Introduction

OpenCrabs est un agent d’orchestration IA auto-hébergé et agnostique du provider qui s’exécute comme un unique binaire Rust. Il automatise votre terminal, votre navigateur, vos channels (Telegram/Discord/Slack/WhatsApp/Trello) et votre codebase, tout en respectant votre vie privée et en vous gardant aux commandes.

11,091 tests sur les providers, les outils, les channels, le TUI, le self-healing et l’automatisation de browser.

Ce qui distingue OpenCrabs

Zéro télémétrie, même pas en opt-in

• OpenCrabs ne téléphone jamais à la maison. Jamais. Pas d’analytics, pas de tracking, pas de statistiques d’utilisation, pas de logs distants, pas de rapports de plantage
• Vos conversations, outils, mémoire, configuration et clés API ne quittent jamais votre machine
• Le seul trafic sortant est celui que vous initiez explicitement : appels d’API LLM, recherches web, commandes GitHub, automatisation du navigateur
• Pas une case de politique de confidentialité : il n’y a aucun code de télémétrie à désactiver, aucun flag d’opt-out, aucun service d’analytics à bloquer. Il n’y a simplement rien à envoyer

Agnostique du provider par conception

• 16 providers intégrés + Custom OpenAI Compatible : Anthropic Claude, OpenAI, Gemini, Xiaomi MiMo, OpenRouter, Qwen (DashScope), MiniMax, Ollama, z.ai GLM, GitHub Copilot, Codex, Codex CLI, OpenCode, OpenCode CLI, Moonshot AI (Kimi), Command Code CLI
• Intégration CLI native: utilisez Claude Code CLI, OpenCode CLI, Codex CLI et Command Code CLI comme providers sans clés API
• Chaîne de fallback persistante: failover automatique sur rate limits ou erreurs, persistance sensible à l’état de santé qui survit aux redémarrages
• Prompt caching sur Anthropic, OpenRouter, Gemini et Qwen DashScope réduit les coûts jusqu’à 95 %
• Override de la fenêtre de contexte: plafonnez ou étendez le contexte de n’importe quel model via la config (le provider OpenCrabs intégré est l’exception : sa fenêtre est fixée à 200k)
• Xiaomi MiMo: plus de 30 models dont la série de reasoning MiMo, provider à clé
• Moonshot AI (Kimi): endpoints du plan API (api.moonshot.ai) et du plan Coding (api.kimi.com), config de reasoning-effort, fenêtre de contexte selon le palier de plan

Multi-Agent Orchestration

• Les sessions sont des agents totalement isolés, chacune avec son propre brain, provider, model, répertoire de travail et historique
• Sous-agents typés : general, explore, plan, code, research avec un accès aux outils adapté
• Orchestration d’équipes : team_create, team_broadcast, team_delete pour des workflows coordonnés
• Overrides provider/model par appel: mélangez les models entre équipes (planifier avec GLM, coder avec Deepseek, relire avec Kimi)
• Protocole A2A: passerelle JSON-RPC 2.0 pour la communication agent-à-agent

Communication native des channels

• Telegram, Discord, Slack, WhatsApp, Trello, intégration bot complète avec DM, groupes et threads
• Messages riches sur Telegram: tableaux natifs, titres, listes, maths via la config rich_messages
• Streaming de brouillons: mises à jour “écrit…” en direct pendant la génération des tokens dans les DM
• Blocs repliables: sections <details>/<summary> pour les sorties longues
• Isolation de session par sujet de forum: chaque sujet dans les supergroupes Telegram a sa propre session
• Réactions Telegram: le bot lit les réactions emoji entrantes et peut répondre par une réaction plutôt qu’un message quand c’est approprié
• Réactions de cadrage (v0.3.61): réactions entrantes lues par sentiment, l’agent s’adresse à l’utilisateur par son prénom
• Réactions en cours de turn (v0.3.61): une réaction pendant un turn en cours s’injecte dans la boucle actuelle au lieu de déclencher un second turn
• Suggestions de suivi (v0.3.69): relances optionnelles tapez-pour-envoyer sur Telegram, Discord, Slack, WhatsApp ; remplir-sans-envoyer dans le TUI
• Réépinglage de la carte de plan Telegram (v0.3.71): réépingler la carte de plan et y replier le texte quand elle est enterrée
• Capture complète de l’historique de groupe (v0.3.73), persiste chaque message de groupe dans l’historique, même des expéditeurs et bots hors allowlist
• Interlocuteur de groupe correct (v0.3.73): ne plus traiter un expéditeur de l’historique du groupe comme l’interlocuteur actuel
• Héritage de session: /new hérite du répertoire de travail de votre session la plus récente
• /goal sur tous les channels: définissez des objectifs autonomes depuis Telegram, Discord, Slack, WhatsApp
• Support vocal: Whisper STT local + Piper TTS, entièrement hors ligne
• Récupération de plantage inter-channels: les requêtes en attente retournent au channel d’origine au redémarrage
• /cowork: créez des workspaces partagés depuis les channels et le TUI
• /rename, /profiles, /cd, gérez sessions, profiles et répertoires depuis n’importe quel channel

Self-Healing et auto-amélioration

• Recursive Self-Improvement (RSI): l’agent analyse ses performances, identifie des schémas et réécrit ses fichiers brain

• Détection des phantom tool calls: détecte quand le model narre des changements sans exécuter d’outils

• Self-heal des phantom calls (v0.3.72): détecte les turns sans outil qui prétendent à des effets critiques (ship/push/tag/release)

• Éditions de config uniquement via config_manager (v0.3.74), l’agent n’édite jamais à la main config.toml/keys.toml ; chaque écriture est validée avant d’atterrir

• Déduplication du brain (v0.3.75): la commande /dedup plus des scans post-écriture et hebdomadaires inter-fichiers empêchent les fichiers brain de dériver vers la duplication, avec approbation par clavier inline Telegram

• Indices de fichiers brain sur échecs d’outils (v0.3.75), des notes brain pertinentes remontent automatiquement quand un appel d’outil échoue ou produit une erreur

• Mémoire proactive (v0.3.76): une mémoire pertinente remonte sans qu’on la demande quand le contexte de conversation correspond au savoir stocké

• Noms de models naturels (v0.3.76): /models opus fonctionne ; les noms familiers se résolvent en IDs de model exacts

• Routage de provider plan/execute (v0.3.76): routez la planification et l’exécution vers des providers/models séparés

• Timeout des thinking-loops (v0.3.78): détecte les boucles de reasoning infinies, déclenche l’application du phantom enforcement avec fallback persistant

• Moteur épistémique (v0.3.78): suivi de croyances avec niveaux de confiance, maillage cognitif OODA/BDI, gate d’Orient avant l’exécution du plan

• Gate de vérification Ralph (v0.3.78): vérification de tâches sensible aux critères avec plafond d’itérations ; les tâches doivent satisfaire les critères d’acceptation déclarés

• Gates de sécurité TOML (v0.3.78): blocklist bash configurable à l’exécution avec hot-reload, rédaction des secrets entre guillemets, vérification des fichiers brain

• Analytics Mission Control (v0.3.78): filtre D/W/M, grille de cartes 3 par ligne, onglets phantom/model/streaming, DB d’événements dédiée

• Onboarding OpenAI TTS (v0.3.78): sélecteur de voix et champ de clé API dans l’assistant d’onboarding

• Installation Homebrew (v0.3.79): brew install opencrabs depuis homebrew-core : binaire précompilé, les deux architectures, sans toolchain Rust

• /restart et /exit (v0.3.79): redémarrez ou arrêtez depuis n’importe quel channel ou le TUI ; réservé au owner sur les channels, annonce avant d’agir

• Circuit breaker de quota (v0.3.79): les providers à quota épuisé reçoivent un breaker à TTL et sont sautés dans les parcours de fallback ; l’épuisement de la chaîne est signalé explicitement

• État des plans entre sessions (v0.3.79): les plans survivent aux frontières de session ; l’exécution isolée des tâches de plan est activée par défaut, Ralph vérifie dans le répertoire propre de la session

