Introduction

O OpenCrabs é um agente de orquestração de IA auto-hospedado e agnóstico de provider que corre como um único binário Rust. Automatiza o teu terminal, browser, channels (Telegram/Discord/Slack/WhatsApp/Trello) e codebase, respeitando a tua privacidade e mantendo-te no controlo.

11,091 testes em providers, ferramentas, channels, TUI, self-healing e automação de browser.

O Que Distingue o OpenCrabs

Zero Telemetria, Nem por Opção

• O OpenCrabs nunca liga para casa. Nunca. Sem analytics, sem tracking, sem estatísticas de utilização, sem logs remotos, sem relatórios de falhas
• As tuas conversas, ferramentas, memória, configuração e chaves de API nunca saem da tua máquina
• O único tráfego de saída é o que inicias explicitamente: chamadas a APIs de LLM, pesquisas web, comandos GitHub, automação de browser
• Não é uma checkbox de política de privacidade: não há código de telemetria para desativar, nenhuma flag de opt-out, nenhum serviço de analytics para bloquear. Simplesmente não há nada para enviar

Agnóstico de Provider por Concepção

• 16 providers integrados + 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
• Integração CLI nativa: usa o Claude Code CLI, OpenCode CLI, Codex CLI e Command Code CLI como providers sem chaves de API
• Cadeia de fallback persistente: failover automático em rate limits ou erros, persistência com noção de estado que sobrevive a reinícios
• Prompt caching em Anthropic, OpenRouter, Gemini e Qwen DashScope reduz custos até 95%
• Override da janela de contexto: limita ou expande o contexto de qualquer model via config (o provider OpenCrabs incorporado é a exceção: a sua janela está fixada em 200k)
• Xiaomi MiMo: mais de 30 models incluindo a série de reasoning MiMo, provider com chave
• Moonshot AI (Kimi): endpoints do plano API (api.moonshot.ai) e do plano Coding (api.kimi.com), config de reasoning-effort, janela de contexto por nível de plano

Multi-Agent Orchestration

• As sessions são agentes totalmente isolados, cada uma com o seu próprio brain, provider, model, diretório de trabalho e histórico
• Sub-agentes tipados: general, explore, plan, code, research com acesso a ferramentas adaptado
• Orquestração de equipas: team_create, team_broadcast, team_delete para workflows coordenados
• Overrides de provider/model por chamada: mistura models entre equipas (planear com GLM, programar com Deepseek, rever com Kimi)
• Protocolo A2A: gateway JSON-RPC 2.0 para comunicação agente-a-agente

Comunicação Nativa dos Channels

• Telegram, Discord, Slack, WhatsApp, Trello, integração completa de bot com DMs, grupos e threads
• Mensagens ricas no Telegram: tabelas nativas, títulos, listas, matemática via config rich_messages
• Streaming de mensagens em rascunho: atualizações “a escrever…” em direto enquanto os tokens são gerados nas DMs
• Blocos colapsáveis: secções <details>/<summary> para outputs longos
• Isolamento de session por tópico de fórum: cada tópico em supergrupos do Telegram tem a sua própria session
• Reações no Telegram: o bot lê as reações emoji recebidas e pode responder com uma reação em vez de uma mensagem quando isso encaixa
• Reações de enquadramento (v0.3.61): reações recebidas lidas por sentimento, o agente trata o utilizador pelo primeiro nome
• Reações a meio do turn (v0.3.61): uma reação durante um turn em execução é injetada no loop atual em vez de disparar um segundo turn
• Sugestões de seguimento (v0.3.69): follow-ups opcionais de toque-para-enviar no Telegram, Discord, Slack e WhatsApp; preencher-sem-enviar no TUI
• Reafixar cartão de plano no Telegram (v0.3.71): reafixa o cartão de plano e enrola o texto nele quando fica enterrado
• Captura integral do histórico de grupos (v0.3.73): persiste todas as mensagens de grupo no histórico, mesmo de remetentes e bots fora da allowlist
• Interlocutor de grupo correto (v0.3.73): deixa de tratar um remetente do histórico do grupo como o interlocutor atual
• Herança de sessions: o /new herda o diretório de trabalho da tua session mais recente
• /goal em todos os channels: define objetivos autónomos a partir do Telegram, Discord, Slack e WhatsApp
• Suporte de voz: Whisper STT local + Piper TTS, totalmente offline
• Recuperação de falhas entre channels: pedidos pendentes regressam ao channel de origem no reinício
• /cowork: cria workspaces partilhados a partir de channels e do TUI
• /rename, /profiles, /cd, gere sessions, profiles e diretórios a partir de qualquer channel

Self-Healing e Auto-Melhoria

• Recursive Self-Improvement (RSI): o agente analisa o desempenho, identifica padrões e reescreve os ficheiros brain

• Deteção de phantom tool calls: apanha quando o model narra alterações sem executar ferramentas

• Self-heal de phantom calls (v0.3.72): apanha turns sem ferramentas que alegam efeitos secundários críticos (ship/push/tag/release)

• Edições de config só via config_manager (v0.3.74): o agente nunca edita à bruta o config.toml/keys.toml; cada escrita é validada antes de aterrar

• Dedup do brain (v0.3.75): o comando /dedup mais rastreios pós-escrita e semanais entre ficheiros evitam que os ficheiros brain derivem para duplicação, com aprovação por teclado inline no Telegram

• Dicas de ficheiros brain em falhas de ferramentas (v0.3.75), notas brain relevantes surgem automaticamente quando uma chamada de ferramenta falha ou dá erro

• Memória proativa (v0.3.76): memória relevante surge sem ser pedida quando o contexto da conversa corresponde a conhecimento armazenado

• Nomes naturais de models (v0.3.76): /models opus funciona; nomes coloquiais resolvem para IDs exatos de model

• Encaminhamento de provider plan/execute (v0.3.76): encaminha o planeamento e a execução para providers/models separados

• Timeout de thinking-loop (v0.3.78): apanha loops de reasoning infinitos, dispara a aplicação de phantom enforcement com fallback persistente