• Système de thèmes (v0.5.0): des presets vérifiés, un sélecteur interactif et vos propres thèmes depuis ~/.opencrabs/themes/*.toml ; le truecolor est détecté avec un niveau de repli ANSI-256, et un preset dont le contraste rendrait le texte illisible est refusé

• Mémoire structurelle du code (v0.5.0): tree-sitter construit un index de symboles et de graphe d’appels à côté de l’index textuel, si bien que « qui appelle X » parcourt de vraies arêtes d’appel tandis que les questions conceptuelles gardent la voie textuelle (#1324)

• Transfert de fichier via SSH (v0.5.0): un fichier déposé dans une TUI exécutée sur un hôte distant est récupéré par la connexion déjà ouverte, avec un opencrabs drop-agent côté client (#1289)

• Verdicts de livraison de notify (v0.5.0): session_notify renvoie un résultat d’envoi lisible par machine, les accusés d’injection de profondeur 3 rendent le notify_id vérifiable, et la livraison est redirigée vers la session qui détient le channel à cet instant

• Compaction en arrière-plan (v0.5.0): le résumeur s’exécute hors du tour au lieu de retenir la session pendant son travail

• Masquage du token à l’écriture (v0.5.0): une erreur de provider transportant une URL ne peut plus laisser fuir le token du bot dans un log, quelle qu’en soit l’origine (#1322)

• Userbot Telegram en réception seule (v0.5.0, expérimental): capture MTProto derrière une feature, avec connexion locale par QR/code/2FA ; il stocke le texte autorisé pour consultation et n’agit jamais à la place de l’utilisateur

• Ancrage temporel (v0.5.1): l’agent sait toujours l’heure qu’il est : chaque tour porte un horodatage dans le fuseau horaire de l’utilisateur, et le prompt système reste octet pour octet identique pour le cache du fournisseur (#1516)

• Sessions cron par job (v0.5.1): chaque job programmé obtient sa propre session, afin que deux jobs simultanés ne partagent jamais leur contexte ou leurs fournisseurs (#1511)

• Verrou par globs de skill (v0.5.1): la liste globs: d’une skill peut refuser les appels d’outils sur les fichiers correspondants tant que l’agent n’a pas lu le corps de la skill (#1515)

• Écritures de config validées par la structure (v0.5.1), le garde d’écriture et les suggestions de section de config_manager dérivent désormais du type Config lui-même, pour ne jamais diverger du code publié (#1508)

• Conceptions de plan refusées à l’écriture (v0.5.1), une conception de plan malformée rebondit immédiatement avec les sections manquantes nommées, et une écriture refusée restaure le scaffold au lieu d’effacer le brouillon (#1507)

• Backpressure de budget fournisseur (v0.5.1): un fournisseur qui signale un budget de tokens en sortie déclenche une seule compaction bornée puis une nouvelle tentative, au lieu d’une cascade de 400 (#1518)

• Jetons A2A liés et config réservée au owner (v0.5.1), les jetons A2A sont liés à la gateway qui les a émis, et config.toml/keys.toml passent en mode owner exclusif, les secrets étant purgés des logs

• Mode serveur ACP (v0.5.2): opencrabs acp parle l’Agent Client Protocol via stdio JSON-RPC, de sorte que Zed, MonoCode et tout client ACP pilotent le même brain que vos channels, avec le streaming de la progression et les approbations qui repartent vers l’éditeur (#1540)

• Navigation compatible shadow-DOM (v0.5.2): la résolution des sélecteurs traverse les shadow roots, de sorte que l’automatisation atteint les web components auparavant invisibles pour les outils

• Surface WhatsApp complète (v0.5.2): notes vocales natives, vidéo/sticker/localisation/contact entrants, votes de sondage, récupération de la présence et des media, accusés de réaction, streaming avec édition sur place, messages éphémères, blocage de contacts, épingler/transférer/profil, mises à jour de statut, découverte des newsletters, boutons native flow, historique par conversation

• Tracing en direct et tables natives sur Discord (v0.5.2), les tours longs sont diffusés comme une réponse live tracée, les réponses passent automatiquement en thread, les tables markdown s’affichent nativement et les tours avec outils ne publient plus deux fois la réponse finale (#1603, #1608)

• Sujets de forum Telegram et /clear (v0.5.2): création/renommage de sujets de forum avec liaison de session, et /clear démarre une session fraîche sans l’appel au summariser (#1585)

• Budget de payload du menu de commandes (v0.5.2): le setMyCommands de Telegram rejette silencieusement les corps de requête au-delà de ~7,8 Ko en signalant BOT_COMMANDS_TOO_MUCH ; les descriptions se raccourcissent désormais par paliers pour que tout le menu tienne (#1613)

• Cron déclenché sur condition (v0.5.3): un job exécute un pre-flight check et ne s’exécute que si votre condition est remplie (output non vide, exit code, regex), les runs ignorés coûtent 0 token et un trigger déclenché peut dispatcher un goal vers une session (#233)

• Windows natif (v0.5.3): gestion du shell par plateforme, lecture BOM/UTF-16, fallbacks tilde et cwd, avec une CI qui compile Windows et gate les PR (#627)

• Mémoire épistémique (v0.5.3): les faits de MEMORY.md portent une confidence et un decay (#1643), les sections froides s’archivent d’elles-mêmes et opencrabs memory prune montre ce qui est devenu froid avant d’y toucher (#1657)

• Moteur de thèmes achevé (v0.5.3): chaque widget du TUI résout ses couleurs via le thème, avec un guard de suite contre tout nouveau site ANSI brut, et les thèmes peuvent déclarer un canvas background (#1634)

• Sondages de suggestions WhatsApp (v0.5.3): les ensembles de follow-ups au-delà de la limite native de boutons s’affichent en sondage, et un vote sélectionne l’option (#1616)

• Famille de sessions ACP (v0.5.4): les sessions sont first-class sur la surface ACP : le context meter est restauré au chargement et suit les usage updates, session/load rejoue la transcription et restaure le model de la session, set_model persiste entre processus, le session/set_mode natif applique l’approval policy côté serveur, session/compact pousse, et session/new propose un catalogue de models en direct

• Prise en main interactive du terminal (v0.5.4): !vi/!nano prennent le terminal de façon interactive et le rendent avec la session intacte; terminaux Unix uniquement, Windows conserve la capture par pipe (#1744, #1759)

• Paste & drop universel (v0.5.4): un router d’attachments partagé accepte tout type de fichier au collage ou au dépôt et classifie code, docs, archives et données pour que chacun arrive dans le bon pipeline (#1740, #1743)

• Moteur de recherche Serper (v0.5.4): serper_search ajoute des résultats Google SERP, et le fan-out de web_search déduplique par URL entre engines (#1731)

• Decision cache (v0.5.4): decide_cached répond aux décisions répétées depuis un anneau de réutilisation L1 avec tiers shadow/live et config [decisions] (#1648)

• Coûts rapportés par le provider et une chaîne de timeouts unifiée (v0.5.4), le ledger d’usage préfère le coût réellement rapporté par le provider aux estimations de table (#1707), et les flags de timeout se résolvent [providers.<name>] -> [agent] -> default pour tous les providers (#1688)

• Commandes compilées /architecture et /attach, audit trail optionnel (v0.5.4), les deux commandes sont livrées comme arms compilés, et un audit trail optionnel enregistre ce qui a tourné avec un viewer /audit (#933, #1705)

• Surface native de Discord (v0.5.5) : sondages natifs via send_poll, réponses TTS livrées comme messages vocaux, et commands.toml projeté sur les slash commands natifs pour que vos propres commandes apparaissent dans le sélecteur de Discord (#1848, #1849, #1850)

• Flow groups et governors d’écriture (v0.5.5) : Discord et Slack ouvrent le flow group au début du tour avec une horloge en direct couvrant la réflexion et le texte d’activité en tête de ligne, et un seul governor d’écriture partagé budgète chaque édition et se met en park sur les 429 (#1841, #1843, #1844, #1845, #1807, #1808, #1809, #1910, #1912, #2012)

• /respond_to et /cowork (v0.5.5) : modes respond_to et open par canal dans la configuration, plus les deux commandes pour les définir depuis le canal lui-même (#2014, #2015)

• Discipline de rate limit sur Telegram (v0.5.5) : polls getUpdates et handoffs de handler instrumentés pour le triage des stalls, un plancher d’espacement sub-seconde entre surfaces avec télémétrie d’admission, une pause 429 par chat derrière un seul accesseur Cooldown, et les liens markdown vers des fichiers locaux livrés comme documents (#1927, #1916, #1968)

• Cycle de vie des sessions ACP v1 (v0.5.5) : les cinq méthodes v1 du cycle de vie des sessions sont implémentées et le plan est publié comme une mise à jour de plan v1 native (#1815)

• Pied de dialogue partagé, URLs cliquables, timeline d’onboarding (v0.5.5) : tous les dialogues partagent un seul command footer avec des verbes d’approbation a/r directs, les URLs et les chemins de fichiers sont cliquables, et l’onboarding a été reconstruit en une timeline d’étapes à gauche avec des commandes de configuration directes (#1775, #1772, #1979, #1980, #1981, #1982)

• Retraite des cron one-shot (v0.5.5) : les jobs one-shot se retirent à la livraison au lieu de se redéclencher un an plus tard, chaque exécution livrée porte son run id, et les rapports cron de Discord arrivent en un seul post de forum (#544, #1703, #1851)

• Premier lancement sans configuration (v0.5.11) : une installation neuve arrive directement dans le chat avec le provider intégré déjà provisionné, config.toml et keys.toml créés, et l’agent qui vous salue. L’assistant est optionnel via /onboard ou --onboard (#2079)

• Un premier tour qui ne peut plus interrompre le processus (v0.5.11) : les threads worker de l’agent tournent sur une pile de 16 MiB, donc le premier tour ne déborde plus la pile par défaut (#2080)

• Tags de release conditionnés à un CI vert (v0.5.11) : le workflow de release lit la conclusion du run CI du commit lui-même avant de publier. Un run rouge fait échouer la release, un run encore en cours est attendu, et un commit sans run échoue aussi (#2078)

• Evolve redémarre les bonnes unités (v0.5.11) : le redémarrage planifié cible des noms d’unités résolus au lieu du glob de découverte opencrabs*.service, qui correspondait aussi à l’unité transitoire qui exécute le redémarrage et faisait que systemd arrêtait son propre exécuteur (#2081)

• Les guest queries de Telegram disposent de la surface complète (v0.5.12) : un tag dans un chat où le bot n’a jamais été invité exécute la même surface d’outils, le même bloc de statut en direct et le même rendu rich qu’un tour normal, avec un tour annulable par guest session et du rate limiting (#2087, #2109, #2133, #2135, #2138, #2143)

• Un plan est exigé au-delà d’un seuil de tool calls (v0.5.12) : lorsqu’un tour dépasse un seuil de tool calls, l’agent doit s’arrêter et écrire un plan avant de continuer (#2128)

• Le transcript survit au changement de session (v0.5.12) : la carte des plis est indexée par une ancre stable de role et de timestamp au lieu d’un UUID généré à chaque rendu, donc changer de session et revenir ne replie plus tous les tours que vous aviez ouverts (#2155)

• Les installations headless provisionnent le provider intégré (v0.5.12) : opencrabs run, daemon, agent, acp et cron créent le token intégré sur un home neuf comme le faisait déjà la TUI, tandis que status et doctor restent en lecture seule (#2151)

• Mode de réparation doctor –fix (v0.3.83): lignes cron bloquées, markers périmés et permissions cassées sont réparées sur-le-champ au lieu d’être seulement signalées

• Verrous d’écriture par chemin (v0.3.83): les écritures concurrentes vers un même fichier se sérialisent ; le dernier écrivain ne gagne plus silencieusement

• Isolation de worktree des sous-agents (v0.3.83): chaque agent enfant reçoit son propre worktree et branch, donc un fan-out ne peut pas écraser l’arbre partagé

• Critères d’acceptation sensibles au type (v0.3.83): les critères du plan sont appliqués contre la toolchain que le projet utilise réellement (#1133)

• Vérification de plan consciente du projet (v0.3.83), les plans vérifient avec les commandes propres du projet, pas toujours cargo, et trouvent le projet depuis le dossier de la session

• /stop annule immédiatement (v0.3.83): interrompt pendant le handshake du provider et les backoffs de retry (#1148)

• Reprise de session A2A (v0.3.83): les sessions reprennent par context id, la passerelle est adressée par profile (#1159, #1161)

• Réglages de thinking DeepSeek (v0.3.83): DeepSeek reçoit les paramètres de thinking qu’il lit réellement, plus le traitement des turns à tool-call uniquement

• Corrélation de logs par session_id (v0.3.82): chaque turn ouvre un tracing span portant son session id, et les cron jobs ainsi que le moteur RSI ont les leurs, donc un seul grep reconstruit un turn entier depuis un log quotidien partagé

• Fiabilité du logger (v0.3.82): le logger cesse de perdre des événements et cesse d’écrire dans le terminal du TUI ; une écriture bloquée ne peut plus faire taire le logging de toutes les autres threads

• Fichiers brain de l’utilisateur protégés (v0.3.82): SOUL.md, USER.md et MEMORY.md ne reçoivent jamais de merge depuis l’upstream, et les directives sont routées vers AGENTS.md, qui est toujours chargé

• Unification des sections de config (v0.3.82): l’orthographe historique [gateway] est migrée sur disque vers [a2a], donc un seul nom survit à un aller-retour de reload

• Cache par hash de chunk (v0.3.82): la mémoire saute le ré-embedding des chunks dont le contenu n’a pas changé

• Binaires de pre-release (v0.3.82): cinq cibles de plateforme plus SHA256SUMS, publiés en pre-release continue pour que les contributeurs testent du code non publié sans attendre une tag. Lancé à la demande, pas à chaque push

• Abandon sur rate-limit (v0.3.82): une longue fenêtre de rate-limit Telegram rend la main immédiatement au lieu de parquer l’envoi en file

• Store de mémoire in-tree (v0.3.81): la dépendance qmd est abandonnée ; recherche vectorielle + SQLite FTS5 détenue in-tree

• Chemins d’index externes (v0.3.81): la recherche de mémoire lit des index hors du répertoire du profile, default-deny dans les sessions partagées

• Mermaid en images sur Telegram (v0.3.81): les diagrammes s’affichent en images tandis que les tableaux gardent le formatage natif

• Reasoning Qwen entre les turns (v0.3.81): preserve_thinking, réglages de thinking gated par famille, palier d’effort recommandé par défaut, Qwen hébergé accessible partout

• Correctif de perte de clés keys.toml (v0.3.81), les clés API des providers ne se perdent plus à l’exécution ; les clés empoisonnées s’auto-réparent

• Détection précoce de boucles (v0.3.81): les rondes d’outils répétitives sont interceptées avant que le provider rejette le turn

• Gate du moteur RSI (v0.3.81): RSI autonome désactivé par défaut pour les daemons headless, activez avec rsi_enabled

• Portée du memory_search (v0.3.80): fouillez les logs quotidiens (memory), les fichiers brain (brain), ou les deux (all) ; les fichiers brain sont indexés à l’écriture

• Récupération de mémoire par chunks (v0.3.80): documents découpés en chunks avant embedding pour que les chunks ultérieurs soient cherchables ; rappel classé avec BM25

• Rendu natif Slack (v0.3.80): tableaux et titres arrivent dans la forme propre de Slack au lieu de markdown brut

• Commandes de channel réservées au owner (v0.3.80): commandes et skills personnalisés sont réservés au owner sur le bras catch-all des channels en groupe

• Gates de convergence RSI (v0.3.80): l’auto-amélioration se met en pause à la convergence, recule sur les séries sans amélioration, hache les constats par identité stable

• Gardes de boucle (v0.3.80): gardes de répétition d’annonces et de quasi-correspondances sur tous les outils ; les kills du détecteur de boucle atteignent la chaîne de fallback

• Mode inventaire du navigateur (v0.3.80): browser_find nu énumère chaque élément cliquable de la page

• Mise à jour des templates de fichiers brain (v0.3.80), les templates AGENTS.md, BOOT.md et SOUL.md ont changé ; le seeding n’écrase jamais les fichiers existants, donc faites un diff contre src/docs/reference/templates/ et fusionnez à la main si vous voulez les nouveaux défauts

• Reconstruction du brain système: fichiers brain reconstruits depuis le disque quand ils changent, sans redémarrage

• Découverte proactive d’outils: cherche les outils disponibles avant de prétendre une incapacité

• Analyseur de prompts multilingue (v0.3.67): PromptAnalyzer partagé avec soft-nudge sur TUI et Telegram, 6 packs de langue (EN/ES/FR/ID/PT/RU)

• Mode plan (v0.3.67-v0.3.68): tracks design/checklist, carte de plan persistante, commande /plan <query>, auto-appréciation de l’agent quand l’utilisateur accorde l’autonomie

• Clic-pour-déplier (v0.3.69): clic gauche sur un bloc de tool-call ou de reasoning pour déplier juste ce bloc, en complément de Ctrl+O

• review_gate des skills (v0.3.70): déclaration frontmatter pour les skills critiques qui exigent l’approbation de l’utilisateur avant les effets de bord

• Activation JIT des outils: outils étendus activés à la demande, sans pré-enregistrement

• Auto-réparation de la config: répare automatiquement un config.toml cassé, n’empoisonne jamais la dernière bonne config

• Gestion du budget de contexte: seuils de compaction 65 % souple / 90 % strict avec fallback LLM

• Détection de streams bloqués: une fenêtre glissante de 2048 octets intercepte les motifs répétitifs

• Défense contre le gaslighting: retire les préambules de refus d’outils en cours de turn

• Livraison des résultats de build (v0.3.61): les résultats de rebuild/evolve atteignent celui qui a demandé, à travers les channels et le TUI

Interface terminal (TUI)

• Rendu markdown natif: emphase, listes, liens et éléments de tâche s’affichent directement dans le terminal
• Compteur de tok/s en temps réel: tokens par seconde en direct pendant le streaming
• Affichage de la version (v0.3.73): affiche la version en cours dans l’en-tête du TUI et dans le /help + /usage des channels
• Dépliage de reasoning en 3 états (v0.3.74): clic ou Ctrl+O fait cycler un bloc de reasoning replié → plafonné → complet, pour ne jamais noyer la vue
• En-têtes par turn (v0.3.75): chaque turn reçoit un en-tête de résumé d’une ligne, son raisonnement s’y replie, et les turns sont repliés par défaut pour garder la vue propre
• Groupement des tool calls (v0.3.61): les appels d’outils consécutifs se replient en un seul bloc dépliable, gardant le TUI propre pendant les opérations multi-étapes
• Repli du texte intermédiaire (v0.3.61): le texte de traitement intermédiaire se replie dans le même log en place que les tool calls, donc seule la réponse finale reste visible
• Recherche de sessions: filtre de recherche + défilement de viewport sur toutes les sessions
• Panneaux divisés: sessions parallèles façon tmux avec persistance du layout
• Collage d’images du presse-papiers: collez des images du navigateur ou de n’importe quelle app directement dans le TUI
• Épinglage du plan: le plan actif est épinglé en fin de prompt à chaque turn
• Onboarding piloté par l’agent: configuration initiale personnalisée avec flux guidé
• Boucle autonome /goal: fixez un objectif et l’agent boucle jusqu’à ce qu’un juge LLM dise que c’est fini, avec contrôles pause/resume/status
• Auto-objectifs (v0.3.61): l’agent peut fixer et piloter ses propres objectifs multi-turn via l’outil goal_manage sans que l’utilisateur invoque /goal

Expérience développeur

• Plus de 50 outils intégrés: opérations fichiers, bash, recherche web, exécution de code, automatisation de navigateur, génération d’images, voix, rendu PDF
• Recherche web parallèle unifiée (v0.3.73): web_search, exa_search et brave_search se déploient en parallèle sous un unique outil web_search
• web_scrape: scraping natif d’URL vers markdown avec protection SSRF, crawl de sitemaps, détection de JS-shell et export conscient du profile
• Détection de captcha DDG (v0.3.73): détecte le captcha DuckDuckGo via HTTP 202 + vérification structurelle de formulaire
• Skill /github intégrée: contrôle total du gh CLI pour issues, PR, revues de code, gestion de repo
• Découverte proactive d’outils: l’agent trouve les outils avant de dire “je ne peux pas”
• Système de skills: templates de workflow avec fuzzy-finding, enregistrées automatiquement comme slash commands
• Outils dynamiques: définis à l’exécution via TOML (exécuteurs HTTP + shell)
• Système de projets: sessions dédiées avec overlays de brain par projet, archivage de fichiers et badges couleur
• Édition hashline: édition de fichiers ancrée par hash avec support de lot et détection de collisions
• Mission Control: tableau de bord plein écran avec inbox RSI, log d’activité et planning cron
• RTK auto-download: proxy de 4 Mo inclus pour 53,5 % d’économie de tokens sur plus de 100 commandes
• Protection des fichiers confidentiels: clés SSH, .env, identifiants protégés par défaut
• AGENTS toujours chargé: règles strictes et gouvernance appliquées à chaque turn
• debug_logs piloté par la config (v0.3.71): basculez les logs de debug avec hot-reload, sans redémarrage
• Portée de la rédaction des secrets (v0.3.71): limitez la rédaction à global/groupe/DM avec la commande /redact
• Portée de la rédaction des secrets (v0.3.71): limitez la rédaction à global/groupe/DM avec la commande /redact
• debug_logs piloté par la config (v0.3.71): basculez les logs de debug avec hot-reload, sans redémarrage
• Watchdog tmux (v0.3.71): kill du seul panneau, avis de 30 s, re-attach automatique
• Plan-gate à trois états (v0.3.71): GateDecision avec bash passant à l’approbation dans l’Editing post-init
• ToolHints façon MCP (v0.3.71): modèle de risque pour la classification des outils, pilote le plan gate

Browser Automation

• Support CDP complet: naviguer, cliquer, saisir, screenshot, évaluer du JS, trouver des éléments
• Mode headless ou headed avec screenshots spécifiques par élément
• Persistance des cookies/sessions entre les sessions de navigateur
• Isolation d’onglets par session: pas de piétinement de DOM entre sessions

Découverte des directives de projet (v0.3.59)

OpenCrabs découvre automatiquement les fichiers de règles que d’autres outils de codage IA déposent dans un repo. Pointez l’agent sur n’importe quel dépôt (via /cd, un workspace de channel, ou en le lançant à l’intérieur) et il scanne les conventions livrées par Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode et le standard inter-outils AGENTS.md. Pas de config, pas d’étape d’import.

L’index se reconstruit quand vous faites /cd vers un nouveau répertoire, donc les fichiers de directives sont toujours à jour.

Démarrage rapide

# Installer (Linux/macOS)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
OS=$(uname -s | tr A-Z a-z)
TAG=$(command -v jq >/dev/null 2>&1 && curl -s https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name || curl -s https://api.github.com/repos/opencrabs/opencrabs/releases/latest | grep -o '"tag_name":"[^"]*"' | cut -d'"' -f4)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-${OS}-${ARCH}.tar.gz" | tar xz
./opencrabs

# Ou via Cargo (nécessite Rust 1.94+)
cargo install opencrabs --locked

Auto-update activé par défaut. Désactivez avec [agent] auto_update = false dans ~/.opencrabs/config.toml.

Architecture

┌─────────────────────────────────────────┐
│           OpenCrabs Binary              │
│  (Single 34-36 MB Rust executable)      │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────────┐  │
│  │   TUI       │  │   CLI Daemon    │  │
│  │  (crossterm)│  │  (systemd/launchd)││
│  └─────────────┘  └─────────────────┘  │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Provider Registry         │   │
│  │  15 built-in + Custom OpenAI    │   │
│  │  Sticky fallback chain          │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Tool Layer                │   │
│  │  50+ built-in tools             │   │
│  │  Dynamic tools via TOML         │   │
│  │  JIT activation                 │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Channel Adapters          │   │
│  │  Telegram / Discord / Slack /    │   │
│  │  WhatsApp / Trello / Voice      │   │
│  └────────────────���────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Self-Healing Layer       │   │
│  │  Context budget / Stuck stream  │   │
│  │  Phantom detection / RSI        │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Persistence              │   │
│  │  SQLite + Brain files           │   │
│  │  FTS5 + vector search           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Prochaines étapes

• Installation: Installer et configurer
• Configuration: Toutes les options de config
• Providers: Connectez vos backends LLM
• Channels: Connectez Telegram, Discord, etc.
• Outils: Explorez plus de 50 capacités intégrées
• Self-Healing: Fonctionnalités de résilience
• Multi-Agent: Orchestrez sous-agents et équipes

Communauté et support

• Communauté Telegram: rejoignez le groupe OpenCrabs pour questions, astuces et discussions de release
• Sponsorisez sur GitHub: soutenez le projet et gardez les crabs nourris
• Buy Me a Coffee: soutien ponctuel si OpenCrabs vous a épargné un après-midi

Un bug ou une envie de fonctionnalité ? Ouvrez une issue sur GitHub.

Installation

Five ways to get OpenCrabs running.

Quick install (Linux and macOS)

The fastest path. One command resolves the latest release, checks your platform, verifies the download against the published SHA256SUMS, installs opencrabs and the rtk helper, and installs the system libraries the Linux build needs.

curl -fsSL https://opencrabs.com/install.sh | bash

On Windows, use PowerShell:

iwr -useb https://opencrabs.com/install.ps1 | iex

It installs to /usr/local/bin when that directory is writable, otherwise to ~/.local/bin, and prints the export PATH line when the target is not on your PATH yet. It refuses to install when glibc is older than 2.38 (Ubuntu 24.04+, Debian 13+, Fedora 39+) or when the system uses musl, and it names the package to install instead of failing silently.

Flags go after bash -s -- when you pipe the script:

Both scripts are plain shell and PowerShell, readable before you run them: install.sh and install.ps1.

Option 1 : Homebrew (recommandé sur macOS et Linux)

brew install opencrabs

OpenCrabs is in homebrew-core. Homebrew ships prebuilt bottles for Apple Silicon Macs (macOS 15 and newer) and for Linux amd64 and arm64, so no Rust toolchain is needed there. On an Intel Mac, Homebrew builds it from source instead; use the macos-amd64 release binary if you’d rather skip the build.

Lancez opencrabs après l’installation. Il va directement dans le chat avec son provider intégré déjà actif, donc le crab vous salue et vous pouvez commencer à parler. Lancez opencrabs --onboard quand vous voulez l’assistant de configuration.

Option 2 : Télécharger le binaire (toutes plateformes)

Récupérez un binaire précompilé sur GitHub Releases.

Linux (amd64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-amd64.tar.gz" | tar xz
./opencrabs

Linux (arm64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-arm64.tar.gz" | tar xz
./opencrabs

macOS (arm64 / Apple Silicon)

TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-macos-arm64.tar.gz" | tar xz
./opencrabs

Windows

$tag = (Invoke-RestMethod https://api.github.com/repos/opencrabs/opencrabs/releases/latest).tag_name
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://github.com/opencrabs/opencrabs/releases/download/$tag/opencrabs-$tag-windows-amd64.zip" -OutFile opencrabs.zip -UseBasicParsing
Expand-Archive opencrabs.zip -DestinationPath . -Force
.\opencrabs.exe

Il va directement dans le chat avec son provider intégré déjà actif. Lancez opencrabs --onboard quand vous voulez l’assistant de configuration.

Windows est une plateforme native (v0.5.3) : gestion du shell consciente de la plateforme, lecture BOM/UTF-16 et fallbacks tilde/cwd intégrés, et la CI compile Windows à chaque PR (#627).

Vérifiez votre téléchargement (optionnel) : chaque release publie un fichier SHA256SUMS à côté des tarballs.

Permissions terminal requises. OpenCrabs lit/écrit des fichiers brain, la config et des fichiers de projet. Votre app de terminal doit avoir accès au système de fichiers, sinon l’OS bloque les opérations.

OS	Quoi faire
macOS	Réglages Système → Confidentialité et sécurité → Accès complet au disque → activez votre app de terminal (Alacritty, iTerm2, Terminal, etc.). Si elle n’est pas listée, cliquez sur “+” et ajoutez-la depuis /Applications/. Sans cela, macOS répète « voudrait accéder aux données d’autres apps ».
Windows	Lancez votre terminal (Windows Terminal, PowerShell, cmd) en tant qu’administrateur au premier lancement, ou donnez au terminal l’accès en écriture à %USERPROFILE%\.opencrabs\ et à vos répertoires de projet. Windows Defender peut aussi demander, cliquez sur « Autoriser ».
Linux	Assurez-vous que votre utilisateur possède ~/.opencrabs/ et vos répertoires de projet. Sur les systèmes SELinux/AppArmor, le processus du terminal a besoin d’un accès lecture/écriture à ces chemins. Les terminaux Flatpak/Snap peuvent nécessiter --filesystem=home ou une permission équivalente.

Le /rebuild fonctionne même avec des binaires précompilés, il clone automatiquement le source vers ~/.opencrabs/source/ à la première utilisation, puis compile et fait un hot-restart.

Option 3 : Compiler depuis le source

Nécessaire pour /rebuild, ajouter des outils personnalisés ou modifier l’agent.

Configuration rapide (recommandé)

Le script de configuration détecte automatiquement votre plateforme (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) et installe toutes les dépendances de build + Rust :

# Installer toutes les dépendances
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Cloner et compiler
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Configuration manuelle

Si vous préférez installer les dépendances vous-même :

• Rust stable: Installez Rust. La toolchain stable fonctionne depuis la v0.2.85
• Une clé API d’au moins un provider supporté
• SQLite (intégré via rusqlite)
• macOS: brew install cmake pkg-config
• Debian/Ubuntu: sudo apt install build-essential pkg-config libssl-dev cmake
• Fedora/RHEL: sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake
• Arch: sudo pacman -S base-devel pkg-config openssl cmake

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

OpenCrabs utilise keys.toml au lieu de .env pour les clés API. L’assistant d’onboarding vous aidera à le configurer, ou éditez ~/.opencrabs/keys.toml directement.

Option 4 : Docker

Lancez OpenCrabs dans un conteneur isolé. La compilation prend ~15 min (Rust release + LTO).

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
docker compose -f src/docker/compose.yml up --build

La config, le workspace et la DB de mémoire persistent dans un volume Docker à travers les redémarrages. Les clés API dans keys.toml sont montées dans le conteneur à l’exécution, jamais cuites dans l’image.

Démarrage automatique au boot

Gardez OpenCrabs en marche comme daemon d’arrière-plan qui démarre avec votre système.

Linux (systemd)

The binary writes the unit itself, so the file cannot drift from the version you are running:

opencrabs service install

That writes ~/.config/systemd/user/opencrabs.service with Type=simple and OOMPolicy=continue, then reloads systemd. Start it with opencrabs service start: a user unit does not come back after a reboot unless lingering is enabled (see below), while a system-wide unit is enabled so it does. OOMPolicy=continue matters because the daemon is the parent of every tool call and cron child: without it, one child killed by the OOM killer stops the whole unit and takes every agent lane with it. The unit name carries the profile when you are not on default, as opencrabs-<profile>.service.

On a headless SSH session the per-user systemd bus is often missing, and the command fails with Failed to connect to bus. Enable lingering so the user service runs without a login, or install a system-wide unit instead:

sudo loginctl enable-linger $(whoami)
# or
sudo opencrabs service install

Manage the daemon with opencrabs service start|stop|restart|status, or with systemctl directly.

Vérifiez l’état : systemctl --user status opencrabs | Logs : journalctl --user -u opencrabs -f

macOS (launchd)

cat > ~/Library/LaunchAgents/com.opencrabs.agent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.opencrabs.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/opencrabs</string>
        <string>daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/opencrabs.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/opencrabs.err</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.opencrabs.agent.plist

Mettez à jour le chemin dans ProgramArguments pour correspondre à votre emplacement d’installation.

Windows (Task Scheduler)

1. Win + R → taskschd.msc
2. Créer une tâche de base → Nom : OpenCrabs
3. Déclencheur : Quand j’ouvre une session
4. Action : Démarrer un programme → C:\Users\<vous>\.cargo\bin\opencrabs.exe, Arguments : daemon
5. Dans Properties > Settings, cochez If the task fails, restart every 1 minute

Ou via PowerShell :

$action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.cargo\bin\opencrabs.exe" -Argument "daemon"
$trigger = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "OpenCrabs" -Action $action -Trigger $trigger -Settings $settings

Mettre à jour

• Utilisateurs Homebrew : brew upgrade opencrabs (si vous tapez /evolve sur une installation Homebrew, il délègue à Homebrew, le binaire reste géré par brew, et l’ancien tap est retiré au profit des autobumps de homebrew-core)
• Utilisateurs du binaire : Tapez /evolve dans le TUI pour télécharger la dernière release
• Utilisateurs du source : git pull && cargo build --release, ou tapez /rebuild dans le TUI
• Utilisateurs Docker : docker compose pull && docker compose up -d

Onboarding

A first run does not open the wizard. OpenCrabs goes straight to the chat, with its built-in provider already provisioned and the agent greeting you. The onboarding wizard is opt-in: run opencrabs --onboard, or /onboard from inside a session.

Les vidéos pas à pas se trouvent sur la page Vidéos d’onboarding.

Démarrage rapide (3 minutes)

La voie rapide vous permet de discuter avec l’agent en moins de 3 minutes.

Configuration avancée (7 minutes)

Configuration complète avec Telegram, la voix locale, la vision et la génération d’images.

Déroulement de l’onboarding

L’assistant est une interface TUI pilotée au clavier, en 8 étapes. Naviguez avec les flèches, Tab pour avancer et Esc pour revenir en arrière.

Configuration des channels (étape 4)

L’écran des channels liste 5 intégrations : Telegram, Discord, WhatsApp, Slack, Trello.

• Space active ou désactive un channel
• Enter sur un channel activé ouvre son écran de configuration (token, identifiants, listes d’autorisation)
• Enter sur Continue ou Tab passe à l’étape suivante
• Chaque écran de configuration de channel possède un bouton Test Connection

Consultez Vue d’ensemble des channels pour le guide de navigation complet.

Relancer la configuration

Vous pouvez accéder directement à n’importe quelle étape sans relancer tout l’assistant :

Après l’onboarding, votre agent démarre et se présente. Il lit ses brain files (SOUL.md, AGENTS.md, TOOLS.md) et lance une conversation.

Amorçage

Au tout premier lancement, l’agent passe par une phase d’amorçage :

• Apprend à vous connaître (nom, préférences, manière de travailler)
• Définit son identité (nom, personnalité, emoji)
• Ouvre SOUL.md avec vous pour discuter des valeurs
• Met en place USER.md avec votre profil

Le fichier d’amorçage (BOOTSTRAP.md) se supprime automatiquement une fois terminé.

Migration depuis un autre outil

Vous utilisez déjà ClaudeCode, OpenClaw, Hermes ou un autre harness d’agent IA ? Votre agent peut migrer vos données existantes (mémoire, skills, commandes personnalisées, préférences) vers ses propres brain files, en langage naturel. Aucune manipulation manuelle de fichiers n’est nécessaire.

Cela fonctionne avec tout agent ou harness de code qui stocke sa configuration en local. La migration recherche dans votre système de fichiers les répertoires de configuration de l’autre outil, lit leur contenu et le transpose dans le format de brain files d’OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).

Migration guidée

Si vous souhaitez vérifier ce qui sera migré avant que cela n’ait lieu :

Recherchez mes données ClaudeCode/OpenClaw/Hermes en local (ou tout autre harness d’agent que j’utilisais), auditez une migration vers nos propres brain files, faites-moi un rapport une fois terminé, et exécutez-la quand je confirme et approuve.

L’agent va :

1. Rechercher dans votre système de fichiers les répertoires de configuration de l’autre outil
2. Lire et analyser tous les fichiers pertinents (mémoire, commandes, skills, préférences)
3. Produire un audit indiquant exactement ce qui correspond à quoi
4. Attendre votre confirmation
5. Exécuter la migration et fournir un bilan complet

Migration autonome

Si vous voulez simplement que ce soit fait :

Recherchez mes données d’agent ou de harness existantes en local et migrez tout vers nos propres brain files, sans attendre mon approbation. Lancez-vous, planifiez et exécutez, puis faites-moi un bilan complet une fois terminé.

L’agent saute l’étape d’audit, planifie la migration en interne, l’exécute et vous donne un résumé de tout ce qui a été déplacé.

Ce qui est transposé

Astuce : Lancez la migration juste après l’onboarding, tant que le contexte est frais. L’agent dispose déjà de votre USER.md et de votre SOUL.md issus de l’assistant : il peut donc fusionner intelligemment au lieu d’écraser.

Commandes principales

Modes d’approbation

Contrôlez le niveau d’autonomie de l’agent :

Répertoire de travail

L’agent travaille dans un répertoire de travail pour ses opérations sur les fichiers. Modifiez-le avec :

• La commande /cd dans le chat
• Le sélecteur de répertoire dans le TUI (Tab pour sélectionner)
• L’outil config_manager set_working_directory

Le répertoire de travail est conservé par session. Changer de session restaure automatiquement le répertoire.

Indication de filtre des models (v0.3.78)

Le sélecteur de model de l’onboarding affiche désormais toujours une indication de filtre au-dessus de la liste des models (“Tapez pour filtrer…”). Auparavant, cette indication n’apparaissait qu’après la saisie, et les utilisateurs ne savaient pas que le filtrage était disponible. De plus, un ID de model saisi exactement l’emporte désormais sur une correspondance partielle : si vous tapez claude-opus-4-8 exactement, ce model est sélectionné même si d’autres models contiennent la même sous-chaîne.

Vidéos d’onboarding

Les vidéos de démonstration de l’installation et de l’onboarding d’OpenCrabs sont sur la chaîne YouTube d’OpenCrabs. Chaque système d’exploitation dispose d’une vidéo de démarrage rapide et d’une vidéo de configuration avancée. Cliquez sur une miniature pour la lire ici.

macOS

Install in under 2 minutes (Homebrew)

Advanced setup on macOS (Telegram, voice, images)

Ubuntu/Linux

Install in 3 minutes (one paste)

Advanced setup on Linux (Telegram, voice, images)

Windows

Install in 2 minutes (PowerShell)

Advanced setup on Windows (Telegram, voice, images)

Toutes les vidéos : youtube.com/@OpenCrabs

La page Onboarding présente en texte les parcours pas à pas Démarrage rapide et Avancé.

Configuration

OpenCrabs uses two config files stored at ~/.opencrabs/:

Workspace Layout

~/.opencrabs/
├── config.toml          # Main configuration
├── keys.toml            # API keys (gitignored)
├── commands.toml        # Custom slash commands
├── opencrabs.db         # SQLite database
├── SOUL.md              # Agent personality
├── USER.md              # Your profile
├── MEMORY.md            # Long-term memory
├── AGENTS.md            # Agent behavior docs
├── TOOLS.md             # Tool reference
├── SECURITY.md          # Security policies
├── HEARTBEAT.md         # Periodic check tasks
├── memory/              # Daily memory notes
│   └── YYYY-MM-DD.md
├── images/              # Generated images
├── logs/                # Application logs
└── skills/              # Custom skills/plugins

Provider Configuration

See Provider Setup for detailed provider configuration.

Quick example: add Anthropic:

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

Provider Priority

When multiple providers are enabled, the first one found in this order is used for new sessions:

MiniMax > OpenRouter > Anthropic > OpenAI > Gemini > Custom

Each session remembers which provider and model it was using. Switch providers per-session via /models.

Config Safety (v0.3.74)

A malformed line in config.toml or keys.toml corrupts the whole file and takes the agent down (no provider keys, no bot token, no way back in). v0.3.74 makes that class of failure nearly impossible:

• Config edits via config_manager only: the agent edits config.toml / keys.toml only through the config_manager tool, never with raw file edits. The write path validates the result and refuses anything that would break parsing (#715).
• Guard config-breaking writes: edit_file / write_file writes that would break config.toml / keys.toml are denied outright (#713).
• Re-validate before write: config is re-validated immediately before fs::write in the config_manager write paths (#714).
• Validate keys before snapshot: keys.toml is validated before it is saved as the last-good snapshot, so a bad snapshot can’t poison recovery (#712).

v0.3.79 hardened this further:

• Every config write is atomic (#911): a crash or a concurrent reader mid-write can never observe a half-written config.toml or keys.toml.
• Config loads no longer race on shared state, concurrent reloads can’t interleave and leave a torn config in memory.
• Reload failures are specific: a failed reload says what failed, and a write race is named as the transient condition it is instead of a scary generic error.
• Never select a provider you didn’t configure, fallback and model routing can no longer land on a provider section that doesn’t exist in your config.

Agent Behavior

[agent]
working_directory = "/path/to/default/dir"
thinking = "on"                     # "on", "off", or "budget_XXk"
approval_policy = "auto-always"     # "ask", "auto-session", "auto-always"
max_concurrent = 4                  # max parallel tool calls
context_limit = 200000              # context window cap (tokens)
max_tokens = 65536                  # max output tokens per API call
auto_update = true                  # auto-install releases on startup
silent_compaction = false           # suppress post-compaction personality narration
compaction_notice = false            # show the compaction notice pair; off by default (v0.5.4)
lazy_tools = true                   # JIT tool-schema loading (ships core + tool_search only)
redact_sensitive_data = true        # redact API keys, tokens, passwords, IPs from output
debug_logs = false                  # enable debug file logging (hot-reloads, no restart)
default_provider = "minimax"        # fallback provider when no provider is active (v0.3.62)
default_model = "MiniMax-M2.7"      # fallback model when no model is active (v0.3.62)

Timeout flags resolve per provider first: [providers.<name>] wins over [agent], which wins over the built-in default, and every provider family honours the chain, anthropic and gemini included (v0.5.4, #1688).

Sub-agent and RSI Overrides

Route spawned sub-agents and RSI (self-improvement) cycles to separate providers so they never compete with your main chat for quota:

[agent]
subagent_provider = "minimax"           # provider for spawned sub-agents
subagent_model = "MiniMax-M2.7"         # model for spawned sub-agents
self_improvement_provider = "minimax"   # provider for RSI self-improvement cycles
self_improvement_model = "MiniMax-M2.7" # model for RSI cycles

Channel Configuration

Telegram

[channels.telegram]
enabled = true
token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["123456789"]       # numeric Telegram user IDs
allowed_channels = ["-100123456"]   # restrict to specific group/channel IDs (empty = all)
respond_to = "mention"              # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0           # idle timeout for non-owner sessions
rich_messages = true                # native Telegram rich messages (Bot API 10.1, default since v0.3.64)
silence_group_start = true          # silently ignore /start from non-allowed users in groups
bot_owner = ["123456789"]           # owner IDs (gated commands, /cd hidden dirs, /profiles)

Discord

[channels.discord]
enabled = true
token = "your-discord-bot-token"
allowed_users = ["123456789012345678"]
allowed_channels = ["123456789012345678"]
respond_to = "mention"
session_idle_hours = 24.0

Slack

[channels.slack]
enabled = true
token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"      # Socket Mode token
allowed_users = ["U12345678"]
allowed_channels = ["C12345678"]
respond_to = "mention"
session_idle_hours = 24.0

WhatsApp

[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]      # E.164 format
session_idle_hours = 24.0

Trello

[channels.trello]
enabled = true
token = "your-trello-api-token"
app_token = "your-trello-api-key"
allowed_users = ["memberId1"]
board_ids = ["boardId1", "boardId2"]
poll_interval_secs = 60
session_idle_hours = 24.0

Other Channels (Preview)

Signal, Google Chat, and iMessage are available as preview placeholders:

[channels.signal]
enabled = true
allowed_phones = ["+15551234567"]

[channels.google_chat]
enabled = true
token = "your-google-chat-token"
allowed_users = ["user@example.com"]

[channels.imessage]
enabled = true
allowed_phones = ["+15551234567"]

Cron Defaults

Route cron jobs to cheaper providers so they never compete with your interactive session:

[cron]
default_provider = "minimax"
default_model = "MiniMax-M2.7"

Memory and Embeddings

[memory]
vector_enabled = true

[memory.embedding]
url = "https://api.openai.com/v1"
model = "text-embedding-3-small"
# api_key loaded from keys.toml: [providers.memory_embedding] api_key = "sk-..."
# dimensions = 1536  # auto-detected from first API response if unset

When [memory.embedding] is not set, embeddings are generated locally via the embeddinggemma-300M GGUF model (~300MB download, ~2.9GB RAM). Setting [memory.embedding] with an API endpoint eliminates the local model overhead.

To index your own docs (or an entire scraped docs site) into memory search, see Memory System → External Index Paths for the full knowledge-base workflow.

Brain Files

[brain]
strip_empty_sections = true
default_cap = 500

[brain.caps]
SOUL.md = 300
AGENTS.md = 800

Browser

[browser]
cdp_endpoint = "http://localhost:9222"

To start a standalone Chromium with CDP enabled:

chromium --remote-debugging-port=9222 --headless --no-sandbox

A2A (Agent-to-Agent) Gateway

[a2a]
enabled = false
bind = "127.0.0.1"
port = 18790
allowed_origins = ["https://your-app.com"]
# api_key = "your-secret-key"  # Bearer token for incoming requests

Daemon Mode

[daemon]
health_port = 8080

OpenCrabs runs in two modes: TUI (interactive terminal UI with chat) and Daemon (headless background service for channels + cron). For any one profile, run only one at a time. The TUI always wins: opening it while a daemon runs shuts the daemon down and takes over the channels.

For full service lifecycle management (TUI vs Daemon comparison, opencrabs service install/start/stop, profile-aware services, OPENCRABS_PROFILE env var, troubleshooting), see the CLI Commands reference.

Image Generation and Vision

[image.generation]
enabled = true
model = "gemini-3.1-flash-image-preview"

[image.vision]
enabled = true
model = "gemini-3.1-flash-image-preview"
provider = "openrouter"           # bypasses enabled gate for vision-only providers (v0.3.63)

Vision analysis automatically scans all enabled providers (Google, OpenRouter, OpenAI-compatible, Anthropic) before returning an error. No configuration needed.

Voice Provider Fallback

STT and TTS providers support automatic failover via fallback_chain. When the primary returns a 5xx, fails a liveness probe (Voicebox), or is otherwise unreachable, the dispatcher walks the chain in order and tries each entry that has the credentials/config it needs.

[providers.stt]
fallback_chain = ["groq", "openai_compatible", "local"]

[providers.tts]
fallback_chain = ["openai_compatible", "openai", "local"]

Empty or omitted chain means “use the default priority order with the primary removed.”

TOML Bash Blocklist (v0.3.78)

A new TOML-driven bash blocklist provides runtime-configurable safety gates for shell commands. The blocklist lives in a TOML file and defines patterns that the agent’s bash tool will refuse to execute:

# safety.toml (example)
[bash_blocklist]
patterns = ["rm -rf /", "dd if=", "mkfs", ":(){ :|:& };:"]

• Patterns are matched against the command string before execution
• The blocklist reloads on file change (no restart needed)
• Configurable per-profile, so different environments can have different safety gates
• Blocked commands return a clear error explaining which pattern matched

This replaces hardcoded safety checks with a user-extensible system. You can add project-specific dangerous commands without code changes.

Safety TOML Reload (v0.3.78)

All safety-related TOML files (bash blocklist, brain verification rules) now hot-reload on change. Edit the file and the new rules take effect immediately on the next tool call. No restart, no /reload, no config manager dance.

CLI Commands

OpenCrabs a une CLI complète avec plus de 20 sous-commandes pour gérer chaque aspect de l’agent.

Utilisation

opencrabs [COMMAND] [OPTIONS]

Commandes

Flags de configuration

Raccourcis clavier (TUI)

Invite de mise à jour au démarrage

Quand une nouvelle version est disponible, un dialogue centré apparaît sur l’écran de splash pour accepter (Entrée) ou passer (Échap). Accepter déclenche /evolve automatiquement. Après la mise à jour, le binaire redémarre et le splash affiche la nouvelle version.

Commandes de channel

Le /doctor, /help, /usage, /evolve, /restart, /exit et les commandes système fonctionnent directement sur Telegram, Discord, Slack et WhatsApp sans passer par le LLM. Elles s’exécutent instantanément et renvoient les résultats dans le channel.

Le /restart et le /exit s’annoncent avant d’agir, parce qu’une fois le processus disparu, il ne reste rien pour signaler un échec. Les deux sont réservés au owner, comme chaque commande qui modifie le processus en cours. Le /exit est l’unique commande sans retour depuis le chat, la récupération nécessite l’accès à la machine où tourne OpenCrabs.

Depuis la v0.3.80, un stop parlé est aussi respecté, dire au bot d’arrêter en langage naturel fonctionne sur les channels et dans le TUI, pas seulement le mot sec « stop ».

Toute la logique de commandes de channel est centralisée dans src/channels/commands.rs (847 lignes), un handler partagé qui élimine la logique dupliquée à travers 5 implémentations de channel. Chaque channel délègue à try_execute_text_command() pour un comportement cohérent.

Le /evolve sur les channels s’exécute maintenant directement (télécharge + installe le binaire) sans demander d’aller-retour LLM. Auparavant il passait par l’agent.

Mode chat

# Par défaut: lancer le TUI
opencrabs

# Identique à ci-dessus
opencrabs chat

Mode agent

Mode non interactif pour le scripting et l’automatisation :

# Chat interactif multi-turn
opencrabs agent

# Mode message unique
opencrabs agent -m "What files changed today?"

Mode daemon vs TUI

OpenCrabs tourne dans un de deux modes. Choisissez celui qui convient à la machine. Pour un profile donné, n’en lancez qu’un à la fois.

Pourquoi pas les deux à la fois ?

Une credential de bot (ex. un token Telegram) ne peut tenir qu’un seul poll getUpdates actif. Si un daemon et un TUI possèdent tous deux le token du même profile, ils se battent (HTTP 409) et le channel tombe.

Le TUI gagne toujours

Quand vous ouvrez le TUI pendant qu’un daemon du même profile tourne, le TUI ferme d’abord ce daemon, reprend les channels et affiche un banner pour le dire. Vos channels étaient déjà configurés, donc ils reprennent simplement, sans reconnexion. Le daemon reste éteint jusqu’à ce que vous le relanciez (opencrabs service start, ou relancez opencrabs daemon).

Sur une machine où le daemon tourne habituellement, le flux quotidien est : ouvrez opencrabs quand vous voulez vous y mettre ; fermez le TUI et opencrabs service start quand vous le voulez à nouveau headless.

Démarrage auto au boot

• Daemon: utilisez l’installeur de service (opencrabs service install) ; il câble systemd (Linux) / launchd (macOS) pour démarrer au boot et redémarrer après un plantage. C’est la configuration always-on recommandée.
• TUI: pour que l’interface terminal s’ouvre automatiquement à la connexion, utilisez un autostart de terminal/desktop, pas l’installeur de service :
  • Desktop Linux : déposez un fichier .desktop dans ~/.config/autostart/ avec Exec=x-terminal-emulator -e opencrabs.
  • macOS : Réglages Système > Général > Éléments de connexion > ajoutez un script .command qui lance opencrabs.
  • VPS par SSH : tournez dans tmux/screen et rattachez-vous. Sur un VPS headless, vous voulez généralement le daemon, pas le TUI.

Fortement recommandé pour les utilisateurs quotidiens. Si vous comptez utiliser OpenCrabs tous les jours, demandez-lui de s’installer comme service système. Dites simplement « installe-toi pour démarrer avec mon ordinateur » ou « retire le service de démarrage auto ». L’agent gère la mise en place et la suppression launchd (macOS) ou systemd (Linux) automatiquement pour vous.

Garder le TUI actif sur un VPS (tmux)

Si vous voulez le TUI interactif complet toujours disponible sur un serveur distant (pas le daemon headless), tmux est la solution. Votre session survit aux déconnexions SSH, à la veille du laptop et aux connexions capricieuses.

1. Installez tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Trouvez où opencrabs est installé

which opencrabs

# Si cela ne renvoie rien, cherchez tout le système de fichiers
find / -name "opencrabs" -type f 2>/dev/null

3. Démarrez une session tmux nommée

tmux new -s opencrabs

4. Lancez opencrabs dedans

opencrabs

5. Détachez (opencrabs continue de tourner)

Pressez Ctrl+B puis D. Vous pouvez maintenant fermer SSH et opencrabs continue de tourner.

6. Rattachez-vous plus tard

tmux attach -t opencrabs

C’est tout. Revenez de n’importe quelle machine, rattachez-vous, et reprenez où vous en étiez. Si vous n’avez besoin que des channels (Telegram, Discord, Slack, WhatsApp) en headless sans le TUI, le daemon convient mieux : opencrabs service install && opencrabs service start.

Endpoint de santé

Ajoutez au config.toml pour exposer un health check :

[daemon]
health_port = 8080

Ensuite GET http://localhost:8080/health renvoie 200 OK avec un statut JSON. Utile pour un watchdog systemd, des moniteurs d’uptime ou des load balancers.

Gestion du service

Installez OpenCrabs comme service système (launchd sur macOS, systemd sur Linux) :

opencrabs service install
opencrabs service start
opencrabs service stop
opencrabs service restart
opencrabs service status
opencrabs service uninstall

Services sensibles au profile

Chaque profile reçoit son propre service indépendant :

# Installer un profile précis comme service
opencrabs -p hermes service install
opencrabs -p hermes service start

# Chaque profile reçoit son propre nom de service
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Gérer indépendamment
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Plusieurs profiles peuvent tourner comme services daemon simultanés avec isolation complète.

Variable d’environnement OPENCRABS_PROFILE

Définissez OPENCRABS_PROFILE=hermes pour sélectionner un profile sans le flag -p. Utile pour les services systemd, les cron jobs et le mode daemon.

Dépannage : le daemon ne remonte pas

Si opencrabs service status dit stopped :

1. Avez-vous ouvert le TUI ? Ouvrir opencrabs éteint délibérément le daemon pour que la session interactive possède les channels. Le daemon reste éteint jusqu’à ce que vous relanciez opencrabs service start.
2. Les anciennes builds peuvent encore avoir Restart=on-failure au lieu de Restart=always. Régénérez l’unit avec opencrabs service install (puis service start) pour adopter la politique de redémarrage permanent.
3. Config, clés, commandes et outils se rechargent à chaud à l’exécution. Éditer config.toml ou keys.toml ne nécessite jamais de redémarrage du daemon. Si un changement ne prend pas effet, cherchez dans les logs une ligne ConfigWatcher: reloaded plutôt que de redémarrer.

Gestion du cron

# Lister tous les cron jobs
opencrabs cron list

# Ajouter un nouveau cron job
opencrabs cron add \
  --name "Daily Report" \
  --cron "0 9 * * *" \
  --tz "America/New_York" \
  --prompt "Check emails and summarize" \
  --provider anthropic \
  --model claude-sonnet-4-20250514 \
  --thinking off \
  --deliver-to telegram:123456

# Remove a cron job (accepts name or ID)
opencrabs cron remove "Daily Report"

# Enable/disable (accepts name or ID)
opencrabs cron enable "Daily Report"
opencrabs cron disable "Daily Report"

Raccourcis clavier du TUI

Troubleshooting

Common issues and how to fix them.

Windows Defender Blocking OpenCrabs

Windows Defender may flag opencrabs.exe as suspicious because it’s an unsigned binary that executes shell commands and makes network requests. This is a false positive.

Add an exclusion:

1. Open Windows Security → Virus & threat protection
2. Virus & threat protection settings → Manage settings
3. Exclusions → Add or remove exclusions
4. Add an exclusion → File → select opencrabs.exe

Or via PowerShell (admin):

Add-MpPreference -ExclusionPath "C:\path\to\opencrabs.exe"

If SmartScreen blocks the first run, click More info → Run anyway.

Binary Won’t Start or Crashes

Startup Errors

Run with debug logging to see what’s failing:

opencrabs -d chat

Logs are written to ~/.opencrabs/logs/.

Download a Previous Version

If the latest release crashes on your machine, download a previous working version from GitHub Releases:

# List all releases
gh release list -R opencrabs/opencrabs

# Download a specific version
gh release download v0.2.66 -R opencrabs/opencrabs -p "opencrabs-*$(uname -m)*$(uname -s | tr A-Z a-z)*"

/evolve: Update & Rollback

/evolve downloads the latest release from GitHub and hot-swaps the binary. It has built-in safety checks:

1. Download: Fetches the platform-specific binary from GitHub Releases
2. Pre-swap health check: Runs opencrabs health-check on the new binary (10s timeout). If it fails, the new binary is deleted and your current version stays untouched.
3. Backup: Creates a backup at <binary-path>.evolve_backup
4. Atomic swap: Replaces the current binary
5. Post-swap health check: Verifies the swapped binary works. If it fails, auto-rolls back to the backup.
6. Restart: exec()-restarts into the new version
7. Brain update prompt: After restart, your crab announces the new version, diffs brain templates against your local files, and offers to update them

If /evolve Fails

The most common reason is the health check caught an issue, your current version stays safe. If something went wrong after the swap:

# Restore the backup manually
cp /path/to/opencrabs.evolve_backup /path/to/opencrabs
chmod +x /path/to/opencrabs

Cargo Install Fallback

When /evolve uses cargo install (building from source), it tries the stable toolchain first. If that fails, it automatically falls back to cargo +nightly. The progress message shows which toolchain succeeded.

Check-Only Mode

The agent can check for updates without installing:

/evolve check_only=true

Bash Tool Safety

The bash tool includes a hard command blocklist that prevents catastrophic commands even if accidentally approved:

• rm -rf /, sudo rm -rf .
• mkfs, dd to /dev/
• Fork bombs
• /etc overwrites, /proc writes
• Sensitive file exfiltration
• Crypto mining commands

These are blocked at the tool level: no configuration needed.

Older CPUs (Pre-2011 / No AVX)

Some features require AVX/AVX2 instructions. Since v0.2.67, OpenCrabs detects CPU capabilities at runtime and automatically hides unavailable options in the onboarding wizard.

What’s Affected

Symptoms

• Local STT option doesn’t appear in /onboard:voice: your CPU lacks AVX2
• Local TTS (Piper) should always be available: no CPU restrictions, works on machines as old as 2007
• Memory search falls back to text-only FTS silently
• Crash with “illegal instruction” on very old CPUs

Fix: Build from Source with CPU Targeting

# For your specific CPU (best performance)
RUSTFLAGS="-C target-cpu=native" cargo build --release

# For Sandy Bridge (AVX but no AVX2)
RUSTFLAGS="-C target-cpu=sandybridge" cargo build --release

macOS with Apple Silicon

Local STT uses Metal GPU acceleration on macOS, no CPU flags needed. Works out of the box on M1/M2/M3/M4.

Config Issues

Config Won’t Load

If config.toml has a syntax error, OpenCrabs will fail to start. Restore from backup:

# Check if a backup exists
ls ~/.opencrabs/config.toml.backup

# Restore it
cp ~/.opencrabs/config.toml.backup ~/.opencrabs/config.toml

Or reinitialize with defaults:

opencrabs init --force

Warning: --force overwrites your config. Back up keys.toml first, it contains your API keys.

Manual Backup

Always keep a backup of your critical files:

cp ~/.opencrabs/config.toml ~/.opencrabs/config.toml.backup
cp ~/.opencrabs/keys.toml ~/.opencrabs/keys.toml.backup
cp ~/.opencrabs/commands.toml ~/.opencrabs/commands.toml.backup

RSI Has Never Run

Mission Control shows ⚠ RSI has never run: N tool event(s) recorded and unprocessed even though rsi_enabled = true is set.

Most common cause: self_improvement_provider is misspelled. Its value is the bare provider section name, no custom: prefix, no model appended:

[providers.custom.glm-53-max]              # the name is "glm-53-max"

[agent]
self_improvement_provider = "glm-53-max"   # ✅ not "custom:glm-53-max"
self_improvement_model = "..."             # the model goes in its own key

Checklist:

1. The provider value matches the config section name exactly ([providers.custom.moonshotai] → "moonshotai").
2. No custom: / custom. / custom/ prefix anywhere in a provider reference.
3. The model is in its own key (self_improvement_model), never appended to the provider.
4. Restart after fixing: Mission Control confirms cycles on the next run.

Fixed at source in opencrabs#1314: current main normalises misspelled values with a warning. Released versions fail silently, which is exactly why the spelling matters.

Channel Issues

Telegram

Bot not responding:

1. Verify token from @BotFather is in keys.toml
2. Check your numeric user ID is in allowed_users
3. If respond_to = "mention", you must @mention the bot in groups

Regenerate bot token:

1. Open @BotFather on Telegram
2. /mybots → select bot → API Token → Revoke
3. Copy new token to keys.toml under [channels.telegram]
4. Restart OpenCrabs

Re-setup from scratch: Run /onboard:channels in the TUI.

Telegram Won’t Connect / Reconnect

If the Telegram bot stops responding or you need to re-link it, re-run the channels setup and re-confirm the token + your numeric user ID.

Fix:

1. Run /onboard:channels (TUI: opens the wizard; on a channel: the agent walks you through it).
2. Paste your bot token again if it’s missing (get it from @BotFather).
3. Paste your numeric user ID and hit Enter to confirm.
4. If the bot sends you a message on Telegram, it worked.

On a channel you can do it in one line: /onboard:channels telegram <BOT_TOKEN> <YOUR_NUMERIC_ID>.

Why you have to provide your numeric ID: Telegram’s Bot API exposes only the bot’s identity from a token (via getMe), it has no way to reveal who created the bot in BotFather. A bot only learns a human’s ID when that human messages it. The onboarding wizard auto-detects your ID via getUpdates when you leave the field blank, but that only works if (a) you’ve already messaged the bot and (b) the bot isn’t already running and consuming those updates, which is exactly the case during a reconnect. So on reconnect, message the bot first, or just paste the ID (get it from @userinfobot).

WhatsApp

QR code / session expired:

WhatsApp sessions are stored at ~/.opencrabs/whatsapp/session.db. To reconnect:

# Delete the session file
rm ~/.opencrabs/whatsapp/session.db

# Re-pair via onboarding
opencrabs chat --onboard

Or press R on the WhatsApp onboarding screen to reset and get a fresh QR code.

Messages not received:

• Verify phone number is in allowed_phones using E.164 format: "+15551234567"
• Empty allowed_phones = [] means accept from everyone

WhatsApp Won’t Connect / Wrong Number Replying

Each OpenCrabs instance supports one WhatsApp account (one companion device). If you connected multiple numbers or the wrong number is replying, you need a full reset. The bot always uses the last number you connected.

Critical: Always reset the connection before connecting a new number. OpenCrabs only keeps the last paired number.

Full reset steps:

1. Remove ALL linked devices from WhatsApp. Open WhatsApp on your phone, go to Settings > Linked Devices, and remove every device in the list. Don’t bother hunting for the opencrabs one. A stale device left over from an earlier pairing is the usual reason the old number keeps replying, so the reliable fix is to clear them all and start fresh.
2. Reset the connection in OpenCrabs: in the TUI or from a channel, go to /onboard:channels and press R to reset the WhatsApp connection. Wait for confirmation that the reset is complete.
3. Re-pair from scratch: after the reset is confirmed, go to WhatsApp > Settings > Linked Devices > Link a Device and scan the new QR code shown by OpenCrabs.

If the bot still shows the old number after resetting, make sure you completed step 1 (removing the device from WhatsApp) before step 2.

Common issues:

Discord

Bot not receiving messages:

1. Ensure Message Content Intent is enabled in Discord Developer Portal → Bot settings
2. Required intents: gateway, guild_messages, direct_messages, message_content
3. Use the bot token (starts with MTk...), not the application ID

Regenerate token: Discord Developer Portal → Bot → Regenerate Token

Slack

Both tokens required:

• Bot token (xoxb-...): For sending messages
• App token (xapp-...): For Socket Mode (receiving events)

Without the app token, the bot can send but not receive messages.

Socket Mode: Must be enabled in app settings → Features → Socket Mode → ON

Trello

Setup:

1. Get API key: trello.com/app-key
2. Generate token from the same page
3. Add board_ids to config: the bot only monitors listed boards
4. Set poll_interval_secs > 0 to enable polling (default 0 = disabled)

General: Re-run Channel Setup

For any channel issues, re-run the onboarding wizard:

opencrabs chat --onboard

Or type /onboard:channels in the TUI.

Agent Hallucinating Tool Calls

If the agent starts sending tool call approvals that don’t render in the UI (meaning it believes it executed actions that never actually ran) the session context has become corrupted.

Fix: Start a new session.

1. Press / and type sessions (or navigate to the Sessions panel)
2. Press N to create a new session
3. Continue your work in the fresh session

This reliably resolves the issue. A fix is coming in a future release.

Claude Code CLI Refuses to Run as Root (VPS, Docker)

Symptom: the claude_cli provider is enabled and claude is authenticated, but every request fails as soon as it spawns. In the log the CLI exits immediately with a message about --dangerously-skip-permissions not being allowed for root, or the first spawn hangs waiting on a prompt nobody can answer.

Cause: OpenCrabs runs the CLI headless with --dangerously-skip-permissions (it owns tool execution itself, so the CLI never asks). Claude Code refuses that flag when the process runs as root unless it believes it is inside a sandbox, and on a fresh install it also wants a one-time interactive acknowledgement of that mode. A VPS or container where OpenCrabs runs as root hits both.

Fix: put the acknowledgement and the sandbox marker in the CLI’s own settings file, ~/.claude/settings.json for the user OpenCrabs runs as (/root/.claude/settings.json on a root box):

{
  "permissions": { "defaultMode": "bypassPermissions" },
  "skipDangerousModePermissionPrompt": true,
  "env": { "IS_SANDBOX": "1" }
}

Merge these keys into the file if it already exists (keep model, theme, and the rest). The CLI reads settings.json on every invocation, so no OpenCrabs restart is needed; the next spawn goes through. Verify as the same user:

echo "say OK" | claude -p --dangerously-skip-permissions

IS_SANDBOX=1 only tells Claude Code that the root check may be skipped. It does not sandbox anything, so keep the box firewalled the way you would for any root agent. On a desktop where OpenCrabs runs as your own user none of this is required.

Daemon Stays Down

Si opencrabs service status dit stopped :

1. Avez-vous ouvert le TUI ? Ouvrir opencrabs éteint délibérément le daemon pour que la session interactive possède les channels. Le daemon reste éteint jusqu’à ce que vous relanciez opencrabs service start.
2. Les anciennes builds peuvent encore avoir Restart=on-failure au lieu de Restart=always. Régénérez l’unit avec opencrabs service install (puis service start) pour adopter la politique de redémarrage permanent.
3. Config, clés, commandes et outils se rechargent à chaud à l’exécution. Éditer config.toml ou keys.toml ne nécessite jamais de redémarrage du daemon. Si un changement ne prend pas effet, cherchez dans les logs une ligne ConfigWatcher: reloaded plutôt que de redémarrer.

For full daemon/service documentation, see CLI Commands: Daemon Mode vs TUI.

Local STT (Speech-to-Text)

Since v0.2.67, local STT uses rwhisper (candle, pure Rust) instead of whisper-rs/ggml. On macOS, it uses Metal GPU acceleration automatically.

Models

Models download automatically from HuggingFace on first use.

Common Issues

Local STT option not showing in wizard: Your CPU lacks AVX2. Use API mode (Groq Whisper) instead, or build from source with RUSTFLAGS="-C target-cpu=native".

“No audio samples decoded”: Audio file is corrupt or unsupported format. Supported: OGG/Opus, WAV.

Transcription hangs: Times out after 300 seconds. Try a smaller model (quantized-tiny).

Model download fails: Check network connection. Models are fetched from HuggingFace.

Audio too short: Messages under 1 second are automatically padded to prevent tensor errors.

Disabling

[voice]
stt_enabled = false

Local TTS (Text-to-Speech)

Requirements

• Python 3 must be installed and in PATH
• Piper installs automatically in a venv at ~/.opencrabs/models/piper/venv/

Voices

Common Issues

“python3 -m venv failed”: Install Python 3. On Ubuntu: sudo apt install python3 python3-venv. On macOS: brew install python3.

“pip install piper-tts failed”: Network issue or pip corrupted. Fix pip first:

python3 -m pip install --upgrade pip

Telegram voice messages show no waveform: This was fixed in v0.2.64, audio is now properly encoded as OGG/Opus (RFC 7845). Update to latest version.

Voice preview not playing: Preview uses afplay (macOS), aplay (Linux), or powershell (Windows). Ensure audio output is available.

Re-setup

Run /onboard:voice in the TUI to reconfigure STT/TTS mode and re-download models.

Disabling

[voice]
tts_mode = "off"

Local Embeddings (Memory Search)

The memory search engine uses a ~300 MB embedding model (llama.cpp) for semantic search. It requires AVX on x86 CPUs.

Fallback

If embeddings can’t initialize (no AVX, download failed, disk full), memory search falls back to FTS-only (keyword matching). It still works, just less semantic.

Fix for Older CPUs

Build from source with CPU targeting (see Older CPUs above).

Model Location

Models are stored in ~/.local/share/opencrabs/models/ (platform-specific data directory).

Database Issues

Location

• Main database: ~/.opencrabs/opencrabs.db (SQLite + WAL)
• WhatsApp session: ~/.opencrabs/whatsapp/session.db

Database Corruption

SQLite with WAL mode is very resilient, but if corruption occurs:

# Back up the corrupted file first
cp ~/.opencrabs/opencrabs.db ~/.opencrabs/opencrabs.db.corrupt

# Reinitialize (WARNING: loses all history)
opencrabs db init

Migration Errors

The database automatically migrates on startup (11 migrations). If migrating from an older version with sqlx, the transition is handled automatically, no manual steps needed.

Building from Source

Quick Setup

curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/scripts/setup.sh | bash
git clone https://github.com/opencrabs/opencrabs.git && cd opencrabs
cargo build --release

Build Without Voice (Smaller Binary)

cargo build --release --no-default-features --features telegram,whatsapp,discord,slack,trello

Feature Flags

Debug Mode

Run with -d for verbose logging:

opencrabs -d chat

Logs go to ~/.opencrabs/logs/ with 7-day retention.

Supported AI Providers

OpenCrabs supports 15 built-in providers + Custom OpenAI Compatible. Switch between them at any time via /models in the TUI or any channel.

How It Works

• One provider active at a time per session: switch with /models
• Per-session isolation: each session remembers its own provider and model. Changing provider in the TUI does not affect other active sessions (Telegram, Discord, Slack)
• Fallback chain: configure automatic failover when the primary provider goes down
• Models fetched live: no binary update needed when providers add new models
• Function calling detection: OpenCrabs detects when a model doesn’t support tool use and warns you with a model switch suggestion, rather than silently failing
• tool_choice: "auto": sent automatically for OpenAI-compatible providers when tools are active, enabling function calling on models that require explicit opt-in
• vision_model works on ANY provider: add vision_model = "..." to any built-in or custom provider block and the agent routes incoming images through that model on the same endpoint. No second API key, no Gemini dependency. See Image Generation & Vision for the full two-path setup

Custom Provider Onboarding (v0.3.24)

Adding a custom OpenAI-compatible provider is now smoother:

• Paste-by-default: Ctrl+V / Cmd+V on the API key field pastes immediately, no need to tab into the field first
• Enter-to-load: type a model name not in the fetched list and press Enter, it’s added to the list and selected
• Field refresh: saved values (base URL, API key, model list) appear instantly without restarting the dialog

Provider Registry (v0.3.34)

All provider resolution now routes through a single registry source of truth: no more hardcoded if-else ladders scattered across the codebase. The registry correctly enforces api_key requirements for API providers (Anthropic, OpenAI, GitHub Copilot, Gemini, OpenRouter, MiniMax), so resolution skips them cleanly when keys are missing instead of silently falling back. Adding a new provider is now a one-file change.

Retry & Fallback Overhaul (v0.3.36)

The provider retry and fallback system was rebuilt for reliability:

• Patient backoff: defaults changed from 100ms hammering to 1s / 2s / 4s / 8s, giving rate-limited endpoints time to recover
• In-place rate limit retry: hits 3 retries on the same provider before falling through the fallback chain, preventing unnecessary provider switches
• Full fallback chain on any HTTP error: previously only 5xx/429 triggered fallback; now any HTTP error walks the chain
• Fail fast on hard-down endpoints: DNS failures and connection refused bail immediately instead of wasting retries
• Retry events surfaced to user: each retry shows as RetryAttempt 1/3 - rate_limit_exceeded so you always know what’s happening
• Transient 4xx HTML pages retried: Cloudflare/nginx error pages that look like 4xx but are actually transient infra issues are now retried

Qwen Cache Auto-Enable (v0.3.30)

Custom providers targeting Qwen-shaped endpoints (base URLs containing dashscope, aliyun, aliyuncs, dialagram, or models prefixed with qwen-*) automatically get ephemeral cache_control markers on the system prompt, last streaming message, and last tool call. Zero-config cost savings for Qwen custom providers, no API key or flag needed.

Qwen Tool-Call Leak Strip (v0.3.35)

Qwen models sometimes emit bare JSON tool-call objects like {"name":"bash","arguments":{"command":"ls"}} directly in the content text instead of through the proper tool-call API. A new bare_tool_call_extractor detects and strips these leaks so they don’t appear as raw JSON in the chat output.

/models Picker (v0.3.30)

The /models command now surfaces every known provider including unconfigured ones, marked with a 🔒 lock icon and setup help text. This helps users discover available providers without needing to know which ones need API keys. Custom providers with no configured models show a helpful empty-state message instead of an inert button.

OpenRouter Reasoning

For models that support extended reasoning (e.g. Qwen 3.6 Plus), OpenCrabs sends include_reasoning: true automatically when using OpenRouter. Thinking/reasoning output is displayed in collapsible sections:

▶ Thinking... (click to expand)
  The user wants to refactor...

Reasoning text wraps to screen width instead of truncating.

See Provider Setup for configuration details and API key setup.

AI Provider Setup

OpenCrabs supports 15 providers (14 built-in + Custom OpenAI-Compatible). Configure them through the onboarding wizard or manually via config.toml and keys.toml at ~/.opencrabs/.

Setup via Onboarding Wizard

The fastest way to configure a provider is the interactive wizard. Run /onboard:provider (or /onboard and navigate to step 3).

Keyboard Navigation

Live-Fetch Providers (recommended)

For providers with a /v1/models API endpoint, the wizard fetches the model list live after you enter your API key.

Supported: Anthropic, OpenAI, OpenRouter, Gemini, MiniMax, Qwen (DashScope), Ollama, z.ai GLM

Flow:

1. Use ↑/↓ to select your provider (e.g. OpenRouter)
2. Press Enter: advances to the API key field
3. Paste your API key (e.g. sk-or-...)
4. Press Enter: triggers a live fetch from the provider’s /v1/models endpoint
5. Use ↑/↓ to browse models, or type to filter (case-insensitive substring match)
6. Press Enter on your chosen model: saves config and advances

Tip: If you’ve already configured a key, the wizard detects it (shown as ••••••••) and skips straight to the model picker. Press Enter to re-fetch models with the existing key.

OAuth Providers (GitHub Copilot, Codex)

No API key needed: authenticate through your browser.

Flow:

1. Select GitHub Copilot or Codex
2. Press Enter: starts the device-code PKCE flow
3. A user code and URL appear (e.g. github.com/login/device)
4. Open the URL in your browser, enter the code, and authorize
5. Tokens are saved automatically to ~/.opencrabs/auth/
6. Models are fetched live: pick one and press Enter

CLI Providers (Claude CLI, OpenCode CLI, Codex CLI)

Use your existing CLI subscription: no separate API key.

Flow:

1. Select the CLI provider (e.g. Claude CLI)
2. Press Enter: skips the API key field (none needed)
3. Models are fetched from the local binary (claude models, opencode models, etc.)
4. Pick a model and press Enter

Requirements: The CLI binary must be installed and authenticated in your PATH.

z.ai GLM (Zhipu AI)

z.ai has two endpoint types. The wizard asks which one before the API key.

Flow:

1. Select z.ai GLM
2. Press Enter: advances to Endpoint Type selector
3. Use ↑/↓ to choose API (general) or Coding (CodeGeeX)
4. Press Enter: advances to API key field
5. Paste your key, press Enter, fetches models
6. Pick a model and press Enter

Custom OpenAI-Compatible

For Ollama, LM Studio, LocalAI, Groq, NVIDIA, vLLM, or any OpenAI-compatible endpoint.

Flow:

1. Select Custom OpenAI-Compatible (last in the list)
2. Press Enter: advances to Name field
3. Name: type a provider identifier (e.g. ollama, lm-studio, nvidia). Press Enter, normalized to a TOML-safe key
4. Base URL: paste your endpoint (e.g. http://localhost:1234/v1). Press Enter
5. API Key: paste if required, or leave empty for local endpoints. Press Enter
6. Model: you have two options:
   • Type or paste a model name: use this for newly-launched models not yet available on the live API (e.g. qwen3.6-35b-a3b-gguf)
   • Press Enter on empty field: triggers a live fetch from {base_url}/models, then pick from the list
7. Context Window: enter the token limit (e.g. 128000). Press Enter, saves and advances

Context Window Recommendation: Set to 200000 (200k tokens) for best results. OpenCrabs handles large contexts gracefully with smart auto-compaction that keeps you always up to date without manual intervention.

Local LLMs: No API key needed, just set base URL and model name. If the model is already running, paste the name directly. If you want to browse available models, leave the Model field empty and press Enter to fetch the list from your local server.

Re-running Provider Setup

Manual Configuration (advanced)

If you prefer editing files directly, configure providers in config.toml and keys.toml.

Key Handling (v0.3.81)

keys.toml no longer drops provider API keys at runtime (#1066): four providers could silently lose their keys during config reloads. The stored-key marker has one owner, and keys already poisoned by the old marker are self-healed on load. If a provider worked yesterday and 401s today, re-check keys.toml: the fix also repairs the file in place.

Anthropic Claude

Models: claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5, and legacy models, fetched live from the API.

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

Features: Streaming, tool use, extended thinking, vision, 200K context window.

OpenAI

Models: GPT-5 Turbo, GPT-5, and others, fetched live.

# keys.toml
[providers.openai]
api_key = "sk-YOUR_KEY"

OpenRouter: 400+ Models

Access 400+ models from every major provider through a single API key. Includes free models (DeepSeek-R1, Llama 3.3, Gemma 2, Mistral 7B).

# keys.toml
[providers.openrouter]
api_key = "sk-or-YOUR_KEY"

Get a key at openrouter.ai/keys. Model list is fetched live, no binary update needed when new models are added.

Google Gemini

Models: gemini-2.5-flash, gemini-2.0-flash, gemini-1.5-pro, fetched live.

# keys.toml
[providers.gemini]
api_key = "AIza..."

# config.toml
[providers.gemini]
enabled = true
default_model = "gemini-2.5-flash"

Features: Streaming, tool use, vision, 1M+ token context window.

Gemini also powers the separate image generation and vision tools. See Image Generation & Vision.

GitHub Copilot

Use your existing GitHub Copilot subscription: no separate API charges. Authenticates via OAuth device flow.

# config.toml
[providers.github_copilot]
enabled = true

Setup: Run /onboard:providers → select GitHub Copilot → follow the device code flow at github.com/login/device. Models are fetched live from the Copilot API.

Requirements: An active GitHub Copilot subscription (Individual, Business, or Enterprise).

z.ai (Zhipu AI)

Models: GLM-4-Plus, GLM-4-Flash, GLM-4-0520, CodeGeeX, fetched live. Two endpoint types: General API and Coding API.

# keys.toml
[providers.zai]
api_key = "your-api-key"

# config.toml
[providers.zai]
enabled = true
default_model = "glm-4-plus"

Get your API key at open.bigmodel.cn.

Qwen (DashScope)

Qwen models via DashScope. As of v0.3.81:

• Reasoning carries across turns (#1033): preserve_thinking is sent so multi-turn conversations keep their reasoning context
• Thinking knobs are family-gated (#1034): each model family gets only the knob it actually reads (enable_thinking, effort tiers), instead of a shared guess
• Tiered families default to the recommended effort tier (#1034)
• Hosted Qwen reachable everywhere (#1040): works outside Alibaba networks and with vendor-prefixed model ids

Claude CLI

Use your existing Claude Code subscription through the local claude binary, no separate API key needed. Supports streaming and extended thinking.

# config.toml
[providers.claude_cli]
enabled = true

Requirements: The claude CLI must be installed and authenticated. Models are detected automatically.

Ollama

Run any Ollama model natively: no custom provider setup needed. Supports both local (localhost:11434) and cloud (api.ollama.com) instances.

# config.toml
[providers.ollama]
enabled = true
default_model = "llama3"

# keys.toml (optional, only for cloud Ollama)
[providers.ollama]
api_key = "your-api-key"

Features: Streaming, tool use, local model tool-call extraction from text. Models are fetched live from the Ollama API.

Requirements: Ollama must be running locally (ollama serve) or you must have a cloud Ollama API key.

OpenCode CLI

Use the local opencode binary for free LLM completions, no API key or subscription needed. Supports NDJSON streaming and extended thinking.

# config.toml
[providers.opencode_cli]
enabled = true

Requirements: The opencode binary must be installed and available in your PATH. Models are fetched live via opencode models.

Codex CLI

Use OpenAI’s @openai/codex CLI as a native provider. User authenticates once via codex CLI; OpenCrabs piggybacks on cached credentials, zero API key handling. Non-interactive mode via codex exec --json with JSONL streaming.

# config.toml
[providers.codex_cli]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex

Requirements: The codex CLI must be installed (npm install -g @openai/codex) and authenticated. Models are detected automatically.

Codex OAuth

Native OpenAI Codex subscription auth via device-code PKCE flow. No CLI dependency, no API key. User authenticates through browser once; tokens stored in ~/.opencrabs/auth/codex.json with automatic refresh and background rotation.

# config.toml
[providers.codex]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex (curated GPT-5 model list)

Setup: Run /onboard:provider → select Codex OAuth → follow the device code flow at auth.openai.com/codex/device. Two-step PKCE exchange: device auth poll → authorization code → token exchange.

Requirements: An active OpenAI Codex subscription. No CLI installation needed.

MiniMax

Models: MiniMax-M2.7, MiniMax-M2.5, MiniMax-M2.1, MiniMax-Text-01

# keys.toml
[providers.minimax]
api_key = "your-api-key"

Get your API key from platform.minimax.io. Model list comes from config.toml (no /models endpoint).

Custom (OpenAI-Compatible)

Use for Ollama, LM Studio, LocalAI, Groq, or any OpenAI-compatible API.

# config.toml
[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"
models = ["qwen2.5-coder-7b-instruct", "llama-3-8B"]

Local LLMs: No API key needed, just set base_url and default_model.

Remote APIs (Groq, etc.): Add the key in keys.toml:

[providers.custom.groq]
api_key = "your-api-key"

Multiple Custom Providers

Define as many as you need with different names:

[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"

[providers.custom.ollama]
enabled = false
base_url = "http://localhost:11434/v1"
default_model = "mistral"

Naming Custom Providers

The provider’s name is the last segment of its config section, nothing else.

[providers.custom.moonshotai]   # the name is "moonshotai"

When you reference the provider anywhere (self_improvement_provider, subagent_provider, plan_provider, execute_provider, or the /models command) use that bare name:

[agent]
self_improvement_provider = "moonshotai"        # ✅ bare section name
self_improvement_model = "kimi-k2.5"            # the model has its own key

Never carry the custom path into the reference, and never append the model:

self_improvement_provider = "custom:moonshotai"    # ❌ RSI silently never runs
self_improvement_provider = "custom.moonshotai"    # ❌ same
self_improvement_provider = "moonshotai/kimi-k2.5" # ❌ provider-only, model goes in self_improvement_model

Real case: a user with [providers.custom.glm-53-max] set self_improvement_provider = "custom:glm-53-max" and RSI silently never ran, Mission Control showed thousands of tool events recorded and unprocessed. Dropping the custom: prefix fixed it instantly (opencrabs#1314). Current main auto-corrects misspelled values with a warning; released versions fail silently, so spell it bare.

Free Prototyping with NVIDIA API

Kimi K2.5 is available for free on the NVIDIA API Catalog, no billing required.

# config.toml
[providers.custom.nvidia]
enabled = true
base_url = "https://integrate.api.nvidia.com/v1"
default_model = "moonshotai/kimi-k2.5"

# keys.toml
[providers.custom.nvidia]
api_key = "nvapi-..."

Fallback Provider Chain

Configure automatic failover when the primary provider fails (rate limits, outages, errors). Fallbacks are tried in order until one succeeds.

# config.toml
[providers.fallback]
enabled = true
providers = ["openrouter", "anthropic"]  # Tried in order on failure

Each fallback provider must have its API key configured in keys.toml. Both complete() and stream() calls are retried transparently, no changes needed downstream.

Single fallback shorthand:

[providers.fallback]
enabled = true
provider = "openrouter"

Or just ask your Crab: “Set up fallback providers using openrouter and anthropic”, it will configure config.toml for you at runtime.

Quota Circuit Breaker (v0.3.79)

Fallback chains now know the difference between a provider that is momentarily busy and one that is genuinely out of quota.

• Hard quota exhaustion (your account has run out of credits/allowance for the period) trips a TTL circuit breaker on that provider. While the breaker is open the provider is skipped in fallback walks instead of being retried pointlessly, so failover lands on a provider that can actually serve the request.
• Transient throttles (short rate limits, 429s that clear in seconds) are classified separately and retried as before, they never trip the breaker.
• When every provider in the chain is exhausted, the failure is reported explicitly as chain exhaustion rather than surfacing as a confusing error from the last provider tried.
• Retry notices now name the provider and model being retried, and state whether the cause was a quota exhaustion or a transient throttle.

No configuration needed: it is always on whenever a fallback chain is configured.

Fallback Improvements (v0.3.80)

• Proactive setup suggestion (#1008): when no fallback chain is configured, OpenCrabs makes a one-shot suggestion to set one up, ask once, answered once, never nags again.
• HTTP 400 failover guidance (#1006, #1007): a 400-series failure now carries guidance on what to check, and a chain-exhaustion ledger records why each provider in the chain was ruled out.
• Fallback provenance in streaming logs (#969): each streamed call logs which provider actually served it, so retries and failovers are visible per call.
• Codex CLI failures route into retry and fallback (#1004, #1005) instead of surfacing as terminal errors.

Provider Configuration Fields

Every provider section ([providers.<name>]) supports these fields:

Example: full provider config:

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.7"
vision_model = "MiniMax-Text-01"
generation_model = "MiniMax-Image-01"
context_window = 200000
force_default = true

Force Default Provider

When you set force_default = true on a provider section, a config reload pushes that provider’s default pair (provider + model) to every non-archived session, overriding their stored pairs. This enforces your chosen default across all active sessions instead of just new ones.

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.7"
force_default = true  # Pushes MiniMax M2.7 to all sessions on reload

How it works:

• Only fires when the flagged section is the active default provider (set via /models or default_provider in [agent])
• Archived sessions are never touched
• Sessions already on the target pair are skipped
• Without this flag: defaults apply to new sessions only, existing sessions keep their own provider/model

Use case: You want to roll out a new default model (e.g. MiniMax M2.7) across all active sessions immediately, not just new ones. Set force_default = true on the MiniMax section, reload config, and every session switches to M2.7.

Note: This only reinforces the default, it doesn’t override a different active provider. If a session is using Anthropic Claude and you set force_default = true on MiniMax, the Claude session stays on Claude (because MiniMax isn’t the active default).

Vision Model

When your default chat model doesn’t support vision, set vision_model to a vision-capable model on the same provider. This registers a vision tool that the agent can call, it sends the image to the vision model, gets a description back, and the chat model uses that context to reply.

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.5"
vision_model = "MiniMax-Text-01"  # Agent calls vision tool → this model describes image → M2.5 replies

[providers.openai]
enabled = true
default_model = "gpt-5-nano"
vision_model = "gpt-5-nano"

MiniMax auto-configures vision_model = "MiniMax-Text-01" on first run. You can also ask your Crab to set it up: “Configure vision model for MiniMax”, it will update config.toml at runtime.

This is separate from the Gemini image tools which provide dedicated generate_image and analyze_image tools.

Per-Session Providers

Each session remembers its provider and model. Switch to Claude in one session, Gemini in another, switching sessions restores the provider automatically.

Model Picker (v0.3.75)

The /models picker got a real overhaul:

• Opus 5 surfaced: Opus 5 now shows up via a third parallel list plus state discovery.
• Newest-first ordering: models are ordered newest-first instead of by merge order.
• claude-cli model discovery: the claude-cli model list is discovered live from the CLI instead of being hardcoded, with every claude-cli row formatted consistently.
• Reconciled against live inventory: the picker reconciles against the live model inventory so it never offers a model that isn’t actually available.

Natural Model Naming (v0.3.76)

The /models command now accepts colloquial model names. Instead of typing the exact model ID, you can say it the way people talk:

/models opus        → claude-opus-4-8
/models sonnet      → claude-sonnet-4-20250514
/models gpt5        → gpt-5
/models qwen max    → qwen3.8-max-preview

The resolver normalizes spacing, case, and common abbreviations before matching against the provider’s model list. Exact matches still take priority.

Plan/Execute Provider Routing (v0.3.76)

The /plan and /execute commands can now route onto their own dedicated provider and model, separate from the main chat provider:

# config.toml
[agent]
plan_provider = "anthropic"
plan_model = "claude-opus-4-8"
execute_provider = "openrouter"
execute_model = "anthropic/claude-sonnet-4"

This lets you use a stronger model for planning (where reasoning quality matters most) and a faster/cheaper model for execution (where throughput matters). If unset, both fall back to the session’s active provider.

Image Generation & Vision

OpenCrabs supports image generation (text-to-image and img2img) and vision analysis (image-to-text). Vision works through two paths, pick whichever fits your provider setup.

Vision: Two Paths

Path A: vision_model on Your Active Provider (Preferred)

Set vision_model = "<model>" inside the provider block you’re already using. Works for every built-in and custom provider. No second API key needed, the agent calls analyze_image against the vision model on the same provider endpoint.

# keys.toml
[providers.openrouter]
api_key = "sk-or-..."

# config.toml
[providers.openrouter]
model = "anthropic/claude-sonnet-4"
vision_model = "google/gemini-2.5-flash"   # ← any vision-capable model on the same endpoint

When a user sends an image and the chat model can’t handle it natively, the agent routes the image through vision_model, gets a text description back, and replies with that context.

Example: User sends an image while you’re on MiniMax M2.5 (no native vision). The agent calls the vision tool, which sends the image to MiniMax-Text-01 (or any model you set), gets the description, and M2.5 replies using that context.

Why this is preferred:

• Single API key, single billing account
• Works on any OpenAI-compatible endpoint (OpenRouter, Ollama, LM Studio, vLLM, Groq, custom)
• No extra onboarding step: just add one line to your existing provider block

Path B: Gemini Global Fallback

Use this only when your active provider has no vision-capable model. Gemini acts as a dedicated vision+image backend, independent of your chat provider.

# keys.toml
[image]
api_key = "AIza..."    # ← MUST go here. See gotcha below.

# config.toml
[image.generation]
enabled = true
model = "gemini-3.1-flash-image-preview"

[image.vision]
enabled = true
model = "gemini-3.1-flash-image-preview"

Get a free API key from aistudio.google.com. Configure interactively with /onboard:image.

⚠️ Gotcha: #[serde(skip)] on [image.vision] api_key

The api_key field under [image.vision] in config.toml is silently ignored: it’s marked #[serde(skip)] in the source. Always put the Gemini key in keys.toml under [image], never in config.toml. If vision reports as unavailable despite a key being set, this is almost always the cause.

Diagnostic: Why Is Vision Unavailable?

is_vision_available logs the exact reason at INFO level with target=vision. Search your daily log:

grep 'target=vision' ~/.opencrabs/logs/opencrabs.$(date -u +%Y-%m-%d)

Common causes surfaced:

• Missing vision_model on active provider (the only field actually required since v0.3.64)
• Missing api_key for that provider
• Missing Gemini [image] api_key in keys.toml
• Key placed in config.toml where #[serde(skip)] drops it

v0.3.64 change: setting vision_model on your active provider is now sufficient to enable vision. The enabled flag under [image.vision] is no longer required. The vision roll-through tries each provider endpoint and falls back to Gemini last.

Agent Tools

When vision or image generation is enabled, these tools become available:

Example prompts:

• “Generate a pixel art crab logo”: agent calls generate_image, returns file path
• “What’s in this image: /tmp/screenshot.png”, agent calls analyze_image

img2img: Edit Images with Context

generate_image accepts an optional image parameter (local file path or HTTPS URL). When provided, the model modifies, restyles, or composites onto that image instead of generating from scratch.

User: "Make this logo darker and add a border"
Agent: generate_image(prompt="dark background with thin white border", image="/tmp/logo.png")

• Gemini backend: full img2img support via inlineData
• OpenAI-shaped backends: reject with a clear error pointing at Gemini (img2img not supported)

Use cases: replace elements, restyle photos, composite logos onto backgrounds, modify user-uploaded images in-place.

Incoming Images from Channels

When a user sends an image from any channel, it arrives as <<IMG:/tmp/path>> in the message. The file is already downloaded, the agent can:

• See it directly (if the chat model supports vision natively)
• Pass the path to analyze_image for vision processing
• Use the path in bash commands or any tool that accepts file paths
• Reference it in replies with <<IMG:path>> to forward to channels

analyze_video: Frame-Extraction Fallback (v0.3.36)

The analyze_video tool sends the full video to Gemini’s video API for multimodal analysis. When that fails (network error, upload timeout, unsupported format), the agent falls back to ffmpeg frame extraction:

1. Extract frames at 1 fps via ffmpeg
2. Cap at 30 frames (one frame per second for the first 30 seconds)
3. Send each frame to Gemini vision via analyze_image
4. Combine per-frame descriptions into a chronological summary

This means analyze_video works even when the video API is unreachable, as long as ffmpeg is installed and at least one vision path (Path A or Path B) is configured. The fallback activates automatically. No user configuration needed.

Model Choices

• Path A: any vision-capable model on your active provider. On OpenRouter: google/gemini-2.5-flash, anthropic/claude-sonnet-4, openai/gpt-4o. On Ollama: llava, bakllava. On custom endpoints: whatever the server offers.
• Path B: gemini-3.1-flash-image-preview handles both vision input and image output in a single request.

Channel Integrations

OpenCrabs connects to multiple messaging platforms simultaneously. All channels share the TUI session by default, with per-user sessions for non-owners.

Setting Up Channels

Channels are configured through the onboarding wizard, not by editing TOML files manually.

Running the Wizard

• First launch: the wizard runs automatically
• Re-run: type /onboard in chat, or /onboard:channels to jump straight to the channels step
• Quick jump: /onboard:channels opens the channel picker and returns to chat when done

Navigation

The channel picker is a keyboard-driven TUI screen:

Channel Setup Screens

When you press Enter on an enabled channel, a dedicated setup screen opens with the fields needed for that platform (bot token, channel ID, allowed users, etc.). Each field:

• Auto-detects existing values from config.toml / keys.toml (shown as masked •••••••• for secrets, plain text for IDs)
• Tab moves to the next field
• Enter on the last field (or the Test Connection button) saves and returns to the channel list
• BackTab moves to the previous field

The Five Channels

After enabling and configuring your channels, the wizard saves everything to config.toml and keys.toml automatically. You can always re-run /onboard:channels to modify settings.

Supported Channels

Cross-Channel Session Resolution (v0.3.29)

All messaging channels now share a stable [chat:<id>] suffix pattern for reliable session lookup. Previously only Telegram had this; Discord, Slack, and WhatsApp used exact-title matching which broke when the agent auto-renamed sessions (creating duplicates on every message).

The shared channels::session_resolve module provides:

• Suffix-first lookup: fast path using [chat:discord-dm-<user_id>], [chat:slack-<channel_id>], [chat:wa-<phone>] etc.
• Legacy forward-migration: pre-suffix rows are migrated to the suffix format on first lookup
• /sessions binding: explicit chat→session binding on switch so user choices win over suffix lookup

Follow-Up Cancel (v0.3.30)

Sending a message while the agent is mid-run now acts as ESC x2 (cancel current run) across all channels. The cancelled partial content is preserved, and the new message starts a fresh agent turn.

ZIP Attachments (v0.3.30)

ZIP file attachments from users are extracted and processed inline:

• Text files are inlined into the conversation
• Images get vision markers for multimodal processing
• PDFs get text extraction
• Capped at 50 files / 10 MB per ZIP entry

Group Onboarding & /cowork (v0.3.74)

Getting a bot into a group and making it useful is now a single flow:

• /cowork opens the group: /cowork sets the target group open = true and persists it (#718).
• /cowork admin deep link: the /cowork deep link requests admin rights, so the bot joins already promoted (#709).
• Group onboarding greeting: the bot greets the group with an onboarding nudge when it joins (#707, #708).
• Per-group /start registration: /start in a group registers the member per-group instead of the stale config.toml lecture (#708).
• Register joining members: any member who joins a bot group is auto-registered (#710).
• Secure by default: member auto-registration is gated to open = true groups (#717).

Follow-Up Suggestions (v0.3.74)

• follow_up_question degrades gracefully: returns the question as plain text on non-interactive surfaces (#716).
• Telegram follow-up taps: suggest_followups renders last, fixing taps doing nothing (#723, #724).
• Accurate description: the suggest_followups tool description is channel-accurate, so the model invokes it instead of writing plain-text suggestions (#706).
• Outbound media dedup: an identical file+caption re-uploaded to the same chat within a short window is collapsed, so the agent can’t send it twice (#721).

Common Features

All messaging channels support:

• Shared session with TUI (owner) or per-user sessions (non-owners)
• Slash commands: /help, /models, /new, /sessions, custom commands
• Inline buttons: Provider picker, model picker, session switcher (Telegram, Discord, Slack)
• User allowlists: Restrict access by user ID, chat ID, role, or phone number. Since v0.5.1 the allowlists are deny-by-default and are the access boundary: on Discord and Slack an unconfigured channel (no allowed_users, no allowed_roles, no bot_owner) refuses every message, matching Telegram; on WhatsApp an empty allowed_phones no longer grants anyone owner rights. Because the default approval_policy is auto-always, the allowlist is what decides who can drive tools at all, set it deliberately
• respond_to filter: all, dm_only, or mention (respond only when @mentioned)

File & Media Support

Images are passed to the active model’s vision pipeline if it supports multimodal input, or routed to the analyze_image tool (Google Gemini vision) otherwise. Text files are extracted as UTF-8 and included inline up to 8,000 characters.

Proactive Channel Tools

The agent can send messages and take actions proactively:

Channel Voice Parity

All four messaging channels (Telegram, Discord, WhatsApp, Slack) now share a single code path via crate::channels::voice::{transcribe, synthesize}. Bot replies are recorded in the channel_messages table for conversation context, previously only user messages were stored.

Typing Indicator Persistence (v0.3.76)

Typing indicators now survive background tasks. Previously, when the agent spawned a background task (long build, test suite), the typing indicator would drop because the foreground turn ended. Now the indicator stays alive until the final response is delivered, regardless of how many background tasks run in between.

Smart Chunk Boundaries (v0.3.78)

When a response exceeds platform message limits and must be split into chunks, the splitter now prefers boundaries that leave no markup open. Previously, a chunk could end mid-bold (**text) or mid-code-fence, causing rendering glitches on the receiving platform. The splitter now scans for the nearest safe break point where all markdown delimiters are balanced.

Owner-Gated Channel Commands (v0.3.80)

User-defined slash commands and skills are owner-gated on the channel catch-all arm (#975). In a group chat, only the bot owner can trigger custom commands and skills; other members’ messages fall through to normal conversation. This closes a gap where any group member could run owner-defined automation through the catch-all routing path.

Telegram

Connect OpenCrabs to Telegram for DMs and group chats.

Setup

Step 1: Create a Bot with BotFather

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456:ABC-DEF...)

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Telegram
2. Press Space to toggle it on
3. Press Enter to open the Telegram setup screen
4. Fill in the fields:
   • Bot Token: paste the token from BotFather
   • Owner User ID: your numeric Telegram chat ID
   • Respond To: all, dm_only, or mention (when to respond in groups)
5. Press Enter on Test Connection to verify the bot works
6. Press Enter to save and return to the channel list

Get your chat ID by messaging @userinfobot on Telegram.

Manual Configuration (advanced)

If you prefer editing files directly, the wizard writes to ~/.opencrabs/keys.toml and ~/.opencrabs/config.toml:

# keys.toml
[channels.telegram]
bot_token = "123456:ABC..."

# config.toml
[channels.telegram]
enabled = true
allowed_users = ["123456789"]
respond_to = "all"

Features

• DMs and groups: Works in private chats and group conversations
• Forum topic routing (v0.3.31): In supergroups with topics enabled, the bot tracks thread_id through the full pipeline. Use list_topics action to map topic names (e.g. #announcements) to numeric IDs, then pass thread_id to send / reply / send_photo to route into a specific topic
• Context-aware pre-tool status (v0.3.31): While a tool runs, the bot shows a live status message naming the tool, elapsed time, and either a reasoning excerpt or an anchored phrase from the user’s request
• Inline ctx budget footer (v0.3.36): context budget footer (ctx: XK/YK Z% | N tok/s) is now appended to the last response message instead of sent as a separate message. Keeps the chat clean.

v0.3.76–v0.3.78 Improvements

/new Gating (v0.3.76)

The /new command is now gated to the bot owner in group chats. Non-owners cannot create new sessions or reset context. The command menu is also scoped: owners see the full menu, non-owners see only the commands available to them.

HTML Conversion (v0.3.77)

All telegram_send actions now apply HTML-to-Telegram conversion consistently. Previously, only the main response path converted HTML entities; proactive sends, follow-ups, and media captions could arrive with raw <b> tags or unescaped ampersands.

Rich Delivery (v0.3.78)

Telegram delivery is unified on markdown formatting. The legacy “blocks path” (which sent structured JSON blocks) has been removed in favor of a single rich-markdown renderer. This eliminates formatting inconsistencies between streaming responses and proactive sends.

Callback Routing (v0.3.78)

Inline keyboard callbacks (plan approvals, follow-up taps, dedup approvals) now route to the originating session instead of the chat-bound session. Previously, tapping a button in a group chat could route the callback to the wrong session if multiple sessions shared the same chat.

Background Streaming (v0.3.78)

Background task results now stream through one turn per session instead of spawning a new message per tick. This eliminates the message flood when a background task (build, test suite) produces incremental output.

Follow-Up Attribution (v0.3.78)

When a user taps a follow-up suggestion button in a group chat, the agent now names the member who tapped it. Previously, follow-up taps were anonymous in group contexts.

Other Fixes

• /start recognizes existing members of closed groups (v0.3.76)
• Plan-card serialisation prevents duplicate cards on concurrent refreshes (v0.3.76)
• Follow-up taps run a real tools turn instead of echoing text (v0.3.76)
• Flow block no longer posts a new message every tick (v0.3.77)
• Echoed plan titles dropped from responses (v0.3.77)
• Open-group registration gated on persisted open flag (v0.3.78)
• Cowork members recorded on first message (v0.3.78)
• Rolling status edit-in-place (v0.3.36): tool status messages (⚙️ running, ✅ done) are edited in-place instead of delete+recreate, preventing flicker and preserving scroll position.
• Bot command hot-reload (v0.3.36): bot commands refresh automatically when config or skills change, without restarting the bot.
• Guard tok/s against burst-delivery (v0.3.36): tok/s footer is guarded against burst-delivery artifacts so the number stays stable.
• follow_up_question polish (v0.3.34): Telegram keyboard is now single-column with a 40-character label cap (longer options rejected with a clear error). The rolling “Running follow_up_question (16s)” status is suppressed while the keyboard is pending so buttons don’t get visually buried. The LLM is instructed to call the tool silently without echoing the question text in surrounding prose
• Inline buttons: Provider picker, model picker, session switcher use Telegram inline keyboards
• Image support: Send images to the bot, receive generated images
• Voice messages: STT transcription + TTS response
• All slash commands: /help, /models, /new, /sessions, custom commands
• Owner vs non-owner: Owner uses the shared TUI session, non-owners get per-user sessions
• Onboarding overhaul (v0.3.30): Auto-detects owner user ID from getUpdates, persists partial config on cancel, only Enter on the last step commits (Tab no longer silently rewrites ~30 config keys)
• Teloxide upgrade + join detection (v0.3.35): Upgraded from teloxide 0.13 to 0.17. New members joining a group are now detected before the allowlist check, so the bot can greet or moderate join events. Marathon-bucket rolling status rotates through project-author quip pool for more varied status messages.

v0.3.81 Improvements

Mermaid Diagrams as Images (#1044)

Mermaid code fences in rich messages render as images via the markdown+media route, while tables stay native Telegram formatting instead of being rasterized into the image.

Delivery and Rate-Limit Hardening

• Rich blocks decode as a typed AST (#1058) instead of ad-hoc string surgery, so structured messages can’t arrive mangled
• Inline rate-limit waits capped at 30s (#1064): a Telegram 429 never parks a turn indefinitely
• Flow footer + section cap (#1052, #1053, #1054, #1056): flow logs get a footer and bounded sections instead of unbounded message growth

Group Safety

• Only the owner may add the bot to a group (#1042)
• Bot-add detection (#1041): being added by a member is told apart from another bot arriving
• Unauthorised chats are never recorded (#1043): chats that were never approved leave no session residue

v0.3.82 Improvements

Long Rate-Limit Windows Bail Immediately (#1110)

A Telegram 429 that asks for a long wait no longer sleeps inline. The send returns immediately and the work is rescheduled, instead of the turn parking on a multi-minute (or multi-hour) window. This closes the failure mode where one throttled send held a turn open long enough to look like a hang.

Delivery Correctness

• Rich sends stop building a double-slash URL (#1117): a trailing slash on the API base no longer produces //bot<token>
• Rich API calls honour set_api_url (#1088): the rich path used a hardcoded api.telegram.org, so it bypassed a redirected Bot. It now routes through the caller’s API URL like every other method, which also makes the path testable without a real network call
• All six send arms route through thread resolution: forum-topic targeting is applied consistently instead of on some arms only

Observability

• Send-correlation telemetry (#1085): the three send chokepoints, every telegram_send arm, and the final streaming edit-in-place are all logged, so a message that never arrived can be traced to the arm that dropped it

Configuration

All Telegram options live under [channels.telegram] in ~/.opencrabs/config.toml:

[channels.telegram]
enabled = true
token = "123456:ABC-DEF..."          # or store in keys.toml
allowed_users = ["123456789"]         # numeric Telegram user IDs
allowed_channels = ["-100123456"]     # restrict to specific group/channel IDs (empty = all)
respond_to = "mention"                # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0             # idle timeout for non-owner sessions
rich_messages = false                 # native Telegram rich messages (Bot API 10.1)
silence_group_start = true            # silently ignore /start from non-allowed users in groups
bot_owner = ["123456789"]             # owner IDs (gated commands, /cd hidden dirs, /profiles)

Per-group access control (per-chat ACL)

Telegram groups can have their own member list, so a user can be allowed in one group without gaining DM access:

• allowed_users (channel level): admins: may DM the bot and act in any chat.
• bot_owner: the owner: always allowed everywhere.
• [channels.telegram.groups.<chat_id>].allowed_users: allowed in that group only. These users are refused in DMs unless they are also an admin or the owner, which closes the “DM the bot privately to escape group oversight” bypass.

DMs are gated to admins + owner. If neither allowed_users nor bot_owner is set, the bot is unconfigured and stays open (no hard lockout); set either one to lock it down.

Each group can also override respond_to just for itself.

[channels.telegram]
allowed_users = ["111"]                  # admins: DM + any chat
respond_to = "mention"                   # global default

[channels.telegram.groups.-1001234567890]
allowed_users = ["222", "333"]           # allowed in this group only, never via DM
respond_to = "all"                       # per-group override of the global respond_to

respond_to accepts all, mention, dm_only, or auto (reply to all while there is at most one active sender, then switch to mention-only once a second unique sender appears).

Per-group open mode (v0.3.66)

Set open = true on a trusted group to serve all members without individual allowlisting:

[channels.telegram.groups.-1001234567890]
open = true                              # all members can talk, no per-user registration needed

Use this for public/community groups where you want the bot available to everyone. Members still can’t DM the bot unless they’re in the global allowed_users or bot_owner.

Guest queries

Telegram Guest Mode (Bot API 10.0) lets someone tag @yourbot in a chat the bot is not a member of. With guest_queries = true, OpenCrabs answers the tag right there using the API method answerGuestQuery.

[channels.telegram]
guest_queries = true                     # default false: guest tags are ignored
allowed_users = ["111"]                  # admins: answered anywhere
[channels.telegram.groups.-1001234567890]
allowed_users = ["222"]                  # this user is answered in this chat only

Default is off, and the gate is narrow once it is on. The caller must be the bot_owner, an admin (allowed_users), or listed for that chat. A group’s open = true grants nothing here: it opens that group to the bot, it does not authorize answering guest tags from its members. Refused queries are logged with the guest_query_id, the caller, and the chat.

Boundaries of a guest turn:

• The bot sees only the tagged message, no history from that chat, and nothing from the guest turn is stored in that chat’s history.
• A guest turn runs the same tool surface as a normal turn, with one exception: tools that need approval are denied, because approvals are buttons in a chat and the caller is not the machine’s owner. The tool set is capped at what a stranger should reach (#2134).
• The live status block and rich rendering match a normal turn: the guest sees the same progress chrome and the same markdown or rich reply, and an edit replaces the placeholder rather than appending a second message (#2109, #2133, #2135, #2138).
• One guest turn per session at a time, cancellable, behind a rate limit, so a tag storm cannot fan out into parallel turns (#2143).
• A reply with no tool calls is the answer alone, and the answer is never carried twice in one reply (#2113).
• Channel directives (<<...>>) are stripped, so a local file path can never leak into someone else’s chat.
• An overlong reply is cut and marked [truncated] rather than dropped.

Because the pinned teloxide-core has no guest update variant, guest queries are read on the raw getUpdates layer, and guest_message is in the bot’s allowed_updates list. Nothing to configure for that; it is on whenever the channel runs.

Voice and file pickup in groups

In mention-only groups (respond_to = "mention"), users can share files and voice messages even when the bot isn’t directly tagged in the same message:

1. Fire-and-forget file capture: The bot downloads ALL incoming voice, video, document, and audio files from group messages to ~/.opencrabs/tmp/, regardless of whether the bot was mentioned. This happens silently in the background.
2. Tag-then-ask: A user sends a voice message, then tags the bot in a follow-up message (e.g. @bot what did I just say?). The bot scans the tmp directory for recent voice files from that chat (5-minute window), transcribes the most recent one, and prepends the transcript to the user’s message.

This solves the core UX problem in mention-only groups: previously, tagging the bot in the same message as a voice note didn’t work because Telegram sends voice and text as separate messages.

The agent can use telegram_send with 20+ actions. The thread_id field on send / reply / send_photo targets a specific forum topic in supergroups with topics enabled.

Reactions (v0.3.58)

The bot understands Telegram emoji reactions in both directions:

• Inbound: when a user reacts to one of the bot’s messages with an emoji, the bot picks up that reaction (it looks up the original bot message by its platform message ID) and can act on it as feedback.
• Frame reactions (v0.3.61): inbound reactions are read by sentiment and the bot addresses the user by first name in its response.
• Mid-turn reactions (v0.3.61): if a user reacts during a running turn, the reaction injects into the current loop instead of spawning a second turn.
• Reaction-only replies: when a short acknowledgement says it all (a thumbs-up, a 👀, a 😂), the bot can respond with just a reaction instead of a full text message, keeping the chat uncluttered.
• Emoji validation: only real emoji count as reaction directives; code spans and stray characters are ignored, and react directives are stripped from intermediate status messages so they never leak into the visible reply.

Use the set_reaction action on telegram_send to add a reaction to a specific message from the agent.

/cowork: Workspace Creation (v0.3.59)

/cowork creates a team workspace directly from Telegram. Run it in your DM with the bot:

1. Send /cowork in your DM with the bot
2. The bot replies with an invite link and QR code for a new group
3. Scan the QR code or tap the link to create the group
4. Add your friends or teammates to the group
5. Members auto-register to the group’s allow list ([channels.telegram.groups.<chat_id>].allowed_users), not the global one. Both new joiners (via invite link) and existing members (on their first message) get registered. Cowork members can talk in the group but cannot DM the bot privately unless also on the global allowed_users. The owner gets a confirmation for each registration.

/cowork works from any surface. In Telegram DMs, the native flow activates directly. From the TUI, Discord, Slack, or WhatsApp, the agent calls the cowork_connect tool which mints a session, registers it with the bot, and returns the t.me deep link plus a scannable QR code PNG.

Flow Logs (v0.3.63)

Telegram’s rich API supports 32K-character processing-log blocks. When the agent runs multi-step operations (tool calls, research, code generation), it streams progress into a single flow-log message that grows as the turn progresses. For shorter messages, HTML formatting falls back to plain text.

Flow logs show:

• Tool calls with parameters and results
• Intermediate reasoning steps
• File edits and git operations
• Build/test progress
• Wall-clock duration (v0.3.66): finished/failed/timeout states carry the total turn time
• Bash comments as flow status (v0.3.66): line-start comments in a bash command surface as live flow status
• Full status preview (v0.3.66): the status preview uses the whole last human-readable line, no truncation

The flow-log message is edited in-place as each step completes, so the channel stays clean. Users see real-time progress without message spam.

Flow blocks re-stick to the chat bottom when buried (v0.3.65), so you always see the latest progress without scrolling.

Forum Topic Management and /clear (v0.5.2)

The agent can create and rename forum topics (not just route into existing ones), and a group’s session can bind to a topic so each topic keeps its own conversation context. /clear starts a fresh session in place (the current one closes and a blank one begins) without invoking the summariser, so it is instant and free (#1585).

Group Chat Behavior

In groups, the agent:

• Responds when mentioned by name or replied to
• Stays quiet when the conversation doesn’t involve it
• Tracks context from group messages passively

Discord

Connect OpenCrabs to Discord for server and DM interactions.

Setup

Step 1: Create a Discord Bot

1. Go to discord.com/developers/applications
2. Create a new application
3. Go to Bot section, create a bot
4. Enable MESSAGE CONTENT Intent (required: under Privileged Gateway Intents)
5. Copy the bot token
6. Under OAuth2 → URL Generator, select bot scope with Send Messages and Read Message History permissions
7. Use the generated URL to invite the bot to your server

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Discord
2. Press Space to toggle it on
3. Press Enter to open the Discord setup screen
4. Fill in the fields:
   • Bot Token: paste the token from the Developer Portal
   • Channel ID: the Discord channel to send the welcome message to (right-click a channel with Developer Mode on → Copy Channel ID)
   • Allowed Users: comma-separated Discord user IDs (since v0.5.1 an empty allowlist no longer allows everyone: until you set users, roles, or bot_owner, the channel denies all messages)
   • Respond To: all, dm_only, or mention
5. Press Enter on Test Connection to verify
6. Press Enter to save and return to the channel list

Enable Developer Mode in Discord: Settings → Advanced → Developer Mode

Manual Configuration (advanced)

# keys.toml
[channels.discord]
token = "your-bot-token"

# config.toml
[channels.discord]
enabled = true
allowed_channels = ["123456789"]
allowed_users = []
respond_to = "all"

Configuration

All Discord options live under [channels.discord] in ~/.opencrabs/config.toml:

[channels.discord]
enabled = true
token = "your-discord-bot-token"       # or store in keys.toml
allowed_users = ["123456789012345678"]  # Discord user IDs
allowed_channels = ["123456789012345678"]
respond_to = "mention"                  # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Features

• Server channels and DMs: Works in text channels and direct messages
• Interactive components: Select menus, modal forms, button interactions with component TTL and role access
• Media gallery: Batch generated files into one multi-attachment message
• Grouped tool calls: Consecutive tool calls collapse into one expandable block with Expand/Collapse toggle
• Reactions: Agent can add emoji reactions to messages. Emoji reactions from users trigger agent turns (parity with Slack/Telegram)
• Forum threads: Support for Discord forum channels
• Image support: Send and receive images
• Embed suppression: Agent wraps multiple links in <> to suppress embeds
• Slash commands: All built-in and custom commands work

Interactive Components (v0.3.63)

Discord buttons, select menus, and modal forms power the provider picker, model picker, and session switcher. Components support:

• Component TTL: Components expire after a configurable timeout
• Role access: Restrict component interactions to specific Discord roles
• Forum threads: Agent can create and manage forum threads

Media Gallery (v0.3.63)

When the agent generates multiple files (PDFs, spreadsheets, images), Discord batches them into one multi-attachment message instead of sending separate messages for each file.

Grouped Tool Calls (v0.3.63)

Consecutive tool calls collapse into a single expandable block in Discord. Users can toggle between expanded and collapsed views. This keeps the channel clean during multi-step operations.

Reactions (v0.3.63)

The agent can add emoji reactions to messages. When a user reacts with an emoji, it triggers an agent turn (parity with Slack and Telegram). This enables quick, lightweight interactions without typing full messages.

Formatting Notes

• Markdown tables in agent output convert to native Discord tables (v0.5.2); in your own messages, bullet lists are still the safest habit
• Wrap multiple links in <url> to suppress embeds

Live Reply Tracing, Auto-Threading, Native Tables (v0.5.2)

Long turns stream as a live reply that is traced and edited in place instead of staying silent until the end. Answers that belong together are auto-threaded, and markdown tables in agent output render as native Discord tables rather than raw pipes (#1608). A dedup guard on tool turns stops the final response from double-posting content a tool summary already showed (#1603).

Native Polls, Voice Replies, Slash Projection, Flow Groups (v0.5.5)

send_poll posts a native Discord poll with each option as its own answer button, so follow-up option sets render as the platform’s own poll UI (#1848). TTS replies are delivered as Discord voice messages instead of attachment links (#1849), and your commands.toml is projected onto native slash commands, so your custom commands appear in Discord’s command picker (#1850).

Flow groups now open at turn start with a live clock that keeps running while the agent thinks, and the activity text leads the line instead of hiding behind the tool count (#1841, #1843, #1844, #1845). Every outbound write, including the persistent plan card, rides one shared write governor that parks cleanly on 429s (#1910, #1912).

Per-channel control arrived with respond_to and open modes in the channel config, enforced in the message filter, the ACL and the command gate (#2014). Two commands set them from inside the channel itself: /respond_to picks who the crab answers there, and /cowork opens the channel or thread to its members (#2014, #2015). Cron reports on Discord arrive as one edited forum post instead of a chain of messages (#1851).

Sustained Typing Indicator (v0.3.76)

Discord now shows a sustained typing indicator while the agent processes a request. Previously, Discord had no typing indicator at all (Telegram and Slack did). The indicator stays alive through background tasks and long tool executions, so users see “OpenCrabs is typing…” for the entire processing duration, not just the first few seconds.

Slack

Connect OpenCrabs to Slack workspaces.

Setup

Step 1: Create a Slack App

1. Go to api.slack.com/apps
2. Create a new app (From Scratch)
3. Enable Socket Mode under Settings
4. Generate an App-Level Token (Settings → Basic Information → App-Level Tokens) with connections:write scope
5. Under OAuth & Permissions, add bot scopes: chat:write, channels:history, groups:history, im:history, reactions:write
6. Install the app to your workspace (Install App → Install to Workspace)
7. Copy both tokens: they live in different places in the Slack dashboard:
   • Bot Token (xoxb-...): under Install App, in the OAuth Tokens for Your Workspace section. It only appears after you install the app to the workspace.
   • App-Level Token (xapp-...): under Basic Information → App-Level Tokens. If you already generated it in step 4, Slack only lists the token name here; click the name to expand it and reveal the actual xapp-... value to copy.

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Slack
2. Press Space to toggle it on
3. Press Enter to open the Slack setup screen
4. Fill in the fields:
   • Bot Token: the xoxb-... token
   • App Token: the xapp-... token
   • Channel ID: right-click a channel → View channel details → copy the Channel ID at the bottom
   • Allowed Users: comma-separated Slack user IDs (Profile → ⋯ → Copy member ID)
   • Respond To: all, dm_only, or mention
5. Press Enter on Test Connection to verify
6. Press Enter to save

Manual Configuration (advanced)

# keys.toml
[channels.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."

# config.toml
[channels.slack]
enabled = true
allowed_channels = ["C12345678"]
allowed_users = []
respond_to = "all"

Configuration

All Slack options live under [channels.slack] in ~/.opencrabs/config.toml:

[channels.slack]
enabled = true
token = "xoxb-your-bot-token"          # or store in keys.toml
app_token = "xapp-your-app-token"      # Socket Mode token
allowed_users = ["U12345678"]           # Slack user IDs
allowed_channels = ["C12345678"]
respond_to = "mention"                  # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Features

• Channels and DMs: Works in public/private channels and direct messages
• Action buttons: Provider picker, model picker, session switcher use Slack action buttons
• Thread support: Responds in threads when appropriate
• Slash commands: All built-in and custom commands work
• Reactions: Agent can add emoji reactions. Emoji reactions from users trigger agent turns (react-back)
• Grouped tool calls: Consecutive tool calls collapse into one edited-in-place message with Expand/Collapse toggle
• TTS voice replies: Voice responses sent as OGG/Opus files via files.upload with inline waveform UI

Grouped Tool Calls (v0.3.62)

Consecutive tool calls collapse into a single message in Slack. The message is edited in-place as each tool executes. Users can toggle between expanded and collapsed views with an Expand/Collapse button. This keeps channels clean during multi-step operations.

Reactions (v0.3.62)

The agent can add emoji reactions to messages. When a user reacts with an emoji, it triggers an agent turn (react-back). This enables quick, lightweight interactions without typing full messages. Parity with Telegram and Discord.

Reactions (v0.3.62)

Slack supports emoji reactions for lightweight acknowledgements:

• React-back: When you react to a bot message, the bot acknowledges it (e.g., adds a 👍 to show it saw your reaction)
• Reaction turns: Certain reactions can trigger agent actions (configurable)
• Grouped tool calls: Multiple tool calls in one turn collapse into a single collapsible message, keeping the channel clean

Native Rendering (v0.3.80)

Slack messages render in Slack’s own shape instead of raw markdown (#1016):

• Tables are converted to Slack-native layout instead of arriving as pipe characters
• Headings are rendered as Slack formatting rather than # hashes

Step-group narration is folded on the character stream rather than on paragraphs, and the final message no longer repeats the step-group narration it already sent (#1010).

Socket Mode

Slack uses Socket Mode (WebSocket) instead of HTTP webhooks, no public URL or ngrok needed. The connection is outbound from your machine.

WhatsApp

Connect OpenCrabs to WhatsApp via QR code pairing.

Setup

Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus WhatsApp
2. Press Space to toggle it on
3. Press Enter to open the WhatsApp setup screen
4. The setup screen has two fields:
   • Connection: shows the QR code or connection status
   • Phone Allowlist: comma-separated phone numbers in E.164 format (e.g. +15551234567). Leave empty to accept all messages.
5. When not yet paired, a QR code appears in the terminal:
   • Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
   • Scan the QR code
   • The status updates to “Connected” automatically
6. When already paired, press R on the Connection field to reset and re-pair
7. Press Enter to save

The pairing session persists across restarts: no need to re-scan.

Manual Configuration (advanced)

# config.toml
[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]

Configuration

WhatsApp options live under [channels.whatsapp] in ~/.opencrabs/config.toml:

[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]      # E.164 format
session_idle_hours = 24.0              # idle timeout for non-owner sessions

How it works

One account per instance. Each OpenCrabs instance supports one WhatsApp account (one companion device). You run the bot AS whatever account you scan: your own number (talk via “Message Yourself”), or any other number you own, including a WhatsApp Business account.

The bot talks to itself. If you message the bot’s own paired number, the bot replies to you. This is by design. The paired account’s self-chat is always allowed, regardless of response_policy or allowed_phones.

Allowlist behavior. Anyone messaging the paired number who is on the allowed_phones list gets a reply. The response_policy controls who else can interact beyond the allowlist.

Ownership (v0.5.1, deny-by-default). Before v0.5.1 an empty allowed_phones under response_policy = "auto" answered every contact and elevated them all to owner: one forgotten allowlist away from handing strangers /evolve and /cd. That elevation is gone: being answered no longer means being in charge. Owner status comes from the paired account’s self-chat, a configured bot_owner, or ownership resolution over allowed_phones + bot_owner: never from an empty list. Tool-approval replies (Yes/Always/No/YOLO) resolve only for the owner on all four channels.

• Personal and group chats: Works in DMs and group conversations
• Image support: Send and receive images
• Voice messages: STT transcription + TTS response
• Plain text UI: No buttons (WhatsApp limitation), uses text-based menus
• Slash commands: All built-in and custom commands work

Outbound rate limiting

WhatsApp is the channel with the heaviest ban consequences, so every outbound send goes through a budget (since v0.5.1):

[channels.whatsapp.rate_limit]
messages_per_minute = 30   # token bucket: sustained sends per minute
daily_cap = 800            # rolling 24h hard cap

Streaming answers used to post every chunk as its own message, exactly the volume pattern Meta’s heuristics hunt. Outbound replies now edit one message in place (since v0.5.1), which keeps chunked turns well inside the budget; the limiter is the safety net underneath.

Formatting Notes

• No markdown tables: use bullet lists
• No headers: use bold or CAPS for emphasis
• Links render natively

Voice Message Handling

When receiving a voice message:

1. Agent downloads and transcribes via STT
2. Sends text response first (searchable)
3. Optionally generates TTS audio response

Features

• Personal and group chats: Works in DMs and group conversations
• Image support: Send and receive images
• Voice messages: STT transcription + TTS response
• Plain text UI: No buttons (WhatsApp limitation), uses text-based menus
• Slash commands: All built-in and custom commands work

Surface (v0.5.2)

The WhatsApp channel grew to match the phone app’s surface:

• Outbound: native voice notes (opus), edit-in-place streaming for long replies, pin, forward, and profile actions
• Inbound: video, stickers, location, contacts, reactions, and poll votes are parsed into the turn; presence events and media recovery fill gaps after reconnects
• Sessions: disappearing messages honored per chat, contact blocking, per-chat history with reaction acknowledgements
• Surfaces: status updates and newsletter discovery, native-flow buttons for interactive prompts; follow-up suggestion sets that exceed the native button cap render as a poll, and a vote selects the option (#1616)

Troubleshooting

Wrong number replying

Each OpenCrabs instance supports one WhatsApp account (one companion device). If you connected multiple numbers or the wrong number is replying, you need a full reset. The bot always uses the last number you connected.

Critical: Always reset the connection before connecting a new number. OpenCrabs only keeps the last paired number.

Full reset steps:

1. Remove ALL linked devices from WhatsApp. Open WhatsApp on your phone, go to Settings > Linked Devices, and remove every device in the list. Don’t bother hunting for the opencrabs one. A stale device left over from an earlier pairing is the usual reason the old number keeps replying, so the reliable fix is to clear them all and start fresh.
2. Reset the connection in OpenCrabs: in the TUI or from a channel, go to /onboard:channels and press R to reset the WhatsApp connection. Wait for confirmation that the reset is complete.
3. Re-pair from scratch: after the reset is confirmed, go to WhatsApp > Settings > Linked Devices > Link a Device and scan the new QR code shown by OpenCrabs.

If the bot still shows the old number after resetting, make sure you completed step 1 (removing the device from WhatsApp) before step 2.

Common issues

Trello

OpenCrabs integrates with Trello for board and card management via the trello_send tool.

Setup

Step 1: Get Trello Credentials

1. Go to trello.com/power-ups/admin
2. Create a new Power-Up to get your API Key
3. Click the “Token” link next to your API key to generate an API Token

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Trello
2. Press Space to toggle it on
3. Press Enter to open the Trello setup screen
4. Fill in the fields:
   • API Key: from the Trello Power-Up admin page
   • API Token: generated alongside the API key
   • Board ID: board name or 24-character hex ID (names are resolved automatically)
   • Allowed Users: Trello member IDs allowed to interact with the bot (leave empty for all members)
5. Press Enter on Test Connection to verify board access
6. Press Enter to save

Manual Configuration (advanced)

# keys.toml
[channels.trello]
api_key = "your-api-key"
token = "your-token"

# config.toml
[channels.trello]
enabled = true
boards = ["Board Name or ID"]
allowed_users = []
# poll_interval_secs = 30  # Poll for new card comments

Configuration

All Trello options live under [channels.trello] in ~/.opencrabs/config.toml:

[channels.trello]
enabled = true
token = "your-trello-api-token"        # or store in keys.toml
app_token = "your-trello-api-key"      # stored as app_token for keys.toml symmetry
allowed_users = ["memberId1"]           # Trello member IDs
board_ids = ["boardId1", "boardId2"]   # boards to monitor (also accepts allowed_channels)
poll_interval_secs = 60                 # polling interval (absent or 0 = tool-only mode)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Tool Actions

The trello_send tool supports 22 actions:

Comportement

• Tool-only by default: The agent acts on Trello only when explicitly asked
• Optional polling: Set poll_interval_secs to enable monitoring for @bot_username mentions
• Image attachments: Generated images are sent as card attachments with embedded previews
• File attachments: Card attachments (images, documents) are fetched and processed through the vision pipeline

Built-in Tools

OpenCrabs ships with 50+ tools available to the agent out of the box, plus support for user-defined dynamic tools.

File Operations

Code Execution

Web & Network

Document Parsing

Document Generation

Session & Memory

Image & Video

Channel Integrations

Sub-Agent Orchestration

Agents can spawn independent child agents for parallel task execution:

Agent Types

When spawning, agent_type selects a specialized role with a curated tool registry:

ALWAYS_EXCLUDED tools (no agent type has these): spawn_agent, resume_agent, wait_agent, send_input, close_agent, rebuild, evolve – no recursive spawning, no self-modification from subagents.

Browser Automation

Native headless Chrome control via Chrome DevTools Protocol (CDP):

Auto-detects your default Chromium browser. Feature-gated under browser (enabled by default).

Dynamic Tools

Define custom tools at runtime via ~/.opencrabs/tools.toml. See Dynamic Tools for details.

System

Error Handling

v0.2.92 improved error surfacing across all tool connections. Channel connect tools (slack_connect, whatsapp_connect, trello_connect) now surface actual connection errors instead of silently swallowing them. Tool call status correctly transitions from “running” to success/failure instead of showing a perpetual spinner.

System CLI Tools

OpenCrabs runs in a TUI with full terminal access. The agent can execute any CLI tool installed on the host via the bash tool – no plugins, no wrappers. If it’s on your system, the agent can use it. Common ones:

GitHub CLI (gh)

Authenticated GitHub CLI for full repo management:

gh issue list / view / create / close / comment
gh pr list / view / create / merge / checks
gh release list / create
gh run list / view / watch

Google CLI (gog)

OAuth-authenticated Google Workspace CLI. Supports Gmail and Calendar:

gog calendar events --max 10
gog gmail search "is:unread" --max 20
gog gmail send --to user@email.com --subject "Subject" --body "Body"

Requires GOG_KEYRING_PASSWORD and GOG_ACCOUNT env vars.

Companion Tools

SocialCrabs: Social Media Automation

SocialCrabs is a social media automation tool with human-like behavior simulation (Playwright). Supports Twitter/X, Instagram, and LinkedIn.

The agent calls SocialCrabs CLI commands via bash:

node dist/cli.js x tweet "Hello world"
node dist/cli.js x mentions -n 5
node dist/cli.js ig like <post-url>
node dist/cli.js linkedin connect <profile-url>

Read operations are safe. Write operations (tweet, like, follow, comment) require explicit user approval.

WhisperCrabs: Floating Voice-to-Text

WhisperCrabs is a floating voice-to-text widget controllable via D-Bus. Click to record, click to stop, text goes to clipboard. The agent can start/stop recording, switch providers, and view transcription history via D-Bus commands.

Custom Commands

Define your own slash commands in ~/.opencrabs/commands.toml. Commands work from the TUI and all channels (Telegram, Discord, Slack, WhatsApp).

Configuration

# ~/.opencrabs/commands.toml

[commands.credits]
description = "Show remaining API credits"
action = "prompt"
value = "Check my API credit balance across all providers and give me a summary"

[commands.deploy]
description = "Deploy to production"
action = "prompt"
value = "Run the production deployment pipeline: git pull, build, test, deploy"

[commands.status]
description = "Show system status"
action = "system"
value = "System is operational. All channels connected."

Action Types

Using Commands

Type /commandname in the TUI or any connected channel:

/credits     → agent checks API balances
/deploy      → agent runs deployment
/status      → shows static system message

Visibility

Custom commands appear in:

• /help output (TUI and channels) under a “Custom Commands” section
• TUI slash autocomplete when typing /

Commands are sorted alphabetically and show their description.

Memory System

OpenCrabs uses a 3-tier memory system for persistent context across sessions.

Memory Tiers

1. Daily Notes (memory/YYYY-MM-DD.md)

Automatic daily files for session-specific observations:

~/.opencrabs/memory/2026-03-07.md

The agent writes here during conversations: new integrations, bugs fixed, decisions made, server changes.

2. Long-term Memory (MEMORY.md)

Curated knowledge that persists across all sessions:

• Server details, SSH access, credentials locations
• User preferences and workflows
• Integration configurations
• Lessons learned from debugging

3. Semantic Search (session_search)

Full-text search across all past sessions stored in SQLite. The agent can query:

• Previous conversations
• Tool execution history
• Past decisions and context

Memory Search

The agent uses session_search for fast memory lookups (~500 tokens) instead of reading full memory files (~15K tokens). This is the primary recall mechanism.

Chunk-Hash Caching (v0.3.82)

Embedding is skipped for chunks whose content has not changed (#1107). Each chunk carries a hash; on write, only chunks whose hash differs from the stored one are re-embedded. Editing one line of a large brain file no longer re-embeds the whole document.

Scoped Search (v0.3.80)

memory_search takes a scope that picks which corpus to search (#1020):

Picking the wrong scope is the usual reason a search comes back with nothing useful. Daily logs outnumber brain files and reuse the same words for unrelated things, so searching memory for a rule usually fails: history outranks policy and you get confident irrelevant hits. Search brain before appending any rule: a hit tells you WHICH file owns it, and then load_brain_file with a query reads the whole section.

Chunked Retrieval and Index-on-Write (v0.3.80)

Memory retrieval was rebuilt around chunking (#998-1002, #1018):

• Documents are chunked before embedding, so chunks past the first are searchable. Previously a long document effectively hid everything after its opening.
• Lexical hits are narrowed to the matching chunk, so keyword results point at the relevant slice instead of the whole document.
• The index updates on write: memory is searchable immediately, not from a boot-time snapshot. Brain files are indexed into the brain collection on write too.
• The store resolves per profile, so profiles never share or cache each other’s memory index.
• The chunker is multi-byte safe: no more panics on UTF-8 boundaries.
• MEMORY.md recall is ranked with BM25 instead of shared-word counts (#996), and recall folds Latin diacritics so accented queries match.

In-tree Memory Store (v0.3.81)

The qmd binary dependency is gone (#1032). OpenCrabs now owns its memory store in-tree (src/memory/): SQLite FTS5 for lexical search plus vector embeddings in one store, resolved per profile. One fewer external binary to install or break, and the store schema ships with the binary.

External Index Paths (v0.3.81)

Memory search can read indexes that live outside the profile directory (#1051, #1055):

[memory]
# Each entry is a bare path string or a { path, pattern } table.
# Relative paths resolve against the OpenCrabs home (not the session cwd),
# so the index stays stable across /cd and profile switches.
extra_paths = [
  "~/knowledge/product-docs",
  { path = "~/knowledge/website-mirror", pattern = "docs/**/*.md" },
]

Indexed files are searchable within one sweep interval (~5 min), no restart needed. Results come back as ranked excerpts with file paths via memory_search scope="external"; the agent can then read the full file for verbatim quotes.

Gotchas: UTF-8 text only (binary files are skipped with a warning); HTML files index as raw markup, so mirror sites to .md first; nested roots and symlinks are skipped by design; test external scope from an owner session, group sessions return nothing unless you set external_allowed_in_shared = true.

Build a knowledge base from any docs site

web_scrape sitemap mode pairs with extra_paths into a complete, zero-cost pipeline: scrape a site to markdown, index it, then ask questions answered verbatim from those docs (see Web Scraping):

[memory]
extra_paths = ["scrapes/docs.example.com"]

1. web_scrape url="https://docs.example.com" mode=sitemap export=true: every sitemap page saved as clean markdown under scrapes/, local extraction, no AI/API cost (hard cap: 100 pages per scrape)
2. Point extra_paths at the scrapes directory (relative paths resolve against the OpenCrabs home)
3. Ask anything: answers are grounded in and quoted from the indexed docs

Structural Code Search Upgrades (v0.5.1)

The code-graph answers (who calls X, what does X call, impact of X) got four upgrades:

• Truncation is now visible. Caller sets in real repos are unbounded (5,000+ call sites exist), so every structural listing that had to cut ends with a marker line ( “… and N more callers of X (re-query with higher n or offset)”) and sets beyond 500 collapse into a per-file rollup instead of one-liners. Nothing is silently chopped anymore.
• Offset pagination. memory_search accepts an offset alongside n for structural listings, so the full set can be walked page by page. Ranked text/vector results stay rank-truncated: the window applies to listings only.
• Depth-2 impact chains. impact of X now walks two hops over the call-edge graph, surfacing the callers-of-callers that a direct query misses.
• Cleaner hits. External code hits render repo-relative paths instead of absolute machine paths, and every scope=all hit carries a corpus provenance tag (which index the fact came from), so a memory answer and a code-graph answer can be told apart (#89).

Embedding Hardening (v0.3.81)

Embedding API calls now carry timeouts, a vector gate (malformed or empty vectors never reach the store), and non-blocking writes (embedding failures never stall the turn) (#1062). /doctor reports embedding health, and a sweep finds unembedded documents and backfills them (#1069, #1067).

Embedding Modes

OpenCrabs supports three embedding configurations:

1. Local GGUF (default): downloads a 300MB embedding model and runs it locally via llama.cpp
2. OpenAI-compatible API: configure external embedding providers (OpenAI text-embedding-3-small, Ollama nomic-embed-text, Jina, LM Studio, or any /v1/embeddings endpoint) via [memory.embedding] config with url, model, api_key, dimensions
3. FTS5-only: pure keyword search with zero RAM overhead. Set [memory] vector_enabled = false. Auto-detects VPS environments and configures automatically

Context Compaction

When context reaches ~80% capacity, OpenCrabs automatically compacts:

1. Summarizes the conversation so far into a comprehensive continuation document
2. Clears old messages from context
3. Continues with the summary as context

Manual compaction: type /compact in chat.

Auto-Save Triggers

The agent saves to memory when:

• New integrations are connected
• Server/infrastructure changes occur
• Bugs are found and fixed
• New tools are configured
• Credentials are rotated
• Architecture decisions are made
• You say “remember this”
• Errors take >5 minutes to debug

Proactive Memory Surfacing (v0.3.76)

The agent now surfaces relevant memory without being asked. When a conversation topic matches something stored in MEMORY.md or daily notes, the relevant context is loaded and injected automatically. Previously, memory was only recalled when the agent explicitly called memory_search or load_brain_file. Now the system proactively checks for relevant context on each turn, so the agent brings up past decisions, server details, or preferences that apply to the current conversation without you having to say “check your memory.”

Confidence, Decay and Pruning (v0.5.3)

MEMORY.md facts carry confidence and decay over time (#1643): a belief’s trust drops as it goes unused and unverified, so stale claims stop outranking fresh ones when memory is recalled. Decay is config-driven through the [epistemic] section.

Cold content is managed in two passes (#1657):

• Archive pass: cold MEMORY.md sections move to memory/archive/ with a backup and reindex, instead of silently accumulating forever.
• opencrabs memory prune: a dry-run preview (the default) of cold beliefs (key, confidence, hits, age) and cold sections (heading, bytes). --apply archives the sections first, then sweeps the remaining cold beliefs. --max-age-days <N> overrides the cold threshold (default: 90).

Brain Files

See Brain Files for the full list of files the agent reads on startup.

Brain Files

Brain files define the agent’s personality, knowledge, and behavior. They live at ~/.opencrabs/ and are loaded on every session start.

Startup Read Order

1. SOUL.md: Personality and values
2. USER.md: Your profile and preferences
3. memory/YYYY-MM-DD.md: Today’s notes
4. MEMORY.md: Long-term memory
5. AGENTS.md: Agent behavior guidelines
6. TOOLS.md: Tool reference and custom notes
7. CODE.md: Coding standards and file organization
8. SECURITY.md: Security policies
9. HEARTBEAT.md: Periodic check tasks

File Reference

SOUL.md

Agent personality. Core truths: strong opinions, brevity, resourcefulness, honesty. Hard rules: never delete files without approval, never send emails without request, never commit code directly.

USER.md

Your profile: name, location, timezone, role, specialties, communication preferences, pet peeves.

AGENTS.md

Comprehensive agent behavior docs: memory system, safety rules, git rules, workspace vs repository separation, cron best practices, platform formatting, heartbeat guidelines.

TOOLS.md

Tool parameter reference, system CLI tools, provider configuration, integration details for all channels and services.

CODE.md

Coding standards brain template. Enforces: no file over 500 lines (target 100–250), types in types.rs, one responsibility per file, mandatory tests for every feature, security-first patterns. Rust-first philosophy, single binary, no runtime dependencies. The agent follows these rules when writing or reviewing code.

SECURITY.md

Security policies: third-party code review, attack playbook awareness, network security, data handling, incident response.

HEARTBEAT.md

Tasks for periodic proactive checks. Keep empty to skip heartbeat API calls. Add tasks for the agent to rotate through (email checks, calendar, weather, etc.).

BOOT.md

Startup procedures: check git log, verify build, greet human with context awareness.

Query-Based Loading (v0.3.76)

load_brain_file now accepts an optional query parameter that returns only the sections matching the query instead of the entire file. This saves significant context budget:

load_brain_file(name="TOOLS.md", query="telegram")
→ Returns only the Telegram-related sections, not the full 2000-line file

Whole sections are returned (never cut mid-section), so a rule is never truncated. This is especially useful for large brain files like TOOLS.md and AGENTS.md where loading the full file wastes 10K+ tokens on irrelevant content.

Customization

These files are yours. The agent reads them but you control the content. Templates are at src/docs/reference/templates/ in the source repo, compare your local files against templates when updating to pick up new sections without losing custom content.

New installs (v0.2.72+): CODE.md and SECURITY.md are automatically seeded on first run. Existing users can ask their crab: “Check my brain templates and update them if any are missing or outdated.”

Upgrading: Brain files are never overwritten by /evolve or /rebuild. After updating, ask your crab to compare templates against local files and patch in new sections.

User-owned files are never synced (v0.3.82)

SOUL.md, USER.md and MEMORY.md are excluded from upstream template sync (#1119). They hold your agent’s personality, your identity, and what it has learned about you, so upstream has no authority over them. Before this, every startup appended upstream sections into them, which grew one user’s SOUL.md from under 2 KB to nearly 5 KB, re-appending after each manual prune.

Seeding is unaffected: all three are still created on first run. Only the merge is forbidden. The remaining brain files (AGENTS, TOOLS, CODE, SECURITY, BOOT, HEARTBEAT) continue to sync normally.

Related (#1121): rules belong in AGENTS.md, not MEMORY.md. MEMORY.md is on-demand, reached only through memory_search, so a rule written there does not bind on a cold session and does not survive compaction. Facts go in MEMORY.md; anything that must always hold goes in AGENTS.md, which is always loaded.

Sessions

Sessions as Isolated Agents

A session in OpenCrabs is not a tab, not a window, not a chat thread. Each session is a fully independent agent with its own brain: conversation history, provider, model, working directory, tool state, approval policy, and context window. When you create a new session, you are spinning up a separate agent that knows nothing about any other session and shares nothing with them.

This is the core mental model: one session = one agent = one context. You can run dozens of sessions in parallel and they will never interfere with each other.

Zero Context Contamination

Sessions are completely isolated at every layer:

• Separate message queues: each session has its own queue. Messages are routed strictly to their originating session. No cross-session bleeding, even when 10 sessions are processing simultaneously.
• Separate provider and model: switching to Gemini in session A does not affect session B running Claude. Each session remembers its own provider independently.
• Separate working directory: /cd in one session does not change the working directory of any other session.
• Separate conversation history: full SQLite-backed history per session. No shared memory, no prompt pollution, no context bleed.
• Separate token tracking: cumulative usage, cost, and context window are tracked per session.

This isolation is guaranteed by Rust’s thread safety and async runtime. Each session runs as an independent tokio task with its own state, and the type system prevents accidental sharing at compile time. You can run split panes, channel sessions, background agents, and sub-agents all at once with zero risk of one session’s output leaking into another.

Switching Sessions Keeps the Transcript

Switching sessions with /sessions and coming back does not fold your transcript away. The fold state for every turn is keyed by a stable role and timestamp anchor, so a turn you had opened stays open across a reload, and a turn you had folded stays folded (#2155). A turn that is still running also stays unfolded while it runs, so the work in flight stays visible instead of hiding behind a collapsed header.

The display window keeps a bounded number of recent messages in the pane rather than trimming by token budget, so one huge tool result can no longer evict the rest of the conversation. The hidden-count marker still tells you how many older rows are out of view, and Ctrl+O pages back through them.

Workflow Patterns: One Session Per Context

The power of isolated sessions becomes clear when you treat each one as a dedicated agent for a specific domain:

Pattern 1: DevOps for a Server

Create a session for a specific server or infrastructure concern. Send a first message like "Devops for server XYZ, monitor nginx builds, manage cronjobs, handle deployments, run log cleanups". The session locks into that context: working directory set to the server’s codebase, provider set to a fast model for quick ops tasks, history filled with that server’s deployment patterns. Come back to it days later and the agent remembers every previous deploy, every cron change, every nginx config tweak.

Pattern 2: Mobile App Development with a Co-Founder

Create a session named mybrand-mobile and connect it to a Telegram group with your co-founder. The agent is locked into the Dart/Flutter codebase, the product design context, and the mobile-specific toolchain. Your co-founder can ask questions, request design changes, or review PRs directly in Telegram while you work on backend tasks in a separate session. The two contexts never mix.

Pattern 3: Production Logs with a Team on Slack

Create a session named mybrand-prod-logs-debug and connect it to a Slack channel. Your team can ask questions about production, staging, or dev logs without you having to context-switch. The agent stays locked into log analysis mode with the right SSH aliases, the right log paths, and the right debugging tools. Meanwhile, your main TUI session is free for development work.

The key insight: you never have to explain the full context again. Once a session is locked into a domain, every follow-up message inherits that context automatically.

Session Context Integrity (v0.3.78)

Two fixes harden session_context (the tool agents use to store key-value state):

• Atomic writes: context writes now use atomic file operations, eliminating trailing-character corruption that could occur when a write was interrupted mid-flush. Previously, a crashed write could leave a JSON file with a truncated trailing character, making the entire context unreadable.
• Concurrency pinning: concurrent session_context calls from parallel tool executions no longer race on the same file. A concurrency pin serializes writes, and temp files are cleaned up after each operation.

Creating Sessions

• TUI: Press Ctrl+N or type /new
• Channels: Type /new in any channel

The First Message Matters

When you create a new session, the first message you send becomes the seed for the entire session’s context. OpenCrabs uses it to:

1. Auto-generate a session title: a background LLM call extracts a 3-8 word descriptive title from your first message. This runs asynchronously and never enters the conversation context.
2. Anchor the agent’s context: the initial message establishes what this session is about, what codebase it should focus on, what tools it should prioritize.

Good first messages are specific and contextual:

• "Devops for server XYZ: nginx, cronjobs, deployments, log cleanups"
• "Flutter mobile app for mybrand: Dart codebase at ~/srv/mobile/mybrand"
• "Debug production logs for mybrand staging and dev environments"

The auto-title will generate something like Devops Server XYZ, Mybrand Mobile Flutter, or Mybrand Prod Logs Debug. You can always rename it later.

Switching Sessions

• TUI: Press Ctrl+L to open the sessions screen, navigate with arrow keys, press Enter to select
• Channels: Type /sessions to see recent sessions with inline buttons

Renaming Sessions

Auto-generated titles are a starting point, not a final name. You can rename any session:

• TUI: Press Ctrl+L, navigate to the session, press r to rename
• Agent-initiated: the rename_session tool lets the agent rename the current session with a descriptive title when the conversation evolves beyond its original scope

Empty or whitespace-only titles are rejected (v0.3.30, #128).

Session Screen

The sessions screen shows:

• Session name
• Created date
• Provider/model badge
• Working directory
• Token usage
• Context window usage (current session)
• Status indicators (processing spinner, pending approval, unread)

Sub-Agent Sessions Stay Out of Your Way (v0.3.79)

Every spawned sub-agent creates a session titled subagent: {label}, and a busy turn can create several. They are an implementation detail of one tool call, so since v0.3.79:

• Sub-agent sessions are hidden from session lists the moment they exist, your session screen only ever shows your sessions.
• They are automatically purged once past agent.subagent_session_ttl_days (default 7; set 0 to keep them forever).
• Your own sessions are never touched: the cleanup sweep matches the subagent: title prefix only.

Per-Session State

Each session remembers:

• Provider and model: Switch to Claude in one, Gemini in another
• Working directory: /cd persists per session
• Conversation history: Full message history in SQLite
• Token count and cost: Cumulative usage tracking

v0.3.74 hardened per-session isolation:

• Per-session working directory: the working directory is isolated per session so it can’t leak across concurrent sessions (#703).
• Restore session provider: a session’s saved provider is restored before its turn, so it never accidentally runs on the global default (#704).
• Don’t persist involuntary remap: an involuntary provider/model remap is not persisted over a session’s saved pair (#705).

Session Management

Background Processing

Sessions can process in the background while you work in another session. The sessions screen shows:

• Spinner for actively processing sessions
• ! for sessions waiting for tool approval
• Dot for sessions with unread messages

Background Tasks (v0.3.74)

Long-running shell commands no longer block your session. When the agent runs a known-long command (cargo test, cargo build, npx remotion render, gh run watch, and similar), OpenCrabs auto-promotes it to a background task (#722): the command runs detached, the session is freed immediately, and the agent can keep working (or you can switch away) while it finishes.

When the task completes, the result is injected back into the originating session and resumes it automatically. On the TUI the session picks up at the next tool-call boundary; on Telegram the resume is delivered to the same chat (#722). No polling loops, no re-running the command to “check”, the completion report arrives on its own.

The agent is told via its preamble that long tasks run in the background and resume the session when done, so it wraps up or moves on instead of sitting in a wait loop (#722).

Two related session fixes landed in the same release:

• No perpetual resume: a completed session no longer resumes on every restart. Resume turns are not re-tracked as pending requests, so a finished background task stays finished across restarts (#729).
• No lingering cancelled query: a query cancelled before the agent replied, plus its empty assistant placeholder, are dropped as a pair so they don’t linger in context and duplicate on resend (#730).

Background-Task Resume Everywhere (v0.3.75)

v0.3.74 introduced background-task resume on the TUI and Telegram. v0.3.75 extends it to every channel: Discord, Slack, WhatsApp, and the interactive CLI agent now resume your session the moment a long task finishes, powered by a shared bg_resume helper so the behaviour is identical across surfaces.

A few refinements make background tasks easier to live with:

• Indicator on the input border: the background-task indicator moved onto the input border, and a detached command shows what it’s currently doing.
• No scaffolding in chat: a background task’s system scaffolding no longer reaches the chat.
• Restart-killed tasks reported: background tasks a restart killed are reported instead of leaving the session waiting forever.

Split Panes

Run multiple sessions side by side with tmux-style pane splitting. Each pane is a fully isolated agent, see Split Panes for details.

State Management

v0.2.92 improved session state tracking:

• Session reload after cancellation: After Esc+Esc cancel, session context reloads from DB to pick up any changes made during the cancelled operation
• Cached state cleanup: Deleting a session now clears stale pane cache entries, preventing phantom state on restart
• CLI tool segment persistence: Tool results from CLI providers (Claude CLI, OpenCode CLI) are now saved to DB alongside regular messages, preserving correct text/tool interleaving across restarts
• Case-insensitive tool input: Tool input descriptions use case-insensitive key lookup, fixing failures when providers return different casing

Channel Sessions

All channels (Telegram, Discord, Slack, WhatsApp, Trello) persist sessions in SQLite by channel/group title. Sessions survive process restarts, no more lost context after daemon restart. Each channel group gets its own isolated session, while owner DMs share the TUI session. Cross-channel stable session suffixes ([chat:<id>]) ensure reliable session resolution across Discord, Slack, and WhatsApp (v0.3.29).

Session-Routed Recovery Reports (v0.3.81)

Crash-recovery reports route by session (#1037): a resumed turn reports back to the session that owned it, not to whichever session happened to boot the recovery. Multi-session setups no longer cross-deliver recovery noise.

Split Panes

OpenCrabs supports tmux-style pane splitting in the TUI. Run multiple sessions side by side, each with its own provider, model, and context, all processing in parallel.

Splitting

How It Works

Each pane runs an independent session. You can have one pane writing code with Claude while another reviews tests with Gemini. The status bar shows [n/total] to indicate which pane is focused.

• Independent providers: Each pane can use a different AI provider and model
• Independent context: Conversation history is isolated per pane
• Parallel processing: All panes process concurrently via Tokio
• Persistent sessions: Each pane’s session is saved to SQLite like any other session

Example Layout

┌──────────────────────┬──────────────────────┐
│  Session 1 (Claude)  │  Session 2 (Gemini)  │
│  Writing code...     │  Reviewing PR...     │
├──────────────────────┴──────────────────────┤
│  Session 3 (OpenRouter)                      │
│  Running tests...                            │
└──────────────────────────────────────────────┘

Split vertically with _, then horizontally with | in the top pane.

Persistent Layout

Split pane configuration (splits, sizes, focused pane) saves to ~/.opencrabs/pane_layout.json on quit and Ctrl+C. On restart, your layout is restored exactly as you left it. Each restored pane preloads its session messages from the database, so content is visible immediately instead of blank.

Non-Focused Panes

Non-focused panes show compact tool call summaries and stripped reasoning text. Tool groups display as single collapsed lines matching the focused pane style. All panes auto-scroll to the bottom when new messages arrive.

v0.2.92 fixed several rendering issues:

• Tool calls no longer show a perpetual “running” spinner after completion
• Scroll position correctly tracks for inactive panes
• Stale cache is cleared when sessions are updated or deleted

State Management

Deleting a session now properly cleans up cached pane state. Previously, deleting a session left stale entries in the pane cache, which could cause phantom panes on restart.

Live Background Updates (v0.3.36)

Inactive panes now update live in the background. Previously, non-focused panes only refreshed when you switched focus to them. Now a background-session live-state cache routes IntermediateText and QueuedUserMessage events into per-session deltas, so you can watch tool calls and responses appearing in other panes in real time without switching focus.

Provider/model contamination prevention: When closing or switching panes, the old session’s provider is captured before the switch. This blocks cross-provider model leaks at 27 call sites throughout the codebase. The footer always shows the correct provider+model for the focused pane.

Ctrl+N binds the focused pane and live-refreshes the footer title, so new sessions show up immediately in the status bar.

Reasoning Expand (v0.3.74)

Reasoning blocks now cycle through three states instead of toggling open/closed. Click a reasoning block (or press Ctrl+O) to cycle: collapsed → capped → full. The capped middle state shows a bounded preview so a long chain-of-thought never floods the viewport (#727, #726).

Two refinements make expanding predictable:

• Anchor block on expand: the clicked block’s header is pinned to its screen row, so expanding or collapsing grows the block in place instead of jumping the viewport (#728).
• Click vs drag on mouse-up: click-vs-drag is decided on mouse-up, so a click-drag selects text (for copying) instead of toggling the expand state (#726).

Version in the UI (v0.3.74)

The running OpenCrabs version now shows on the TUI header and in channel /help and /usage output (#696), so you always know which build a session is on.

Double-Escape Returns the Query (v0.3.74)

Pressing Esc twice before any reply now returns the query to the input box and removes it from the conversation (#698), so a half-typed prompt you cancel doesn’t linger as an empty turn.

Per-Turn Headers (v0.3.75)

Every turn now gets a one-line header summarising the work that turn did, and the turn’s working-out folds up into it. OpenCrabs infers turn boundaries so each turn can be grouped, then folds the narration, intermediate text, and tool calls underneath the header.

The view stays clean by default:

• Fold every turn by default: turns fold as soon as they settle (and even while still running), so settled work collapses out of the way instead of scrolling off screen.
• Fold live: intermediate text folds while the turn is still running, and stale narration the model kept thinking past is collapsed.
• Readable folded turn: a folded turn stays readable and holds its place when toggled, and the tool-call summary stays at full visibility.
• Short live-thinking excerpt: live thinking shows a short excerpt with room to finish a thought, not a scrolling wall.
• Labelled token counter: the live token counter is labelled as a turn total and shows the ctx budget; ctx dropped from the spinner since it already shows under the input.

Expanding a turn is smooth: the header is kept after expand, and expanding no longer scrolls the view up by its own size.

TUI Improvements (v0.3.76–v0.3.78)

Steps AND Tools Display (v0.3.76)

The TUI now shows both steps and tool calls in the turn view. Previously it was either/or: if tool calls existed, steps were hidden. Now both render, with steps providing the narrative and tool calls showing the mechanical detail.

Background Task Position (v0.3.77)

Background task feedback moved from the left border to the right border of the input box. This prevents it from colliding with the context budget footer on the left.

Duplicate-Submit Guard (v0.3.76)

Pressing Enter twice quickly no longer submits the same message twice. The TUI drops a re-submitted message if the running turn is already answering it.

Command Labelling (v0.3.76)

Commands in the TUI are now labelled by what they run (e.g. “cargo test”) instead of the working directory. Makes the activity feed readable at a glance.

Deliverable Report Visibility (v0.3.78)

When a turn produces a deliverable report (audit, comparison, analysis), the report stays visible even when the turn folds. Previously, folding a turn would hide the report along with the working-out.

Background Running Indicator (v0.3.78)

The “running” indicator is now cleared before delivering the final response. Previously, the indicator could linger for a moment after the response appeared, creating a visual glitch.

Limits

There is no hard limit on pane count – you can run as many as your terminal fits. Each pane is a full session with its own token tracking and working directory.

Dynamic Tools

Define custom tools at runtime without recompiling. Tools are defined in ~/.opencrabs/tools.toml and can be created, removed, and reloaded on the fly.

Defining Tools

Create ~/.opencrabs/tools.toml:

[[tools]]
name = "deploy"
description = "Deploy the application to production"
executor = "shell"
command = "cd {{project_dir}} && ./deploy.sh {{environment}}"

[[tools]]
name = "check-status"
description = "Check service health"
executor = "http"
method = "GET"
url = "https://api.example.com/health"

Executors

Template Parameters

Use {{param}} syntax for dynamic values. The agent fills these in when calling the tool:

[[tools]]
name = "search-logs"
description = "Search application logs for a pattern"
executor = "shell"
command = "grep -r '{{pattern}}' /var/log/myapp/ --include='*.log' -l"

Runtime Management

The tool_manage meta-tool lets the agent manage dynamic tools during a session:

• Create: Add a new tool definition
• Remove: Delete an existing dynamic tool
• Reload: Re-read tools.toml without restarting

Dynamic tools appear alongside built-in tools in the agent’s tool list. Enable or disable individual tools without restarting the process.

Per-Parameter Value Coercion (v0.3.24)

Dynamic tools defined in tools.toml can now handle empty-string or null parameters gracefully. When a parameter arrives as "" or null, the engine substitutes a configured value before rendering the command template.

[[tools]]
name = "deploy"
description = "Deploy to environment with optional verbose flag"
executor = "shell"
command = "cd {{project_dir}} && ./deploy.sh --env {{environment}} {{verbose}}"

[[tools.deploy.params]]
name = "verbose"
type = "string"
required = false
coerce_empty_to = "--quiet"

A shell tool with an optional --verbose flag no longer breaks when the parameter is omitted. The engine substitutes --quiet (or any configured default) instead of passing an empty string.

(#95)

External contributions now enable tools.toml to be loaded in run mode and agent mode (not just the TUI). Previously, dynamic tools only worked in the interactive TUI session. Now they’re available across all modes, allowing headless automation and scripted workflows to use custom tools.

(#79: thanks @leshchenko)

Shell Parameter Escaping (v0.3.35)

Dynamic shell tool parameters now properly escape single quotes, preventing command injection edge cases when user-supplied values contain quotes. Contributed by @leshchenko1979.

Browser Automation

OpenCrabs includes native headless Chrome control via the Chrome DevTools Protocol (CDP). No Selenium, no Playwright, direct browser control built into the binary.

Requirements

• A Chromium-based browser installed (Chrome, Brave, Edge, or Chromium)
• Feature flag: browser (enabled by default)

OpenCrabs auto-detects your default Chromium browser, no manual path configuration needed.

Browser Tools

How It Works

The browser is lazy-initialized as a singleton, it only launches when the agent first needs it. It runs in stealth mode with a persistent profile directory, so cookies and sessions survive across tool calls.

On macOS, display auto-detection enables headed mode when a display is available, falling back to headless in CI or daemon environments.

Exemple

Ask the agent:

“Go to our staging site, log in with the test account, navigate to the dashboard, and take a screenshot”

The agent will chain navigate → type (username) → type (password) → click (login button) → navigate (dashboard) → screenshot: all autonomously.

Inventory Mode (v0.3.80)

browser_find now works without a pattern (#1022). Call it bare and it enumerates every visible interactive element on the page (links, buttons, inputs, selects, textareas, role=button elements, onclick handlers, tabindex elements, labels, and disclosure widgets) each stamped with a selector and index you can click directly.

This is the structural fix for the screenshot-as-discovery loop: instead of screenshotting repeatedly and guessing selectors, the agent gets the page’s clickable inventory in one call. When browser_screenshot reports an identical page, the hint now nudges toward inventory mode.

Shadow-DOM Resolution (v0.5.2)

Selector resolution is shadow-DOM aware: an element inside one or more shadow roots is reached by piercing the roots along the path, so web components and widget libraries that host their UI in shadow trees are automatable like light-DOM content. Applies across the browser tools (click, type, find, screenshot targeting).

Configuration

No configuration needed. The browser feature is enabled by default. To disable it at build time:

cargo build --release --no-default-features --features "telegram,discord,slack"

Cron Jobs

Schedule tasks to run on a recurring schedule. Cron jobs can run in isolated sessions or wake the main session.

CLI Management

# Add a job
opencrabs cron add \
  --name "Morning Report" \
  --cron "0 9 * * *" \
  --tz "Europe/London" \
  --prompt "Check emails, calendar, and give me a morning briefing" \
  --deliver-to telegram:123456

# List all jobs
opencrabs cron list

# Enable/disable (accepts name or ID)
opencrabs cron enable "Morning Report"
opencrabs cron disable "Morning Report"

# Remove (accepts name or ID)
opencrabs cron remove "Morning Report"

Agent Management

The agent can also manage cron jobs via the cron_manage tool:

"Create a cron job that checks my emails every morning at 9am"

Since v0.3.80, cron_manage supports an update action that patches an existing job in place (#966), change the schedule, prompt, model, or delivery target without deleting and recreating the job.

Options

Multi-Target Delivery

deliver_to accepts comma-separated targets to send results to multiple destinations simultaneously:

opencrabs cron add \
  --name "Morning Report" \
  --cron "0 9 * * *" \
  --prompt "Give me a morning briefing" \
  --deliver-to "telegram:-12345,http://webhook.example.com/notify"

Supported targets in any combination:

• telegram:CHAT_ID or telegram:-GROUP_ID
• discord:CHANNEL_ID
• slack:CHANNEL_ID
• whatsapp:PHONE_OR_JID
• http://... or https://... (webhook URL)

Target URLs (v0.5.1)

Since v0.5.1 every delivery field also speaks a unified oc:// target scheme, resolved by a central resolver against the live channel bindings (issue #148):

Target URLs are resolved once, at create/update time, and the concrete channel target is baked into the job; if an unbaked URL ever reaches fire time the run fails loudly instead of resolving against a possibly-changed world.

Forum-topic delivery (v0.5.1, opt-in)

telegram:CHAT_ID:THREAD_ID (or the oc://telegram/<chat>/<thread> form) delivers into a specific topic of a forum group. It is deliberately opt-in: the chat must actually be a forum and the topic must exist: an invalid thread target is rejected loudly at fire time, never silently re-routed to the general topic. When a job is created from inside a thread (here/oc:// form), the origin thread id is persisted so the result lands back in the same topic (#104).

Results are stored in the DB via the cron_results table regardless of delivery target, so you can query past execution results with opencrabs cron results <name>.

Trigger-gated jobs (v0.5.3)

A job can carry a pre-flight trigger: at each fire time the scheduler runs a shell command first, and only executes the prompt when a condition on that command’s result is met. This turns scheduled jobs from “fires into the void every hour” into “acts when something actually happened” (a file appeared, a health check failed, a log line matched) (#233).

Set it through the cron_manage tool at create or update time:

trigger_on conditions

Semantics

• Condition not met → the run is short-circuited at 0 tokens and recorded as a skipped/success run. The prompt never executes, nothing is delivered.
• Trigger command errors or times out → the run is recorded as an error; the prompt still does not execute.
• Empty prompt with a trigger → direct 0-token delivery: the formatted trigger output (goal_template, or the raw output) is delivered to deliver_to without an agent turn at all.
• set_goal → the fired trigger dispatches into the target session as an active goal, so the session’s agent works the condition it detected rather than just echoing output.

Put the watching in trigger_cmd (deterministic, cheap, script-runner pattern), the condition in trigger_on, and the acting in the prompt or goal.

Scheduler Lock (v0.3.65)

The cron scheduler uses a file lock to prevent duplicate job execution. Only one scheduler instance can run per profile at a time. If you accidentally start OpenCrabs twice, the second instance won’t fire duplicate cron jobs.

Heartbeat vs Cron

Use heartbeat (HEARTBEAT.md) when:

• Checks are periodic but timing is flexible (~30 min)
• You want to reduce API calls by batching
• Tasks share the main session context

Use cron when:

• Exact timing matters (“9:00 AM every Monday”)
• Task needs isolation from main session
• You want a different model or thinking level
• Output should deliver to a specific channel

Plans

Plans provide structured multi-step task execution with a live progress widget in the TUI.

Creating a Plan

Ask the agent to plan a complex task:

"Plan the migration from PostgreSQL to SQLite"

The agent uses the plan tool internally to create a plan with:

• Title and description
• Technical stack
• Risk assessment
• Test strategy
• Ordered tasks with dependencies and complexity ratings

Plan Lifecycle

1. Draft: Agent creates the plan and adds tasks
2. Finalize: Agent calls finalize which triggers the tool approval dialog
3. Approved: You approve in the tool dialog, plan status becomes Approved, and the agent begins executing tasks immediately
4. In Progress: Tasks execute in dependency order
5. Completed: All tasks done

In ask mode (default), the finalize step triggers the tool approval dialog, you review the full plan before execution begins. In auto-approve mode, finalize is auto-approved and the agent plans and executes without pausing.

Plan Requirement Gate

A turn that crosses a threshold of tool calls has to stop and write a plan before it continues (#2128). This is what keeps a sprawling refactor from being discovered after twenty files have already changed: you see the shape of the work, and you get a chance to say no before it lands.

The gate is configurable under [agent]. A turn that already has a live plan is never gated again, and a session configured to run autonomously is not stalled by an approval prompt it was told to skip.

Task States

Each task in a plan can be:

• Pending (·): Waiting for dependencies
• InProgress (▶): Currently executing
• Completed (✓): Done
• Skipped (✓): Manually skipped
• Failed (✗): Execution failed
• Blocked (·): Dependencies not met

TUI Plan Widget

When a plan is active, a live checklist panel appears above the input box showing:

• Plan title and progress counter (e.g. 3/7)
• Progress bar: Visual ██████░░░░ bar with percentage
• Task list: Up to 6 tasks visible with status icons and task numbers
• Overflow indicator: ... (N more) when tasks exceed the visible limit

The widget updates in real-time as the agent completes each task.

Managing Plans

Plans are managed through natural language:

"Approve the plan"
"Reject the plan"
"What's the plan status?"
"Skip task 3"

The agent handles plan creation, approval, execution, and status reporting through the plan tool.

Mid-Plan Insertion (v0.3.36)

Tasks can be inserted at any position in an existing plan using insert_after:

plan(operation: "add_task", insert_after: 3, title: "Re-run tests after fix", ...)

This inserts the new task as task #4, and all existing tasks from #4 onward are renumbered automatically. Dependencies between tasks are preserved through the renumber.

This is useful when a later task introduces a bug caught by an earlier test. Instead of re-opening the completed test task, insert a fresh re-test task right after the fix.

Finished Checklist Persistence (v0.3.76)

When a plan completes all tasks, the finished checklist now stays on screen instead of disappearing. You can review the final state (all tasks marked ✓) without having to ask “what was the plan?” again. The completed card renders its final state with the full task list and progress bar at 100%.

Epistemic Orient Gate (v0.3.78)

Plan execution is now gated behind an epistemic Orient phase before any task starts. The agent must:

1. Observe: gather ground truth (read files, check state)
2. Orient: map observations against current beliefs and goals
3. Decide: form intention, confirm alignment and safety
4. Act: execute through mechanical gates