• Motor epistémico (v0.3.78): tracking de crenças com níveis de confiança, malha cognitiva OODA/BDI, gate de Orient antes da execução do plano

• Gate de verificação Ralph (v0.3.78): verificação de tarefas com noção de critérios e limite de iterações; as tarefas têm de cumprir os critérios de aceitação declarados

• Gates de segurança TOML (v0.3.78): blocklist de bash configurável em runtime com hot-reload, redação de segredos entre aspas, verificação de ficheiros brain

• Analytics do Mission Control (v0.3.78): filtro D/W/M, grelha de cartões 3 por linha, separadores phantom/model/streaming, DB de eventos dedicada

• Onboarding de OpenAI TTS (v0.3.78): seletor de voz e campo de chave de API no assistente de onboarding

• Instalação via Homebrew (v0.3.79): brew install opencrabs a partir do homebrew-core: binário pré-compilado, ambas as arquiteturas, sem toolchain Rust

• /restart e /exit (v0.3.79): reinicia ou desliga a partir de qualquer channel ou do TUI; só o owner nos channels, anuncia antes de agir

• Circuit breaker de quota (v0.3.79): providers com quota esgotada recebem um breaker com TTL e são saltados nas passagens de fallback; o esgotamento da cadeia é reportado explicitamente

• Estado de planos entre sessions (v0.3.79): os planos sobrevivem aos limites das sessions; a execução isolada de tarefas de plano vem ligada por defeito, o Ralph verifica no próprio diretório da session

• Sistema de temas (v0.5.0): presets verificados, um seletor interativo e os teus próprios temas em ~/.opencrabs/themes/*.toml; o truecolor é detetado com um nível de recurso ANSI-256, e um preset cujo contraste tornaria o texto ilegível é recusado

• Memória estrutural de código (v0.5.0): o tree-sitter constrói um índice de símbolos e de grafo de chamadas ao lado do índice de texto, por isso “quem chama X” percorre arestas de chamada reais enquanto as perguntas conceptuais mantêm o percurso de texto (#1324)

• Transferência de ficheiros por SSH (v0.5.0): um ficheiro largado numa TUI a correr num host remoto é obtido através da ligação já aberta, com um opencrabs drop-agent do lado do cliente (#1289)

• Veredictos de entrega do notify (v0.5.0): o session_notify devolve um resultado de envio legível por máquina, os recibos de injeção de profundidade 3 tornam o notify_id verificável, e a entrega é redirecionada para a session que detém o channel nesse momento

• Compactação em segundo plano (v0.5.0): o sumarizador corre fora do turno em vez de reter a session enquanto trabalha

• Redação do token na escrita (v0.5.0): um erro de provider que transporte um URL já não pode expor o token do bot num log, seja qual for a origem do registo (#1322)

• Userbot de Telegram só de receção (v0.5.0, experimental): captura MTProto protegida por feature com início de sessão local por QR/código/2FA; guarda texto autorizado para consulta e nunca age como o utilizador

• Ancoragem temporal (v0.5.1): o agente sabe sempre que horas são: cada turno traz uma marca temporal no fuso horário do utilizador, e o prompt do sistema permanece byte a byte estável para o cache do provedor (#1516)

• Sessões cron por job (v0.5.1): cada job agendado recebe a sua própria sessão, para que dois jobs em execução simultânea nunca partilhem contexto ou provedores (#1511)

• Gating por globs de skill (v0.5.1): a lista globs: de uma skill pode recusar chamadas de ferramentas sobre ficheiros correspondentes até que o agente tenha lido o corpo da skill (#1515)

• Escritas no config validadas pela estrutura (v0.5.1), a guarda de escrita e as sugestões de secção do config_manager derivam agora do próprio tipo Config, para nunca divergirem do código publicado (#1508)

• Propostas de plano recusadas à escrita (v0.5.1): um desenho de plano malformado rebate imediatamente com as secções em falta nomeadas, e uma escrita recusada restaura o scaffold em vez de apagar o rascunho (#1507)

• Backpressure de orçamento do provedor (v0.5.1): um provedor que reporta um orçamento de tokens de saída dispara uma única compactação com limites e uma retentativa, em vez de uma cascata de 400 (#1518)

• Tokens A2A vinculados e config só do owner (v0.5.1), os tokens A2A ligam-se ao gateway que os emitiu, e config.toml/keys.toml passam a modo exclusivo do owner, com segredos removidos dos logs

• Modo servidor ACP (v0.5.2): opencrabs acp fala o Agent Client Protocol sobre stdio JSON-RPC, por isso o Zed, o MonoCode e qualquer cliente ACP conduzem o mesmo brain que os teus channels usam, com streaming do progresso e aprovações a voltar até ao editor (#1540)

• Navegação com consciência de shadow-DOM (v0.5.2): a resolução de seletores atravessa shadow roots, por isso a automação chega a web components que antes eram invisíveis para as ferramentas

• Superfície completa do WhatsApp (v0.5.2): mensagens de voz nativas, vídeo/sticker/localização/contacto recebidos, votos em sondagens, recuperação de presença e media, confirmações de reação, streaming com edição no lugar, mensagens temporárias, bloqueio de contactos, fixar/reencaminhar/perfil, atualizações de estado, descoberta de newsletters, botões de native flow, histórico por conversa

• Tracing ao vivo e tabelas nativas no Discord (v0.5.2), turnos longos são transmitidos como uma resposta ao vivo com tracing, as respostas criam thread automaticamente, as tabelas markdown renderizam nativamente e os turnos com ferramentas deixam de publicar a resposta final duas vezes (#1603, #1608)

• Tópicos de fórum do Telegram e /clear (v0.5.2): criar/renomear tópicos de fórum com ligação à session, e /clear inicia uma session nova sem a chamada ao summariser (#1585)

• Orçamento do payload do menu de comandos (v0.5.2): o setMyCommands do Telegram rejeita silenciosamente corpos de pedido acima de ~7,8KB reportando BOT_COMMANDS_TOO_MUCH; as descrições passam a encurtar por níveis para o menu inteiro caber (#1613)

• Cron com triggers (v0.5.3): um job corre um pre-flight check e só executa quando a condição é satisfeita (output não vazio, exit code, regex), os runs saltados custam 0 tokens e um trigger disparado pode despachar um goal para uma session (#233)

• Windows de primeira classe (v0.5.3): shell handling por plataforma, leitura de ficheiros BOM/UTF-16, fallbacks de tilde e cwd, com a CI a compilar Windows e a fazer gate aos PRs (#627)

• Memória epistémica (v0.5.3): os factos do MEMORY.md ganham confidence e decay (#1643), as secções frias arquivam-se sozinhas e o opencrabs memory prune mostra o que ficou frio antes de tocar em nada (#1657)

• Motor de temas terminado (v0.5.3): todos os widgets do TUI resolvem as cores através do tema, com um guard de suite contra novos sítios de ANSI cru, e os temas podem declarar um canvas background (#1634)

• Polls de sugestões no WhatsApp (v0.5.3): conjuntos de follow-ups além do limite nativo de botões renderizam como poll, e um voto seleciona a opção (#1616)

• Família de sessions ACP (v0.5.4): os sessions são first-class na superfície ACP: o context meter é restaurado no load e acompanha as usage updates, o session/load repõe a transcrição e restaura o model do session, o set_model persiste entre processos, o session/set_mode nativo aplica a approval policy do lado do servidor, o session/compact faz push, e o session/new oferece um catálogo de models ao vivo

• Entrega interativa do terminal (v0.5.4): o !vi/!nano assumem o terminal de forma interativa e devolvem-no com o session intacto; apenas terminais Unix, no Windows mantém-se a captura por pipe (#1744, #1759)

• Paste & drop universal (v0.5.4): um router de attachments partilhado aceita qualquer tipo de ficheiro no paste ou no drop e classifica código, docs, arquivos e dados para cada um seguir o pipeline certo (#1740, #1743)

• Motor de pesquisa Serper (v0.5.4): o serper_search acrescenta resultados Google SERP, e o fan-out do web_search elimina duplicados por URL entre engines (#1731)

• Decision cache (v0.5.4): o decide_cached responde a decisões repetidas a partir de um anel de reutilização L1 com tiers shadow/live e config [decisions] (#1648)

• Custos reportados pelo provider e uma cadeia de timeouts unificada (v0.5.4), o ledger de usage prefere o custo que o provider reportou de facto em vez de estimativas de tabela (#1707), e os flags de timeout resolvem [providers.<name>] -> [agent] -> default em todos os providers (#1688)

• Comandos compilados /architecture e /attach, audit trail opcional (v0.5.4), ambos os comandos são distribuídos como arms compilados, e um audit trail opcional regista o que correu com um viewer /audit (#933, #1705)

• Superfície nativa do Discord (v0.5.5): inquéritos nativos via send_poll, respostas TTS entregues como mensagens de voz, e commands.toml projetado nos slash commands nativos para que os teus comandos apareçam no picker do Discord (#1848, #1849, #1850)

• Flow groups e governors de escrita (v0.5.5): o Discord e o Slack abrem o flow group no início do turno com um relógio ao vivo a cobrir o pensamento e o texto de atividade a liderar a linha, e um governor de escrita partilhado orçamenta cada edição e faz park em 429s (#1841, #1843, #1844, #1845, #1807, #1808, #1809, #1910, #1912, #2012)

• /respond_to e /cowork (v0.5.5): modos respond_to e open por canal na configuração, mais os dois comandos para os definir a partir do próprio canal (#2014, #2015)

• Disciplina de rate limit no Telegram (v0.5.5): polls getUpdates e handoffs de handler instrumentados para triagem de stalls, um piso de espaçamento sub-segundo entre superfícies com telemetry de admissão, uma pausa 429 por chat atrás de um único accessor Cooldown, e ligações markdown a ficheiros locais entregues como documentos (#1927, #1916, #1968)

• Ciclo de vida de sessions ACP v1 (v0.5.5): os cinco métodos v1 de ciclo de vida de session estão implementados e o plano é publicado como um plan update nativo v1 (#1815)

• Footer de diálogo partilhado, URLs clicáveis, timeline de onboarding no TUI (v0.5.5): todos os diálogos partilham um command footer com verbos de aprovação a/r diretos, URLs e caminhos de ficheiro são clicáveis, e o onboarding foi reconstruído como uma timeline de passos à esquerda com comandos de configuração diretos (#1775, #1772, #1979, #1980, #1981, #1982)

• Reforma de cron one-shot (v0.5.5): os jobs one-shot reformam-se na entrega em vez de voltarem a disparar um ano depois, cada execução entregue leva o seu run id, e os reports de cron do Discord chegam como um único post no fórum (#544, #1703, #1851)

• Primeira execução sem configuração (v0.5.11): uma instalação nova cai direto no chat com o provider incorporado já provisionado, config.toml e keys.toml criados, e o agente a cumprimentar-te. O assistente é opcional através de /onboard ou --onboard (#2079)

• Um primeiro turno que não pode abortar o processo (v0.5.11): as threads worker do agente correm numa stack de 16 MiB, por isso o primeiro turno já não transborda a stack predefinida (#2080)

• Tags de release só com CI verde (v0.5.11): o workflow de release lê a conclusão da run de CI do próprio commit antes de publicar. Uma run vermelha falha a release, uma run ainda em curso é aguardada, e um commit sem run também falha (#2078)

• O evolve reinicia as unidades certas (v0.5.11): o reinício agendado aponta para nomes de unidades resolvidos em vez do glob de descoberta opencrabs*.service, que também apanhava a unidade transitória que corre o reinício e fazia o systemd parar o seu próprio executor (#2081)

• As guest queries do Telegram passam a ter a superfície completa (v0.5.12): um tag num chat onde o bot nunca foi convidado corre a mesma superfície de ferramentas, o mesmo bloco de estado ao vivo e a mesma renderização rich de um turno normal, com um turno cancelável por guest session e rate limiting (#2087, #2109, #2133, #2135, #2138, #2143)

• Um plano passa a ser exigido a partir de um limite de tool calls (v0.5.12): quando um turno ultrapassa um limite de tool calls, o agente tem de parar e escrever um plano antes de continuar (#2128)

• O transcript sobrevive à troca de session (v0.5.12): o mapa de dobras é indexado por um anchor estável de role e timestamp em vez de um UUID gerado a cada render, por isso trocar de session e voltar já não dobra todos os turnos que tinhas aberto (#2155)

• Instalações headless provisionam o provider integrado (v0.5.12): opencrabs run, daemon, agent, acp e cron criam o token integrado numa home nova tal como a TUI já fazia, enquanto status e doctor ficam read-only (#2151)

• Modo de reparação doctor –fix (v0.3.83): linhas de cron presas, markers obsoletos e permissões partidas são reparados no momento em vez de apenas reportados

• Locks de escrita por caminho (v0.3.83): escritas concorrentes no mesmo ficheiro são serializadas; o último a escrever deixa de ganhar silenciosamente

• Isolamento de worktree para sub-agentes (v0.3.83): cada agente filho recebe o seu próprio worktree e branch, pelo que um fan-out não consegue destruir a árvore partilhada

• Critérios de aceitação com noção de tipo (v0.3.83): os critérios do plano são aplicados contra a toolchain que o projeto realmente usa (#1133)

• Verificação de planos com noção de projeto (v0.3.83), os planos verificam com os comandos do próprio projeto, não sempre cargo, e encontram o projeto a partir da pasta da session

• /stop cancela imediatamente (v0.3.83): interrompe durante o handshake do provider e os backoffs de retry (#1148)

• Retoma de sessions A2A (v0.3.83): as sessions retomam por context id, o gateway é endereçado por profile (#1159, #1161)

• Botões de thinking do DeepSeek (v0.3.83): o DeepSeek recebe os parâmetros de thinking que realmente lê, mais tratamento de turns só de tool-call

• Correlação de logs por session_id (v0.3.82): cada turn abre um tracing span com o seu session id, e os cron jobs e o motor RSI têm os seus próprios, pelo que um único grep reconstrói um turn inteiro a partir de um log diário partilhado

• Fiabilidade do logger (v0.3.82): o logger deixa de descartar eventos e deixa de escrever no terminal do TUI; uma escrita travada deixa de silenciar o logging de todas as outras threads

• Ficheiros brain do utilizador protegidos (v0.3.82): o SOUL.md, USER.md e MEMORY.md nunca recebem merges do upstream, e as diretivas são encaminhadas para o AGENTS.md, que está sempre carregado

• Unificação de secções de config (v0.3.82): a grafia legada [gateway] é migrada em disco para [a2a], pelo que um nome sobrevive a um ciclo de reload

• Cache por hash de chunk (v0.3.82): a memória salta o re-embedding de chunks cujo conteúdo não mudou

• Binários de pre-release (v0.3.82): cinco alvos de plataforma mais SHA256SUMS, publicados como pre-release contínua para que contribuidores testem código por lançar sem esperar por uma tag. Corre a pedido, não em cada push

• Abandono em rate-limit (v0.3.82): uma janela longa de rate-limit do Telegram devolve imediatamente em vez de estacionar o envio em linha

• Store de memória in-tree (v0.3.81): a dependência qmd foi removida; pesquisa vetorial + SQLite FTS5 mantida in-tree

• Caminhos de índice externos (v0.3.81) (a pesquisa de memória lê índices fora do diretório do profile, default-deny em sessions partilhadasCaminhos de índice externos (v0.3.81)) a pesquisa de memória l�� índices fora do diretório do profile, default-deny em sessions partilhadas

• Mermaid como imagens no Telegram (v0.3.81): os diagramas renderizam como imagens enquanto as tabelas mantêm a formatação nativa

• Reasoning do Qwen entre turns (v0.3.81): preserve_thinking, botões de thinking gated por família, nível de esforço recomendado por defeito, Qwen hospedado acessível em todo o lado

• Correção da perda de chaves no keys.toml (v0.3.81), as chaves de API dos providers deixam de se perder em runtime; chaves envenenadas autorrecuperam-se

• Deteção precoce de loops (v0.3.81): rondas de ferramentas repetitivas apanhadas antes de o provider rejeitar o turn

• Gate do motor RSI (v0.3.81): RSI autónomo desligado por defeito para daemons headless, ativa com rsi_enabled

• Âmbito do memory_search (v0.3.80): pesquisa os logs diários (memory), os ficheiros brain (brain) ou ambos (all); os ficheiros brain são indexados no momento da escrita

• Recuperação de memória por chunks (v0.3.80): documentos divididos em chunks antes do embedding para que chunks posteriores sejam pesquisáveis; recall ordenado com BM25

• Renderização nativa do Slack (v0.3.80): tabelas e títulos chegam na própria forma do Slack em vez de markdown cru

• Comandos de channel reservados ao owner (v0.3.80): comandos e skills personalizados são só do owner no braço catch-all dos channels em grupos

• Gates de convergência do RSI (v0.3.80): a auto-melhoria pausa na convergência, recua em sequências de zero melhorias, faz hash dos achados por identidade estável

• Guardas de loop (v0.3.80): guardas de repetição de anúncios e quase-correspondências em todas as ferramentas; kills do detetor de loop chegam à cadeia de fallback

• Modo de inventário do browser (v0.3.80): o browser_find nu enumera todos os elementos clicáveis na página

• Atualização dos templates de ficheiros brain (v0.3.80), os templates de AGENTS.md, BOOT.md e SOUL.md mudaram; o seeding nunca sobrescreve ficheiros existentes, por isso faz diff contra src/docs/reference/templates/ e faz merge à mão se quiseres os novos defeitos

• Reconstrução do brain de sistema: ficheiros brain reconstruídos a partir do disco quando mudam, sem reinício

• Descoberta proativa de ferramentas: pesquisa ferramentas disponíveis antes de alegar incapacidade

• Analisador de prompts multilingue (v0.3.67): PromptAnalyzer partilhado com soft-nudge no TUI e Telegram, 6 packs de idioma (EN/ES/FR/ID/PT/RU)

• Modo de planos (v0.3.67-v0.3.68): tracks design/checklist, cartão de plano persistente, comando /plan <query>, auto-aprovação do agente quando o utilizador concede autonomia

• Clique-para-expandir (v0.3.69): clique esquerdo num bloco de tool-call ou reasoning para expandir só esse bloco, a complementar o Ctrl+O

• review_gate de skills (v0.3.70): declaração no frontmatter para skills críticas que exigem aprovação do utilizador antes de efeitos secundários

• Ativação JIT de ferramentas: ferramentas estendidas ativadas a pedido, sem pré-registo

• Auto-reparação da config: repara automaticamente um config.toml partido, nunca envenena a última config boa

• Gestão do orçamento de contexto: limiares de compaction de 65% suave / 90% rígido com fallback LLM

• Deteção de streams presas: janela deslizante de 2048 bytes apanha padrões repetitivos

• Defesa contra gaslighting: remove preâmbulos de recusa de ferramentas a meio do turn

• Entrega de resultados de build (v0.3.61): os resultados de rebuild/evolve chegam a quem pediu, através de channels e TUI

Interface de Terminal (TUI)

• Renderização nativa de markdown: ênfase, listas, links e itens de tarefa renderizam diretamente no terminal
• Medidor de tok/s em tempo real: tokens por segundo em direto durante o streaming
• Exibição da versão (v0.3.73): mostra a versão em execução no cabeçalho do TUI e no /help + /usage dos channels
• Expansão de reasoning em 3 estados (v0.3.74): clique ou Ctrl+O percorre um bloco de reasoning colapsado → limitado → completo, para nunca inundar a vista
• Cabeçalhos por turn (v0.3.75): cada turn recebe um cabeçalho de resumo de uma linha, o raciocínio enrola-se nele, e os turns vêm dobrados por defeito para a vista se manter limpa
• Agrupamento de tool calls (v0.3.61): chamadas de ferramentas consecutivas colapsam num único bloco expansível, mantendo o TUI limpo em operações multi-passo
• Dobrar texto intermédio (v0.3.61): o texto de processamento intermédio dobra-se no mesmo log in-place das tool calls, pelo que só a resposta final fica visível
• Pesquisa de sessions: filtro de pesquisa + scroll no viewport por todas as sessions
• Painéis divididos: sessions paralelas ao estilo tmux com persistência de layout
• Colar imagens da clipboard: cola imagens do browser ou de qualquer app diretamente no TUI
• Afixar o plano: o plano ativo é afixado no fim do prompt a cada turn
• Onboarding orientado pelo agente: configuração inicial personalizada com fluxo guiado
• Loop autónomo /goal: define um objetivo e o agente entra em loop até um juiz LLM dizer que está feito, com controlos pause/resume/status
• Auto-objetivos (v0.3.61): o agente pode definir e conduzir os seus próprios objetivos multi-turn via ferramenta goal_manage sem o utilizador invocar /goal

Experiência de Desenvolvimento

• Mais de 50 ferramentas integradas: operações de ficheiros, bash, pesquisa web, execução de código, automação de browser, geração de imagens, voz, renderização de PDF
• Pesquisa web paralela unificada (v0.3.73): web_search, exa_search e brave_search dispersam em paralelo sob uma única ferramenta web_search
• web_scrape: scraping nativo de URL para markdown com proteção SSRF, rastreio de sitemaps, deteção de JS-shell e export com noção de profile
• Deteção de captcha DDG (v0.3.73): deteta captcha do DuckDuckGo via HTTP 202 + verificação estrutural de formulário
• Skill /github integrada: controlo total do gh CLI para issues, PRs, code reviews, gestão de repos
• Descoberta proativa de ferramentas: o agente encontra ferramentas antes de dizer “não consigo”
• Sistema de skills: templates de workflow com fuzzy-finding, registadas automaticamente como slash commands
• Ferramentas dinâmicas: definidas em runtime via TOML (executores HTTP + shell)
• Sistema de projetos: sessions dedicadas com overlays de brain por projeto, arquivo de ficheiros e badges de cor
• Edição hashline: edição de ficheiros ancorada por hash com suporte de lote e deteção de colisões
• Mission Control: dashboard de ecrã inteiro com inbox RSI, log de atividade e agenda de cron
• RTK auto-download: proxy de 4MB incluído para 53.5% de poupança de tokens em mais de 100 comandos
• Proteção de ficheiros confidenciais: chaves SSH, .env, credenciais protegidas por defeito
• AGENTS sempre carregado: regras rígidas e governança aplicadas a cada turn
• debug_logs orientado por config (v0.3.71): alterna logs de debug com hot-reload, sem reinício
• Âmbito de redação de segredos (v0.3.71): limita a redação a global/grupo/DM com o comando /redact
• Âmbito de redação de segredos (v0.3.71): limita a redação a global/grupo/DM com o comando /redact
• debug_logs orientado por config (v0.3.71): alterna logs de debug com hot-reload, sem reinício
• Watchdog de tmux (v0.3.71): kill só do painel, aviso de 30s, re-anexação automática
• Plan-gate de três estados (v0.3.71): GateDecision com bash a ir para aprovação no Editing pós-init
• ToolHints ao estilo MCP (v0.3.71): modelo de risco para classificação de ferramentas, alimenta o plan gate

Browser Automation

• Suporte CDP total: navegar, clicar, escrever, screenshot, avaliar JS, encontrar elementos
• Modo headless ou headed com screenshots específicas por elemento
• Persistência de cookies/sessions entre sessions de browser
• Isolamento de separadores por session: sem pisões de DOM entre sessions

Descoberta de Diretivas de Projeto (v0.3.59)

O OpenCrabs descobre automaticamente ficheiros de regras que outras ferramentas de codificação por IA deixam num repo. Aponta o agente para qualquer repositório (via /cd, um workspace de channel, ou lançando dentro de um) e ele pesquisa as convenções enviadas pelo Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode e o standard entre ferramentas AGENTS.md. Sem config, sem passo de importação.

O índice reconstrói-se quando fazes /cd para um novo diretório, pelo que os ficheiros de diretivas estão sempre atualizados.

Início Rápido

# Instalar (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 (requer Rust 1.94+)
cargo install opencrabs --locked

Auto-update ativado por defeito. Desativa com [agent] auto_update = false em ~/.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           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Próximos Passos

• Instalação: Instalar e configurar
• Configuração: Tod as opções de config
• Providers: Liga os teus backends LLM
• Channels: Liga Telegram, Discord, etc.
• Ferramentas: Explora mais de 50 capacidades integradas
• Self-Healing: Funcionalidades de resiliência
• Multi-Agent: Orquestra sub-agentes e equipas

Comunidade e Suporte

• Comunidade no Telegram: junta-te ao grupo OpenCrabs para dúvidas, dicas e conversa sobre releases
• Patrocina no GitHub: apoia o projeto e mantém os crabs alimentados
• Buy Me a Coffee: apoio pontual se o OpenCrabs te poupou uma tarde

Encontraste um bug ou queres uma funcionalidade? Abre uma issue no 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.

Opção 1: Homebrew (recomendado em macOS e 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.

Corre opencrabs depois de instalar. Vai direto para o chat com o provider incorporado já ativo, por isso o crab cumprimenta-te e podes começar a falar. Corre opencrabs --onboard quando quiseres o assistente de configuração.

Opção 2: Descarregar Binário (todas as plataformas)

Vai buscar um binário pré-compilado ao 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

Vai direto para o chat com o provider incorporado já ativo. Corre opencrabs --onboard quando quiseres o assistente de configuração.

O Windows é uma plataforma de primeira classe (v0.5.3): shell handling consciente da plataforma, leitura BOM/UTF-16 e fallbacks de tilde/cwd incluídos, e a CI compila Windows em cada PR (#627).

Verifica o download (opcional): cada release publica um ficheiro SHA256SUMS junto com os tarballs.

Permissões de terminal necessárias. O OpenCrabs lê e escreve ficheiros brain, config e ficheiros de projeto. A tua app de terminal precisa de acesso ao sistema de ficheiros ou o SO bloqueia as operações.

SO	O que fazer
macOS	Definições do Sistema → Privacidade e Segurança → Acesso Total ao Disco → ativa a tua app de terminal (Alacritty, iTerm2, Terminal, etc.). Se não estiver listada, clica em “+” e adiciona-a a partir de /Applications/. Sem isto, o macOS pergunta repetidamente “quer aceder a dados de outras apps”.
Windows	Corre o terminal (Windows Terminal, PowerShell, cmd) como Administrador na primeira execução, ou dá ao terminal acesso de escrita a %USERPROFILE%\.opencrabs\ e aos teus diretórios de projeto. O Windows Defender também pode perguntar, clica em “Permitir”.
Linux	Garante que o teu utilizador é dono de ~/.opencrabs/ e dos diretórios de projeto. Em sistemas SELinux/AppArmor, o processo do terminal precisa de acesso de leitura/escrita a esses caminhos. Terminais Flatpak/Snap podem precisar de --filesystem=home ou permissão equivalente.

O /rebuild funciona mesmo com binários pré-compilados: clona automaticamente o source para ~/.opencrabs/source/ na primeira utilização, depois compila e faz hot-restart.

Opção 3: Compilar a partir do Source

Necessário para /rebuild, adicionar ferramentas personalizadas ou modificar o agente.

Configuração rápida (recomendado)

O script de configuração deteta automaticamente a tua plataforma (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) e instala todas as dependências de build + Rust:

# Instalar todas as dependências
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Clonar e compilar
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Configuração manual

Se preferires instalar as dependências tu mesmo:

• Rust stable: Instala o Rust. A toolchain stable funciona desde a v0.2.85
• Uma chave de API de pelo menos um provider suportado
• SQLite (incluído 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

O OpenCrabs usa keys.toml em vez de .env para chaves de API. O assistente de onboarding ajuda-te a configurar, ou edita ~/.opencrabs/keys.toml diretamente.

Opção 4: Docker

Corre o OpenCrabs num contentor isolado. A compilação demora ~15min (Rust release + LTO).

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

A config, o workspace e a DB de memória persistem num volume Docker entre reinícios. As chaves de API em keys.toml são montadas no contentor em runtime, nunca vão parar dentro da imagem.

Arranque Automático no Boot

Mantém o OpenCrabs a correr como daemon de fundo que arranca com o teu sistema.

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.

Verifica o estado: 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

Atualiza o caminho em ProgramArguments para corresponder ao local de instalação.

Windows (Task Scheduler)

1. Win + R → taskschd.msc
2. Criar Tarefa Básica → Nome: OpenCrabs
3. Gatilho: Quando inicio sessão
4. Ação: Iniciar um programa → C:\Users\<tu>\.cargo\bin\opencrabs.exe, Argumentos: daemon
5. Em Properties > Settings, marca 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

Atualizar

• Utilizadores de Homebrew: brew upgrade opencrabs (se escreveres /evolve numa instalação Homebrew, delega para o Homebrew, o binário fica gerido pelo brew, e o tap antigo foi reformado em favor dos autobumps do homebrew-core)
• Utilizadores de binário: Escreve /evolve no TUI para descarregar a última release
• Utilizadores de source: git pull && cargo build --release, ou escreve /rebuild no TUI
• Utilizadores de 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.

Os vídeos com demonstrações estão na página Vídeos de Onboarding.

Início Rápido (3 minutos)

O caminho rápido permite-te conversar com o agente em menos de 3 minutos.

Configuração Avançada (7 minutos)

Configuração completa com Telegram, voz local, visão e geração de imagens.

Fluxo de onboarding

O assistente é uma TUI controlada pelo teclado, com 8 passos. Navega com as setas, usa Tab para avançar e Esc para voltar atrás.

Configuração de channels (passo 4)

O ecrã de channels lista 5 integrações: Telegram, Discord, WhatsApp, Slack e Trello.

• Space ativa ou desativa um channel
• Enter num channel ativado abre o respetivo ecrã de configuração (token, IDs, listas de permissões)
• Enter em Continue ou Tab avança para o passo seguinte
• Cada ecrã de configuração de channel tem um botão Test Connection

Consulta Channels Overview para o guia completo de navegação.

Voltar a executar a configuração

Podes saltar para qualquer passo sem voltar a executar o assistente completo:

Depois do onboarding, o agente arranca e apresenta-se. Lê os seus ficheiros brain (SOUL.md, AGENTS.md, TOOLS.md) e começa uma conversa.

Bootstrap

Na primeira execução, o agente passa por uma fase de bootstrap:

• Fica a conhecer-te (nome, preferências, forma de trabalhar)
• Define a sua identidade (nome, personalidade, emoji)
• Abre o SOUL.md contigo para discutir valores
• Configura o USER.md com o teu perfil

O ficheiro de bootstrap (BOOTSTRAP.md) apaga-se quando termina.

Migrar a partir de outra ferramenta

Já usas ClaudeCode, OpenClaw, Hermes ou outro harness de agente de IA? O teu agente pode migrar os teus dados existentes (memória, skills, comandos personalizados, preferências) para os seus próprios ficheiros brain, em linguagem natural. Não é preciso mover ficheiros manualmente.

Funciona com qualquer agente ou harness de programação que guarde a configuração localmente. A migração procura no teu sistema de ficheiros as pastas de configuração da outra ferramenta, lê o conteúdo e converte-o para o formato de ficheiros brain do OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).

Migração guiada

Se quiseres rever o que é migrado antes de a migração acontecer:

Procura localmente os meus dados do ClaudeCode/OpenClaw/Hermes (ou de qualquer outro harness de agente que eu usasse), faz uma auditoria de uma migração para os nossos próprios ficheiros brain, informa-me quando terminares e executa só quando eu confirmar e aprovar.

O agente vai:

1. Procurar no teu sistema de ficheiros as pastas de configuração da outra ferramenta
2. Ler e analisar todos os ficheiros relevantes (memória, comandos, skills, preferências)
3. Produzir uma auditoria que mostra exatamente o que vai para onde
4. Esperar pela tua confirmação
5. Executar a migração e apresentar um resumo completo

Migração autónoma

Se só queres que fique feito:

Procura localmente os meus dados existentes de agentes ou harness e migra tudo para os nossos próprios ficheiros brain, sem precisar da minha aprovação. Avança, planeia e executa, e informa-me quando terminares, com um resumo completo.

O agente salta a etapa de auditoria, planeia a migração internamente, executa-a e dá-te um resumo de tudo o que foi movido.

O que é mapeado

Dica: Executa a migração logo a seguir ao onboarding, enquanto o contexto está fresco. O agente já tem o teu USER.md e o SOUL.md do assistente, por isso pode fazer a fusão de forma inteligente em vez de substituir.

Comandos principais

Modos de aprovação

Controla o grau de autonomia do agente:

Pasta de trabalho

O agente opera dentro de uma pasta de trabalho para as operações com ficheiros. Muda-a com:

• Comando /cd no chat
• Seletor de pastas na TUI (Tab para selecionar)
• Ferramenta config_manager set_working_directory

A pasta de trabalho é guardada por session. Ao mudar de session, a pasta é restaurada automaticamente.

Dica de filtro de modelos (v0.3.78)

O seletor de modelos do onboarding passa agora a mostrar sempre uma dica de filtro acima da lista de modelos (“Type to filter…”). Antes, a dica só aparecia depois de começares a escrever, por isso os utilizadores não sabiam que existia filtragem. Além disso, um ID de modelo escrito exatamente tem agora prioridade sobre uma correspondência parcial: se escreveres claude-opus-4-8 exatamente, seleciona esse modelo, mesmo que outros modelos contenham a mesma sequência de caracteres.

Vídeos de onboarding

Os vídeos com demonstrações da configuração e do onboarding do OpenCrabs estão no canal do YouTube do OpenCrabs. Cada sistema operativo tem um vídeo de início rápido e um vídeo de configuração avançada. Clique numa miniatura para a reproduzir aqui.

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)

Todos os vídeos: youtube.com/@OpenCrabs

A página Onboarding tem os caminhos Rápido e Avançado, passo a passo, em texto.

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

O OpenCrabs tem uma CLI completa com mais de 20 subcomandos para gerir todos os aspetos do agente.

Utilização

opencrabs [COMMAND] [OPTIONS]

Comandos

Flags de Configuração

Atalhos de Teclado (TUI)

Prompt de Atualização no Arranque

Quando há uma nova versão disponível, aparece um diálogo centrado no ecrã de splash a perguntar se aceitas (Enter) ou saltas (Esc). Aceitar dispara o /evolve automaticamente. Após a atualização, o binário reinicia e o splash mostra a nova versão.

Comandos de Channel

O /doctor, /help, /usage, /evolve, /restart, /exit e os comandos de sistema funcionam diretamente no Telegram, Discord, Slack e WhatsApp sem passar pelo LLM. Executam instantaneamente e devolvem os resultados no channel.

O /restart e o /exit anunciam-se antes de agir, porque depois de o processo desaparecer não sobra nada para reportar uma falha. Ambos são só do owner, como todos os comandos que alteram o processo em execução. O /exit é o único comando sem caminho de volta a partir do chat, a recuperação precisa de acesso à máquina onde o OpenCrabs corre.

Desde a v0.3.80, um stop falado também é respeitado, dizer ao bot para parar em linguagem natural funciona nos channels e no TUI, não só a palavra seca “stop”.

Toda a lógica de comandos de channel está centralizada em src/channels/commands.rs (847 linhas), um handler partilhado que elimina lógica de comandos duplicada por 5 implementações de channel. Cada channel delega em try_execute_text_command() para comportamento consistente.

O /evolve nos channels agora corre diretamente (descarrega + instala o binário) sem exigir uma ida-e-volta ao LLM. Antes era encaminhado pelo agente.

Modo Chat

# Predefinição: lançar o TUI
opencrabs

# Igual ao anterior
opencrabs chat

Modo Agent

Modo não interativo para scripting e automação:

# Chat interativo multi-turn
opencrabs agent

# Modo de mensagem única
opencrabs agent -m "What files changed today?"

Modo Daemon vs TUI

O OpenCrabs corre num de dois modos. Escolhe o que encaixa na máquina. Para qualquer profile, corre só um de cada vez.

Porque não ambos ao mesmo tempo?

Uma credencial de bot (ex.: um token do Telegram) só consegue suster um poll getUpdates ativo. Se um daemon e um TUI forem ambos donos do token do mesmo profile, eles brigam (HTTP 409) e o channel cai.

O TUI ganha sempre

Quando abres o TUI enquanto um daemon do mesmo profile está a correr, o TUI primeiro desliga esse daemon, assume os channels e mostra um banner a dizê-lo. Os teus channels já estavam configurados, por isso simplesmente retomam, sem reconectar. O daemon fica em baixo até o voltares a iniciar (opencrabs service start, ou relançar opencrabs daemon).

Numa máquina onde o daemon costuma correr, o fluxo do dia-a-dia é: abre opencrabs quando te queres sentar com ele; fecha o TUI e opencrabs service start quando o queres outra vez headless.

Arranque automático no boot

• Daemon: usa o instalador de serviço (opencrabs service install); liga o systemd (Linux) / launchd (macOS) para arrancar no boot e reiniciar em crash. Esta é a configuração always-on recomendada.
• TUI: para a interface de terminal abrir automaticamente no login, usa um autostart de terminal/desktop, não o instalador de serviço:
  • Desktop Linux: pousa um ficheiro .desktop em ~/.config/autostart/ com Exec=x-terminal-emulator -e opencrabs.
  • macOS: Definições do Sistema > Geral > Itens de Início de Sessão > adiciona um script .command que corre opencrabs.
  • VPS por SSH: corre dentro de tmux/screen e reanexa. Numa VPS headless normalmente queres o daemon, não o TUI.

Fortemente recomendado para utilizadores do dia-a-dia. Se planeias usar o OpenCrabs diariamente, pede-lhe para se configurar como serviço de sistema. Basta dizer algo como “configura-te para arrancar com o meu computador” ou “remove o serviço de arranque automático”. O agente trata da configuração e remoção do launchd (macOS) ou systemd (Linux) automaticamente por ti.

Manter o TUI a correr numa VPS (tmux)

Se queres o TUI interativo completo sempre disponível num servidor remoto (não o daemon headless), tmux é o caminho. A tua session sobrevive a desconexões SSH, sleep do laptop e ligações instáveis.

1. Instala o tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Descobre onde o opencrabs está instalado

which opencrabs

# Se isso não devolver nada, pesquisa todo o sistema de ficheiros
find / -name "opencrabs" -type f 2>/dev/null

3. Inicia uma session de tmux com nome

tmux new -s opencrabs

4. Lança o opencrabs lá dentro

opencrabs

5. Desanexa (deixa o opencrabs a correr)

Prime Ctrl+B e depois D. Já podes fechar o SSH e o opencrabs continua a correr.

6. Reanexa mais tarde

tmux attach -t opencrabs

É isto. Volta de qualquer máquina, reanexa e continua onde ficaste. Se só precisas dos channels (Telegram, Discord, Slack, WhatsApp) a correr headless sem o TUI, o daemon encaixa melhor: opencrabs service install && opencrabs service start.

Endpoint de Saúde

Adiciona ao config.toml para expor um health check:

[daemon]
health_port = 8080

Depois GET http://localhost:8080/health devolve 200 OK com estado em JSON. Útil para watchdog de systemd, monitores de uptime ou load balancers.

Gestão de Serviço

Instala o OpenCrabs como serviço de sistema (launchd no macOS, systemd no Linux):

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

Serviços com noção de profile

Cada profile recebe o seu próprio serviço independente:

# Instala um profile específico como serviço
opencrabs -p hermes service install
opencrabs -p hermes service start

# Cada profile recebe o seu próprio nome de serviço
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Gere de forma independente
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Vários profiles podem correr como serviços daemon simultâneos com isolamento total.

Variável de ambiente OPENCRABS_PROFILE

Define OPENCRABS_PROFILE=hermes para selecionar um profile sem a flag -p. Útil para serviços systemd, cron jobs e modo daemon.

Resolução de problemas: o daemon não levanta

Se o opencrabs service status diz stopped:

1. Abreste o TUI? Abrir o opencrabs desliga deliberadamente o daemon para que a session interativa seja dona dos channels. O daemon fica em baixo até correres opencrabs service start outra vez.
2. Builds antigas podem ainda ter Restart=on-failure em vez de Restart=always. Regenera a unit com opencrabs service install (depois service start) para adotar a política de reinício permanente.
3. Config, chaves, comandos e ferramentas fazem hot-reload em runtime. Editar o config.toml ou o keys.toml nunca precisa de reiniciar o daemon. Se uma alteração não está a surtir efeito, verifica nos logs uma linha ConfigWatcher: reloaded em vez de reiniciar.

Gestão de Cron

# Listar todos os cron jobs
opencrabs cron list

# Adicionar um novo 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"

Atalhos de Teclado do 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

Se o opencrabs service status diz stopped:

1. Abreste o TUI? Abrir o opencrabs desliga deliberadamente o daemon para que a session interativa seja dona dos channels. O daemon fica em baixo até correres opencrabs service start outra vez.
2. Builds antigas podem ainda ter Restart=on-failure em vez de Restart=always. Regenera a unit com opencrabs service install (depois service start) para adotar a política de reinício permanente.
3. Config, chaves, comandos e ferramentas fazem hot-reload em runtime. Editar o config.toml ou o keys.toml nunca precisa de reiniciar o daemon. Se uma alteração não está a surtir efeito, verifica nos logs uma linha ConfigWatcher: reloaded em vez de reiniciar.

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:

Comportamento

• 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.

Exemplo

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