Introduction

OpenCrabs es un agente de orquestación de IA autoalojado y agnóstico de proveedor que funciona como un único binario Rust. Automatiza tu terminal, navegador, canales (Telegram/Discord/Slack/WhatsApp/Trello) y código base, respetando tu privacidad y manteniéndote en control.

11,091 tests en providers, herramientas, channels, TUI, self-healing y automatización de browser.

Qué Hace Diferente a OpenCrabs

Cero Telemetría, Ni Siquiera Opt-In

• OpenCrabs no llama a casa. Nunca. Sin analíticas, sin rastreo, sin estadísticas de uso, sin logs remotos, sin informes de fallos
• Tus conversaciones, herramientas, memoria, configuración y claves API nunca salen de tu máquina
• El único tráfico saliente es el que tú inicias explícitamente: llamadas a APIs de LLM, búsquedas web, comandos de GitHub, automatización de navegador
• No es una casilla de política de privacidad: no hay código de telemetría que desactivar, ningún flag de opt-out, ningún servicio de analíticas que bloquear. Simplemente no hay nada que enviar

Agnóstico de Proveedor por Diseño

• 16 proveedores 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
• Integración CLI nativa: usa Claude Code CLI, OpenCode CLI, Codex CLI y Command Code CLI como proveedores sin claves API
• Cadena de fallback persistente: conmutación automática por rate limits o errores, persistencia consciente de salud que sobrevive a reinicios
• Prompt caching en Anthropic, OpenRouter, Gemini y Qwen DashScope reduce costes hasta un 95%
• Override de ventana de contexto: limita o amplía el contexto de cualquier modelo vía config (el provider OpenCrabs incorporado es la excepción: su ventana está fijada en 200k)
• Xiaomi MiMo: 30+ modelos incluyendo la serie de razonamiento MiMo, proveedor con clave
• Moonshot AI (Kimi): endpoints del plan API (api.moonshot.ai) y del plan Coding (api.kimi.com), config de reasoning-effort, ventana de contexto por nivel de plan

Multi-Agent Orchestration

• Las sesiones son agentes totalmente aislados, cada una con su propio brain, proveedor, modelo, directorio de trabajo e historial
• Sub-agentes tipados: general, explore, plan, code, research con acceso a herramientas a medida
• Orquestación de equipos: team_create, team_broadcast, team_delete para workflows coordinados
• Overrides de proveedor/modelo por llamada: mezcla modelos entre equipos (planear con GLM, programar con Deepseek, revisar con Kimi)
• Protocolo A2A: gateway JSON-RPC 2.0 para comunicación agente-a-agente

Comunicación Nativa de Canales

• Telegram, Discord, Slack, WhatsApp, Trello, integración completa de bot con DMs, grupos e hilos
• Mensajes enriquecidos en Telegram: tablas nativas, encabezados, listas, matemáticas vía config rich_messages
• Streaming de mensajes en borrador: actualizaciones de “escribiendo…” en vivo mientras se generan tokens en los DMs
• Bloques plegables: secciones <details>/<summary> para salidas largas
• Aislamiento de sesión por tema de foro: cada tema en supergrupos de Telegram tiene su propia sesión
• Reacciones en Telegram: el bot lee las reacciones emoji entrantes y puede responder con una reacción en vez de un mensaje cuando encaja
• Reacciones de encuadre (v0.3.61): las reacciones entrantes se leen por sentimiento, el agente se dirige al usuario por su nombre
• Reacciones a mitad de turno (v0.3.61): una reacción durante un turno en ejecución se inyecta en el bucle actual en vez de disparar un segundo turno
• Sugerencias de seguimiento (v0.3.69): seguimientos opcionales de toca-y-envía en Telegram, Discord, Slack y WhatsApp; rellenar-sin-enviar en la TUI
• Re-pegado de tarjeta de plan en Telegram (v0.3.71): vuelve a fijar la tarjeta del plan y pliega la prosa en ella cuando queda enterrada
• Captura completa del historial de grupo (v0.3.73): persiste cada mensaje de grupo en el historial, incluso de remitentes y bots fuera de la allowlist
• Interlocutor correcto en grupos (v0.3.73): deja de dirigirse a un remitente del historial del grupo como si fuera el interlocutor actual
• Herencia de sesión: /new hereda el directorio de trabajo de tu sesión más reciente
• /goal en todos los canales: define objetivos autónomos desde Telegram, Discord, Slack y WhatsApp
• Soporte de voz: Whisper STT local + Piper TTS, totalmente offline
• Recuperación de fallos entre canales: las peticiones pendientes vuelven al canal de origen al reiniciar
• /cowork: crea workspaces compartidos desde canales y la TUI
• /rename, /profiles, /cd, gestiona sesiones, perfiles y directorios desde cualquier canal

Auto-Reparación y Automejora

• Automejora Recursiva (RSI): el agente analiza su rendimiento, identifica patrones y reescribe sus brain files

• Detección de tool calls fantasma: detecta cuando el modelo narra cambios sin ejecutar herramientas

• Autocuración de fantasmas (v0.3.72): detecta turnos sin herramientas que afirman efectos secundarios de alto riesgo (ship/push/tag/release)

• Ediciones de config solo vía config_manager (v0.3.74), el agente nunca edita en crudo config.toml/keys.toml; cada escritura se valida antes de aterrizar

• Deduplicación de brain (v0.3.75): el comando /dedup más escaneos post-escritura y semanales entre archivos evitan que los brain files deriven hacia la duplicación, con aprobación por teclado inline en Telegram

• Pistas de brain files en fallos de herramientas (v0.3.75), las notas relevantes del brain aparecen automáticamente cuando una llamada a herramienta falla o da error

• Memoria proactiva (v0.3.76): la memoria relevante aparece sin que se lo pidan cuando el contexto de la conversación coincide con conocimiento almacenado

• Nombres de modelos naturales (v0.3.76): /models opus funciona; los nombres coloquiales se resuelven a IDs exactos de modelo

• Enrutado de proveedor planificar/ejecutar (v0.3.76), enruta la planificación y la ejecución hacia proveedores/modelos separados

• Timeout de bucle de pensamiento (v0.3.78): detecta bucles de razonamiento infinitos, dispara la aplicación anti-fantasma con fallback persistente

• Motor epistémico (v0.3.78): seguimiento de creencias con niveles de confianza, malla cognitiva OODA/BDI, puerta Orient antes de ejecutar planes

• Puerta de verificación Ralph (v0.3.78): verificación de tareas consciente de criterios con tope de iteraciones; las tareas deben cumplir los criterios de aceptación establecidos

• Puertas de seguridad TOML (v0.3.78): blocklist de bash configurable en caliente, redacción de secretos entrecomillados, verificación de brain files

• Analíticas de Mission Control (v0.3.78): filtro D/W/M, rejilla de tarjetas de 3 en fondo, pestañas fantasma/modelo/streaming, BD de eventos dedicada

• Onboarding de OpenAI TTS (v0.3.78): selector de voz y campo de clave API en el asistente de onboarding

• Instalación vía Homebrew (v0.3.79): brew install opencrabs desde homebrew-core: binario precompilado, ambas arquitecturas, sin toolchain de Rust

• /restart y /exit (v0.3.79): reinicia o apaga desde cualquier canal o la TUI; solo el owner en canales, anuncia antes de actuar

• Cortacircuitos de cuota (v0.3.79): los proveedores con cuota agotada reciben un breaker con TTL y se saltan en los recorridos de fallback; el agotamiento de la cadena se informa explícitamente

• Estado de plan entre sesiones (v0.3.79): los planes sobreviven a los límites de sesión; la ejecución aislada de tareas de plan viene activada por defecto, Ralph verifica en el directorio propio de la sesión

• Sistema de temas (v0.5.0): presets verificados, un selector interactivo y tus propios temas en ~/.opencrabs/themes/*.toml; el truecolor se detecta con un nivel de reserva ANSI-256, y un preset cuyo contraste haría el texto ilegible se rechaza

• Memoria estructural de código (v0.5.0): tree-sitter construye un índice de símbolos y de grafo de llamadas junto al índice de texto, de modo que “quién llama a X” recorre aristas de llamada reales mientras las preguntas conceptuales siguen la vía de texto (#1324)

• Transferencia de archivos por SSH (v0.5.0): un archivo soltado en una TUI que corre en un host remoto se recupera por la conexión ya abierta, con un opencrabs drop-agent en el lado del cliente (#1289)

• Veredictos de entrega de notify (v0.5.0): session_notify devuelve un resultado de envío legible por máquina, los recibos de inyección de profundidad 3 hacen verificable el notify_id, y la entrega se redirige a la session que posee el channel en ese momento

• Compactación en segundo plano (v0.5.0): el resumidor corre fuera del turno en lugar de retener la session mientras trabaja

• Redacción del token en la escritura (v0.5.0): un error de provider que lleve una URL ya no puede filtrar el token del bot a un log, sea cual sea el origen del registro (#1322)

• Userbot de Telegram solo de recepción (v0.5.0, experimental): captura MTProto tras una feature, con inicio de sesión local por QR/código/2FA; almacena texto permitido para su consulta y nunca actúa como el usuario

• Anclaje temporal (v0.5.1): el agente siempre sabe qué hora es: cada turno lleva una marca temporal en la zona horaria del usuario, y el prompt del sistema permanece byte a byte estable para la caché del proveedor (#1516)

• Sesiones de cron por job (v0.5.1): cada job programado recibe su propia sesión, para que dos jobs en ejecución simultánea nunca compartan contexto ni proveedores (#1511)

• Puerta de globs de skill (v0.5.1): la lista globs: de una skill puede rechazar llamadas a herramientas sobre ficheros coincidentes hasta que el agente haya leído el cuerpo de la skill (#1515)

• Escrituras de config validadas contra la estructura (v0.5.1), la barrera de escritura y las sugerencias de sección de config_manager se derivan ahora del propio tipo Config, para no divergir jamás del código publicado (#1508)

• Diseños de plan rechazados al escribir (v0.5.1): un diseño de plan malformado rebota al instante con las secciones que faltan nombradas, y una escritura rechazada restaura el scaffold en vez de borrar el borrador (#1507)

• Contrapresión de presupuesto del proveedor (v0.5.1), un proveedor que informa un presupuesto de tokens de salida dispara una sola compactación acotada y un reintento, en vez de una cascada de 400 (#1518)

• Tokens A2A atados y config solo del owner (v0.5.1), los tokens A2A se atan al gateway que los emitió, y config.toml/keys.toml pasan a modo exclusivo del owner, con secretos limpiados de los logs

• Modo servidor ACP (v0.5.2): opencrabs acp habla el Agent Client Protocol sobre stdio JSON-RPC, así que Zed, MonoCode y cualquier cliente ACP manejan el mismo brain que usan tus channels, con streaming del progreso y aprobaciones que vuelven al editor (#1540)

• Navegación consciente del shadow-DOM (v0.5.2): la resolución de selectores atraviesa shadow roots, así que la automatización alcanza web components que antes eran invisibles para las herramientas

• Superficie completa de WhatsApp (v0.5.2): notas de voz nativas, vídeo/sticker/ubicación/contacto entrantes, votos de encuestas, recuperación de presencia y media, acuses de reacción, streaming con edición en el sitio, mensajes temporales, bloqueo de contactos, fijar/reenviar/perfil, actualizaciones de estado, descubrimiento de newsletters, botones de native flow, historial por chat

• Tracing en vivo y tablas nativas en Discord (v0.5.2), los turnos largos se transmiten como una respuesta en vivo con tracing, las respuestas crean hilo automáticamente, las tablas markdown se renderizan de forma nativa y los turnos con herramientas ya no publican dos veces la respuesta final (#1603, #1608)

• Temas de foro de Telegram y /clear (v0.5.2): crear/renombrar temas de foro con vinculación de session, y /clear inicia una session nueva sin la llamada al summariser (#1585)

• Presupuesto del payload del menú de comandos (v0.5.2), setMyCommands de Telegram rechaza en silencio los cuerpos de petición por encima de ~7,8KB informando BOT_COMMANDS_TOO_MUCH; ahora las descripciones se acortan por niveles para que quepa el menú entero (#1613)

• Cron con triggers (v0.5.3): un job corre un pre-flight check y solo ejecuta cuando tu condición se cumple (output no vacío, exit code, regex), los runs omitidos cuestan 0 tokens y un trigger disparado puede despachar un goal a una session (#233)

• Windows de primera clase (v0.5.3): manejo de shell por plataforma, lectura BOM/UTF-16, fallbacks de tilde y cwd, con CI compilando Windows y aplicando gate a los PRs (#627)

• Memoria epistémica (v0.5.3): los hechos de MEMORY.md llevan confidence y decay (#1643), las secciones frías se archivan solas y opencrabs memory prune muestra qué quedó frío antes de tocar nada (#1657)

• Motor de temas terminado (v0.5.3): cada widget del TUI resuelve sus colores a través del tema, con un guard de suite contra nuevos sitios de ANSI crudo, y los temas pueden declarar un canvas background (#1634)

• Encuestas de sugerencias en WhatsApp (v0.5.3): los conjuntos de follow-ups que superan el límite nativo de botones se renderizan como encuesta, y un voto selecciona la opción (#1616)

• Familia de sessions ACP (v0.5.4): los sessions son first-class en la superficie ACP: el context meter se restaura al cargar y sigue las usage updates, session/load reproduce la transcripción y restaura el model del session, set_model persiste entre procesos, el session/set_mode nativo aplica la approval policy en el servidor, session/compact hace push, y session/new ofrece un catálogo de models en vivo

• Entrega interactiva del terminal (v0.5.4): !vi/!nano toman el terminal de forma interactiva y lo devuelven con el session intacto; solo terminales Unix, en Windows se mantiene la captura por pipe (#1744, #1759)

• Paste & drop universal (v0.5.4): un router de attachments compartido acepta cualquier tipo de archivo al pegar o soltar y clasifica código, docs, archivos y datos para que cada uno siga el pipeline correcto (#1740, #1743)

• Motor de búsqueda Serper (v0.5.4): serper_search añade resultados Google SERP, y el fan-out de web_search deduplica por URL entre engines (#1731)

• Decision cache (v0.5.4): decide_cached responde decisiones repetidas desde un anillo de reutilización L1 con tiers shadow/live y config [decisions] (#1648)

• Costes reportados por el provider y una cadena de timeouts unificada (v0.5.4), el ledger de usage prefiere el coste que el provider reportó de verdad frente a estimaciones de tabla (#1707), y los flags de timeout se resuelven [providers.<name>] -> [agent] -> default en todos los providers (#1688)

• Comandos compilados /architecture y /attach, audit trail opcional (v0.5.4), ambos comandos se distribuyen como arms compilados, y un audit trail opcional registra lo que corrió con un viewer /audit (#933, #1705)

• Superficie nativa de Discord (v0.5.5): encuestas nativas vía send_poll, respuestas TTS entregadas como mensajes de voz, y commands.toml proyectado sobre los slash commands nativos para que tus propios comandos aparezcan en el selector de Discord (#1848, #1849, #1850)

• Flow groups y governors de escritura (v0.5.5): Discord y Slack abren el flow group al inicio del turno con un reloj en vivo que cubre el pensamiento y el texto de actividad liderando la línea, y un solo governor de escritura compartido presupuesta cada edición y hace park en los 429 (#1841, #1843, #1844, #1845, #1807, #1808, #1809, #1910, #1912, #2012)

• /respond_to y /cowork (v0.5.5): modos respond_to y open por canal en la configuración, más los dos comandos para definirlos desde el propio canal (#2014, #2015)

• Disciplina de rate limit en Telegram (v0.5.5): polls de getUpdates y handoffs de handlers instrumentados para triage de stalls, un piso de espaciado sub-segundo entre superficies con telemetría de admisión, una pausa 429 por chat detrás de un único accessor Cooldown, y enlaces markdown a ficheros locales entregados como documentos (#1927, #1916, #1968)

• Ciclo de vida de sessions ACP v1 (v0.5.5): los cinco métodos v1 de ciclo de vida de sessions están implementados y el plan se publica como una actualización de plan v1 nativa (#1815)

• Footer de diálogo unificado, URLs clicables, timeline de onboarding (v0.5.5): todos los diálogos comparten un único command footer con verbos de aprobación a/r directos, las URLs y rutas de fichero son clicables, y el onboarding se reconstruyó como una timeline de pasos a la izquierda con comandos de configuración directos (#1775, #1772, #1979, #1980, #1981, #1982)

• Jubilación de cron one-shot (v0.5.5): los jobs one-shot se jubilan al entregarse en vez de volver a dispararse un año después, cada ejecución entregada lleva su run id, y los reportes de cron de Discord llegan como un único post en el foro (#544, #1703, #1851)

• Primera ejecución sin configuración (v0.5.11): una instalación nueva cae directo al chat con el provider incorporado ya provisionado, config.toml y keys.toml ya creados, y el agente saludándote. El asistente es opcional mediante /onboard o --onboard (#2079)

• Un primer turno que no puede abortar el proceso (v0.5.11): los hilos worker del agente corren en una pila de 16 MiB, así que el primer turno ya no desborda la pila por defecto (#2080)

• Etiquetas de release solo con CI verde (v0.5.11): el workflow de release lee la conclusión de la ejecución de CI del propio commit antes de publicar. Una ejecución roja falla la release, una ejecución aún en curso se espera, y un commit sin ejecución también falla (#2078)

• Evolve reinicia las unidades correctas (v0.5.11): el reinicio programado apunta a nombres de unidades resueltos en vez del glob de descubrimiento opencrabs*.service, que también capturaba la unidad transitoria que ejecuta el reinicio e hizo que systemd detuviera su propio ejecutor (#2081)

• Las guest queries de Telegram reciben la superficie completa (v0.5.12): una etiqueta en un chat donde el bot nunca fue invitado ejecuta la misma superficie de herramientas, el mismo bloque de estado en vivo y el mismo renderizado rich que un turno normal, con un turno cancelable por guest session y rate limiting (#2087, #2109, #2133, #2135, #2138, #2143)

• Se exige un plan a partir de un umbral de tool calls (v0.5.12): cuando un turno supera un umbral de tool calls, el agente debe parar y escribir un plan antes de continuar (#2128)

• El transcript sobrevive al cambio de session (v0.5.12): el mapa de pliegues se indexa por un ancla estable de role y timestamp en lugar de un UUID generado en cada render, así que cambiar de session y volver ya no pliega todos los turnos que habías abierto (#2155)

• Las instalaciones headless aprovisionan el provider integrado (v0.5.12): opencrabs run, daemon, agent, acp y cron crean el token integrado en un home nuevo igual que ya hacía la TUI, mientras que status y doctor siguen en solo lectura (#2151)

• Modo de reparación doctor –fix (v0.3.83): las filas de cron atascadas, los marcadores obsoletos y los permisos rotos se reparan al momento en vez de solo reportarse

• Bloqueos de escritura por ruta (v0.3.83): las escrituras concurrentes al mismo archivo se serializan; el último escritor ya no gana en silencio

• Aislamiento de worktree en sub-agentes (v0.3.83): cada agente hijo recibe su propio worktree y rama, así un fan-out no puede machacar el árbol compartido

• Criterios de aceptación conscientes del tipo (v0.3.83), los criterios del plan se aplican contra la toolchain que el proyecto realmente usa (#1133)

• Verificación de plan consciente del proyecto (v0.3.83), los planes verifican con los comandos propios del proyecto, no siempre cargo, y localizan el proyecto desde la carpeta de la sesión

• /stop cancela de inmediato (v0.3.83): interrumpe durante el handshake del proveedor y las esperas de reintento (#1148)

• Reanudación de sesión A2A (v0.3.83): las sesiones se reanudan por context id, el gateway se direcciona por perfil (#1159, #1161)

• Perillas de razonamiento de DeepSeek (v0.3.83): DeepSeek recibe los parámetros de thinking que realmente lee, más gestión de turnos solo-con-tool-calls

• Correlación de logs por session_id (v0.3.82): cada turno abre un tracing span que lleva su session id, y los cron jobs y el motor RSI tienen los suyos, así un solo grep reconstruye un turno completo desde un log diario compartido

• Fiabilidad del logger (v0.3.82): el logger deja de perder eventos y de escribir en la terminal de la TUI; una escritura atascada ya no puede silenciar el logging de todos los demás hilos

• Brain files del usuario protegidos (v0.3.82): a SOUL.md, USER.md y MEMORY.md nunca se les fusiona contenido de upstream, y las directivas van a AGENTS.md, que siempre está cargado

• Unificación de secciones de config (v0.3.82): la escritura legada [gateway] se migra en disco a [a2a], así un solo nombre sobrevive a un ciclo de recarga

• Caché por hash de chunk (v0.3.82): la memoria se salta re-embedder chunks cuyo contenido no ha cambiado

• Binarios pre-release (v0.3.82): cinco objetivos de plataforma más SHA256SUMS, publicados como pre-release continuo para que los contribuidores prueben código no publicado sin esperar un tag. Se ejecuta bajo demanda, no en cada push

• Salida ante rate-limit (v0.3.82): una ventana larga de rate-limit en Telegram devuelve de inmediato en vez de aparcar el envío en línea

• Almacén de memoria in-tree (v0.3.81): la dependencia qmd se elimina; búsqueda SQLite FTS5 + vectorial propiedad del propio árbol

• Rutas de índice externas (v0.3.81): la búsqueda de memoria lee índices fuera del directorio del perfil, default-deny en sesiones compartidas

• Mermaid como imágenes en Telegram (v0.3.81): los diagramas se renderizan como imágenes mientras las tablas mantienen el formato nativo

• Razonamiento de Qwen entre turnos (v0.3.81): preserve_thinking, perillas de thinking por familia, nivel de esfuerzo recomendado por defecto, Qwen hosted alcanzable desde todo

• Arreglo de pérdida de claves en keys.toml (v0.3.81), las claves API de proveedores ya no se pierden en tiempo de ejecución; las claves envenenadas se auto-reparan

• Detección temprana de bucles (v0.3.81): las rondas de herramientas repetitivas se detectan antes de que el proveedor rechace el turno

• Puerta del motor RSI (v0.3.81): RSI autónomo desactivado por defecto en daemons headless, actívalo con rsi_enabled

• Ámbito de memory_search (v0.3.80): busca en logs diarios (memory), brain files (brain) o ambos (all); los brain files se indexan al escribir

• Recuperación de memoria por chunks (v0.3.80): los documentos se trocean antes del embedding para que los chunks posteriores sean buscables; el recall se ordena con BM25

• Renderizado nativo de Slack (v0.3.80): tablas y encabezados llegan en el propio formato de Slack en vez de markdown en crudo

• Comandos de canal con puerta de owner (v0.3.80): los comandos y skills personalizados son solo-owner en el brazo catch-all del canal en grupos

• Puertas de convergencia RSI (v0.3.80): la automejora se pausa al converger, se retira en rachas de cero mejora, y calcula hashes de hallazgos por identidad estable

• Guardas anti-bucle (v0.3.80): guardas de repetición por anuncio y casi-coincidencia en todas las herramientas; los kills del detector de bucles llegan a la cadena de fallback

• Modo inventario del navegador (v0.3.80): browser_find a secas enumera cada elemento clicable de la página

• Actualización de plantillas de brain files (v0.3.80), las plantillas de AGENTS.md, BOOT.md y SOUL.md cambiaron; el seeding nunca sobrescribe archivos existentes, así que haz diff contra src/docs/reference/templates/ y fusiona a mano si quieres los nuevos valores por defecto

• Reconstrucción del brain del sistema: los brain files se reconstruyen desde disco al cambiar, sin reiniciar

• Descubrimiento proactivo de herramientas: busca herramientas disponibles antes de declararse incapaz

• Analizador de prompts multilenguaje (v0.3.67): PromptAnalyzer compartido con soft-nudge en TUI y Telegram, 6 paquetes de idioma (EN/ES/FR/ID/PT/RU)

• Modo plan (v0.3.67-v0.3.68): pistas design/checklist, tarjeta de plan persistente, comando /plan <query>, auto-aprobación del agente cuando el usuario concede autonomía

• Clic-para-expandir (v0.3.69): clic izquierdo en un bloque de tool-call o razonamiento para expandir solo ese bloque, complementando Ctrl+O

• review_gate en skills (v0.3.70): declaración en frontmatter para skills de alto riesgo que exigen aprobación del usuario antes de efectos secundarios

• Activación JIT de herramientas: herramientas extendidas activadas bajo demanda, sin pre-registro

• Auto-reparación de config: repara automáticamente un config.toml roto, nunca envenena la última config buena

• Gestión del presupuesto de contexto: umbrales de compactación 65% suave / 90% duro con fallback a LLM

• Detección de streams atascados: ventana rodante de 2048 bytes detecta patrones repetitivos

• Defensa anti-gaslighting: elimina los preámbulos de rechazo de herramientas a mitad de turno

• Entrega de resultados de build (v0.3.61): los resultados de rebuild/evolve llegan a quien los pidió, a través de canales y TUI

Terminal UI

• Renderizado markdown nativo: énfasis, listas, enlaces y tareas se renderizan directamente en la terminal
• Medidor de rendimiento tok/s en tiempo real, tokens por segundo en vivo durante el streaming
• Muestra de versión (v0.3.73): muestra la versión en ejecución en la cabecera de la TUI y en /help + /usage de los canales
• Expansión de razonamiento en 3 estados (v0.3.74): clic o Ctrl+O alterna un bloque de razonamiento plegado → limitado → completo, así nunca inunda la vista
• Cabeceras por turno (v0.3.75): cada turno recibe una cabecera resumen de una línea, su desarrollo se pliega en ella, y los turnos se pliegan por defecto para que la vista quede limpia
• Agrupación de tool calls (v0.3.61): las llamadas consecutivas a herramientas colapsan en un bloque expandible, manteniendo la TUI limpia en operaciones de varios pasos
• Plegado de texto intermedio (v0.3.61): el texto de procesamiento intermedio se pliega en el mismo log in-situ que las tool calls, así solo la respuesta final permanece visible
• Búsqueda de sesiones: filtro de búsqueda + scroll de viewport en todas las sesiones
• Paneles divididos: sesiones paralelas al estilo tmux con persistencia de layout
• Pegado de imágenes del portapapeles: pega imágenes desde el navegador o cualquier app directamente en la TUI
• Fijado del plan: el plan activo se fija al final del prompt en cada turno
• Onboarding guiado por el agente: configuración inicial personalizada con flujo guiado
• Bucle autónomo /goal: define un objetivo y el agente itera hasta que un juez LLM dice que está hecho, con controles de pausa/reanudación/estado
• Auto-objetivos (v0.3.61): el agente puede definir y dirigir sus propios objetivos multi-turno vía la herramienta goal_manage sin que el usuario invoque /goal

Experiencia de Desarrollo

• 50+ herramientas integradas: operaciones de archivos, bash, búsqueda web, ejecución de código, automatización de navegador, generación de imágenes, voz, renderizado de PDF
• Búsqueda web paralela unificada (v0.3.73): web_search, exa_search y brave_search se disparan en paralelo bajo una única herramienta web_search
• web_scrape: scraping nativo de URL a markdown con protección SSRF, rastreo de sitemaps, detección de JS-shell y exportación consciente de perfil
• Detección de captcha de DDG (v0.3.73): detecta el captcha de DuckDuckGo vía HTTP 202 + comprobación estructural del formulario
• Skill /github integrada: control completo de gh CLI para issues, PRs, revisiones de código y gestión de repos
• Descubrimiento proactivo de herramientas: el agente encuentra herramientas antes de decir “no puedo”
• Sistema de skills: plantillas de workflow con búsqueda difusa, auto-registradas como comandos slash
• Herramientas dinámicas: definidas en tiempo de ejecución vía TOML (ejecutores HTTP + shell)
• Sistema de proyectos: sesiones dedicadas con overlays de brain por proyecto, archivado de archivos e insignias de color
• Edición hashline: edición de archivos anclada por hash con soporte por lotes y detección de colisiones
• Mission Control: panel a pantalla completa con bandeja RSI, log de actividad y programación de cron
• Auto-descarga de RTK: proxy de 4MB incluido para un ahorro del 53.5% de tokens en 100+ comandos
• Protección de archivos confidenciales: claves SSH, .env y credenciales protegidas por defecto
• AGENTS siempre cargado: reglas duras y gobernanza aplicadas en cada turno
• debug_logs por config (v0.3.71): activa los logs de debug con hot-reload, sin reiniciar
• Ámbito de redacción de secretos (v0.3.71): delimita la redacción a global/grupo/DM con el comando /redact
• Ámbito de redacción de secretos (v0.3.71): delimita la redacción a global/grupo/DM con el comando /redact
• debug_logs por config (v0.3.71): activa los logs de debug con hot-reload, sin reiniciar
• Watchdog de tmux (v0.3.71): kill solo del panel, aviso de 30s, re-enganche automático
• Plan-gate de tres estados (v0.3.71): GateDecision con bash yendo a aprobación en el Editing post-init
• ToolHints estilo MCP (v0.3.71): modelo de riesgo para clasificar herramientas, alimenta la plan gate

Browser Automation

• Soporte CDP completo: navegar, clicar, teclear, capturar, evaluar JS, buscar elementos
• Modo headless o headed con capturas específicas por elemento
• Persistencia de cookies/sesión entre sesiones del navegador
• Aislamiento de pestañas por sesión: sin pisoteo del DOM entre sesiones

Descubrimiento de Directivas de Proyecto (v0.3.59)

OpenCrabs descubre automáticamente los archivos de reglas que otras herramientas de código con IA dejan en un repo. Apunta el agente a cualquier repositorio (vía /cd, un workspace de canal, o lanzándolo dentro de uno) y escanea las convenciones traídas por Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode y el estándar multi-herramienta AGENTS.md. Sin config, sin paso de importación.

El índice se reconstruye al hacer /cd a un nuevo directorio, así los archivos de directivas están siempre al día.

Inicio Rápido

# Install (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

# Or via Cargo (requires Rust 1.94+)
cargo install opencrabs --locked

Auto-actualización activada por defecto. Desactívala con [agent] auto_update = false en ~/.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 Pasos

• Instalación: Instala y configura
• Configuración: Todas las opciones de config
• Proveedores: Conecta tus backends LLM
• Canales: Conecta Telegram, Discord, etc.
• Herramientas: Explora más de 50 capacidades integradas
• Auto-Reparación: Funciones de resiliencia
• Multi-Agente: Orquesta sub-agentes y equipos

Comunidad y Soporte

• Comunidad de Telegram: únete al grupo de OpenCrabs para preguntas, trucos y novedades de releases
• Patrocina en GitHub: apoya el proyecto y mantiene a los cangrejos alimentados
• Buy Me a Coffee: apoyo puntual si OpenCrabs te salvó una tarde

¿Encontraste un bug o quieres una función? Abre un issue en 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.

Opción 1: Homebrew (recomendado en macOS y 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.

Ejecuta opencrabs tras instalar. Va directo al chat con su provider incorporado ya activo, así que el crab te saluda y puedes empezar a hablar. Ejecuta opencrabs --onboard cuando quieras el asistente de configuración.

Opción 2: Descargar Binario (todas las plataformas)

Descarga un binario precompilado desde 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

Va directo al chat con su provider incorporado ya activo. Ejecuta opencrabs --onboard cuando quieras el asistente de configuración.

Windows es una plataforma de primera clase (v0.5.3): manejo de shell consciente de la plataforma, lectura BOM/UTF-16 y fallbacks de tilde/cwd integrados, y CI compila Windows en cada PR (#627).

Verifica tu descarga (opcional): cada release publica un archivo SHA256SUMS junto a los tarballs.

Permisos de terminal necesarios. OpenCrabs lee/escribe brain files, config y archivos de proyecto. Tu app de terminal necesita acceso al sistema de archivos o el SO bloqueará las operaciones.

SO	Qué hacer
macOS	Ajustes del Sistema → Privacidad y Seguridad → Acceso a Disco Completo → activa tu app de terminal (Alacritty, iTerm2, Terminal, etc.). Si no aparece, pulsa “+” y añádela desde /Applications/. Sin esto, macOS pregunta repetidamente “quiere acceder a datos de otras apps”.
Windows	Ejecuta tu terminal (Windows Terminal, PowerShell, cmd) como Administrador en la primera ejecución, o concede a la terminal acceso de escritura a %USERPROFILE%\.opencrabs\ y a tus directorios de proyecto. Windows Defender también puede preguntar, pulsa “Permitir”.
Linux	Asegúrate de que tu usuario es dueño de ~/.opencrabs/ y de los directorios de proyecto. En sistemas con SELinux/AppArmor, el proceso de la terminal necesita acceso de lectura/escritura a esas rutas. Las terminales Flatpak/Snap pueden necesitar --filesystem=home o un permiso equivalente.

/rebuild funciona incluso con binarios precompilados: clona el código fuente a ~/.opencrabs/source/ en el primer uso, luego compila y reinicia en caliente.

Opción 3: Compilar desde Código Fuente

Necesario para /rebuild, añadir herramientas personalizadas o modificar el agente.

Configuración rápida (recomendada)

El script de configuración detecta automáticamente tu plataforma (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) e instala todas las dependencias de build + Rust:

# Install all dependencies
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

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

Configuración manual

Si prefieres instalar las dependencias tú mismo:

• Rust stable: Instala Rust. La toolchain estable funciona desde v0.2.85
• Una clave API de al menos un proveedor soportado
• SQLite (incluido vía rusqlite)
• macOS: brew install cmake pkg-config
• Debian/Ubuntu: sudo apt install build-essential pkg-config libssl-dev cmake
• Fedora/RHEL: sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake
• Arch: sudo pacman -S base-devel pkg-config openssl cmake

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

OpenCrabs usa keys.toml en vez de .env para las claves API. El asistente de onboarding te ayudará a configurarlo, o edita ~/.opencrabs/keys.toml directamente.

Opción 4: Docker

Ejecuta OpenCrabs en un contenedor aislado. La build tarda ~15min (release de Rust + LTO).

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

La config, el workspace y la BD de memoria persisten en un volumen Docker entre reinicios. Las claves API de keys.toml se montan en el contenedor en tiempo de ejecución, nunca se hornean en la imagen.

Autoarranque al Encender

Mantén OpenCrabs corriendo como daemon en segundo plano que arranca con tu 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.

Comprueba el 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

Actualiza la ruta en ProgramArguments para que coincida con tu ubicación de instalación.

Windows (Programador de Tareas)

1. Win + R → taskschd.msc
2. Crear tarea básica → Nombre: OpenCrabs
3. Desencadenador: Al iniciar sesión
4. Acción: Iniciar un programa → C:\Users\<you>\.cargo\bin\opencrabs.exe, Argumentos: daemon
5. En Propiedades > Configuración, marca Si la tarea falla, reiniciar cada 1 minuto

O vía 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

Actualizando

• Usuarios de Homebrew: brew upgrade opencrabs (si escribes /evolve en una instalación Homebrew, delega en Homebrew, el binario sigue gestionado por brew, y el tap antiguo queda retirado en favor de los autobumps de homebrew-core)
• Usuarios de binario: Escribe /evolve en la TUI para descargar el último release
• Usuarios de código fuente: git pull && cargo build --release, o escribe /rebuild en la TUI
• Usuarios 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.

Los vídeos guiados están en la página Vídeos de onboarding.

Inicio Rápido (3 minutos)

La vía rápida te permite chatear con el agente en menos de 3 minutos.

Configuración avanzada (7 minutos)

Configuración completa con Telegram, voz local, visión y generación de imágenes.

Flujo de onboarding

El asistente es una TUI controlada con el teclado y tiene 8 pasos. Navega con las flechas, usa Tab para avanzar y Esc para volver.

Configuración de channels (paso 4)

La pantalla de channels muestra 5 integraciones: Telegram, Discord, WhatsApp, Slack y Trello.

• Space activa o desactiva un channel
• Enter en un channel activado abre su pantalla de configuración (token, IDs, listas de permitidos)
• Enter en Continue o Tab pasa al siguiente paso
• Cada pantalla de configuración de channels tiene un botón Test Connection

Consulta Channels Overview para ver la guía de navegación completa.

Volver a ejecutar la configuración

Puedes ir a cualquier paso sin volver a ejecutar el asistente completo:

Al terminar el onboarding, tu agente se inicia y se presenta. Lee sus archivos de brain (SOUL.md, AGENTS.md, TOOLS.md) y empieza una conversación.

Bootstrap

En la primera ejecución, el agente pasa por una fase de bootstrap:

• Te conoce (nombre, preferencias, forma de trabajar)
• Define su identidad (nombre, personalidad, emoji)
• Abre SOUL.md contigo para hablar de sus valores
• Configura USER.md con tu perfil

El archivo de bootstrap (BOOTSTRAP.md) se elimina solo al completarse.

Migrar desde otra herramienta

¿Ya usas ClaudeCode, OpenClaw, Hermes u otro arnés de agente de IA? Tu agente puede migrar tus datos existentes (memoria, skills, comandos personalizados, preferencias) a sus propios archivos de brain usando lenguaje natural. No necesitas mover archivos a mano.

Funciona con cualquier agente o arnés de programación que guarde su configuración en local. La migración busca en tu sistema de archivos los directorios de configuración de la otra herramienta, lee su contenido y lo convierte al formato de archivos de brain de OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).

Migración guiada

Si quieres revisar qué se migra antes de que ocurra:

Busca en local mis datos de ClaudeCode/OpenClaw/Hermes (o de cualquier otro arnés de agente que haya usado) y audita una migración a nuestros propios archivos de brain. Informa cuando termine y ejecútala cuando yo confirme y apruebe.

El agente:

1. Busca en tu sistema de archivos los directorios de configuración de la otra herramienta
2. Lee y analiza todos los archivos relevantes (memoria, comandos, skills, preferencias)
3. Genera una auditoría que muestra exactamente qué se asigna a dónde
4. Espera tu confirmación
5. Ejecuta la migración e informa de un desglose completo

Migración autónoma

Si solo quieres que se haga:

Busca en local mis datos existentes de agentes o arneses y migra todo a nuestros propios archivos de brain, sin necesidad de mi aprobación. Adelante: planifica y ejecuta, e informa cuando termine con un desglose completo.

El agente omite el paso de auditoría, planifica la migración internamente, la ejecuta y te entrega un resumen de todo lo que se movió.

Qué se asigna

Consejo: Ejecuta la migración justo después del onboarding, mientras el contexto está fresco. El agente ya tiene tu USER.md y tu SOUL.md del asistente, así que puede combinarlos de forma inteligente en lugar de sobrescribirlos.

Comandos principales

Modos de aprobación

Controla cuánta autonomía tiene el agente:

Directorio de trabajo

El agente opera dentro de un directorio de trabajo para las operaciones con archivos. Cámbialo con:

• Comando /cd en el chat
• Selector de directorios en la TUI (Tab para seleccionar)
• Herramienta config_manager set_working_directory

El directorio de trabajo se guarda por session. Al cambiar de session, el directorio se restaura automáticamente.

Pista de filtro de modelos (v0.3.78)

El selector de modelos del onboarding ahora siempre muestra una pista de filtro encima de la lista de modelos (“Type to filter…”). Antes, la pista solo aparecía después de empezar a escribir, así que los usuarios no sabían que había filtrado. Además, un ID de modelo escrito exactamente ahora tiene prioridad sobre una coincidencia parcial: si escribes claude-opus-4-8 exactamente, selecciona ese modelo aunque otros modelos contengan la misma subcadena.

Vídeos de onboarding

Los vídeos guiados de la configuración y el onboarding de OpenCrabs están en el canal de YouTube de OpenCrabs. Cada sistema operativo tiene un vídeo de inicio rápido y otro de configuración avanzada. Haz clic en una miniatura para reproducirlo aquí.

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 los vídeos: youtube.com/@OpenCrabs

La página Onboarding describe por escrito los pasos de las vías rápida y avanzada.

Configuration

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

Workspace Layout

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

Provider Configuration

See Provider Setup for detailed provider configuration.

Quick example: add Anthropic:

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

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

Provider Priority

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

MiniMax > OpenRouter > Anthropic > OpenAI > Gemini > Custom

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

Config Safety (v0.3.74)

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

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

v0.3.79 hardened this further:

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

Agent Behavior

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

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

Sub-agent and RSI Overrides

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

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

Channel Configuration

Telegram

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

Discord

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

Slack

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

WhatsApp

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

Trello

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

Other Channels (Preview)

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

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

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

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

Cron Defaults

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

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

Memory and Embeddings

[memory]
vector_enabled = true

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

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

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

Brain Files

[brain]
strip_empty_sections = true
default_cap = 500

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

Browser

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

To start a standalone Chromium with CDP enabled:

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

A2A (Agent-to-Agent) Gateway

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

Daemon Mode

[daemon]
health_port = 8080

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

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

Image Generation and Vision

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

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

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

Voice Provider Fallback

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

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

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

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

TOML Bash Blocklist (v0.3.78)

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

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

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

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

Safety TOML Reload (v0.3.78)

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

CLI Commands

OpenCrabs tiene una CLI completa con más de 20 subcomandos para gestionar todos los aspectos del agente.

Uso

opencrabs [COMMAND] [OPTIONS]

Comandos

Flags de Configuración

Atajos de Teclado (TUI)

Aviso de Actualización al Arrancar

Cuando hay una versión nueva disponible, aparece un diálogo centrado en la pantalla de splash pidiendo aceptar (Enter) o saltar (Esc). Aceptar dispara /evolve automáticamente. Tras la actualización, el binario se reinicia y el splash muestra la nueva versión.

Comandos de Canal

/doctor, /help, /usage, /evolve, /restart, /exit y los comandos de sistema funcionan directamente en Telegram, Discord, Slack y WhatsApp sin pasar por el LLM. Se ejecutan al instante y devuelven resultados en el canal.

/restart y /exit se anuncian antes de actuar, porque una vez que el proceso desaparece no queda nada que reporte un fallo. Ambos son solo-owner, como cualquier otro comando que cambia el proceso en ejecución. /exit es el único comando sin retorno desde el chat: recuperar requiere acceso a la máquina donde corre OpenCrabs.

Desde v0.3.80, un stop hablado también se respeta, decirle al bot que pare en lenguaje natural funciona en los canales y en la TUI, no solo la palabra suelta “stop”.

Toda la lógica de comandos de canal está centralizada en src/channels/commands.rs (847 líneas), un handler compartido que elimina la lógica duplicada entre 5 implementaciones de canal. Cada canal delega en try_execute_text_command() para un comportamiento consistente.

/evolve en los canales ahora se ejecuta directamente (descarga + instala el binario) sin requerir un round-trip al LLM. Antes se enrutaba a través del agente.

Modo Chat

# Default: launch TUI
opencrabs

# Same as above
opencrabs chat

Modo Agente

Modo no interactivo para scripting y automatización:

# Interactive multi-turn chat
opencrabs agent

# Single-message mode
opencrabs agent -m "What files changed today?"

Modo Daemon vs TUI

OpenCrabs corre en uno de dos modos. Elige el que encaje con la máquina. Para un mismo perfil, ejecuta solo uno a la vez.

¿Por qué no ambos a la vez?

Una credencial de bot (p. ej. un token de Telegram) solo puede mantener un poll getUpdates vivo. Si un daemon y una TUI poseen el token del mismo perfil, se pelean (HTTP 409) y el canal se cae.

La TUI siempre gana

Cuando abres la TUI mientras corre un daemon del mismo perfil, la TUI apaga ese daemon primero, toma los canales y muestra un banner avisando de ello. Tus canales ya estaban configurados, así que simplemente se reanudan, sin reconectar. El daemon permanece apagado hasta que lo arranques de nuevo (opencrabs service start, o relanza opencrabs daemon).

En una máquina donde el daemon suele correr, el flujo diario es: abre opencrabs cuando quieras sentarte con él; cierra la TUI y opencrabs service start cuando lo quieras headless de nuevo.

Autoarranque al encender

• Daemon: usa el instalador de servicio (opencrabs service install); conecta systemd (Linux) / launchd (macOS) para arrancar al encender y reiniciar ante fallos. Esta es la configuración always-on recomendada.
• TUI: para que la interfaz de terminal se abra automáticamente al iniciar sesión, usa un autoarranque de terminal/escritorio, no el instalador de servicio:
  • Escritorio Linux: deja un archivo .desktop en ~/.config/autostart/ con Exec=x-terminal-emulator -e opencrabs.
  • macOS: Ajustes del Sistema > General > Elementos de Inicio > añade un script .command que ejecute opencrabs.
  • VPS por SSH: ejecuta dentro de tmux/screen y reengánchate. En un VPS headless normalmente quieres el daemon, no la TUI.

Muy recomendado para usuarios diarios. Si planeas usar OpenCrabs a diario, pídele que se configure como servicio del sistema. Solo di algo como “configúrate para arrancar con mi ordenador” o “quita el servicio de autoarranque”. El agente gestiona la configuración y eliminación de launchd (macOS) o systemd (Linux) automáticamente.

Mantén la TUI corriendo en un VPS (tmux)

Si quieres la TUI interactiva completa siempre disponible en un servidor remoto (no el daemon headless), tmux es el camino. Tu sesión sobrevive a desconexiones SSH, suspensión del portátil y conexiones inestables.

1. Instala tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Localiza dónde está instalado opencrabs

which opencrabs

# If that returns nothing, search the whole filesystem
find / -name "opencrabs" -type f 2>/dev/null

3. Arranca una sesión tmux con nombre

tmux new -s opencrabs

4. Lanza opencrabs dentro

opencrabs

5. Desconéctate (opencrabs sigue corriendo)

Pulsa Ctrl+B y luego D. Ya puedes cerrar SSH y opencrabs sigue corriendo.

6. Reengánchate después

tmux attach -t opencrabs

Eso es todo. Vuelve desde cualquier máquina, reengánchate y continúa donde lo dejaste. Si solo necesitas canales (Telegram, Discord, Slack, WhatsApp) corriendo headless sin la TUI, el daemon encaja mejor: opencrabs service install && opencrabs service start.

Endpoint de Salud

Añade a config.toml para exponer un chequeo de salud:

[daemon]
health_port = 8080

Entonces GET http://localhost:8080/health devuelve 200 OK con estado en JSON. Útil para watchdog de systemd, monitores de uptime o balanceadores.

Gestión del Servicio

Instala OpenCrabs como servicio del sistema (launchd en macOS, systemd en Linux):

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

Servicios conscientes de perfil

Cada perfil recibe su propio servicio independiente:

# Install a specific profile as a service
opencrabs -p hermes service install
opencrabs -p hermes service start

# Each profile gets its own service name
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Manage independently
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Varios perfiles pueden correr como servicios daemon simultáneos con aislamiento total.

Variable de entorno OPENCRABS_PROFILE

Define OPENCRABS_PROFILE=hermes para seleccionar un perfil sin el flag -p. Útil para servicios systemd, cron jobs y modo daemon.

Solución de problemas: el daemon no arranca

Si opencrabs service status dice stopped:

1. ¿Abriste la TUI? Abrir opencrabs apaga deliberadamente el daemon para que la sesión interactiva posea los canales. El daemon permanece apagado hasta que hagas opencrabs service start de nuevo.
2. Las builds antiguas pueden tener aún Restart=on-failure en vez de Restart=always. Regenera la unidad con opencrabs service install (luego service start) para adoptar la política de reinicio siempre.
3. La config, las claves, los comandos y las herramientas se recargan en caliente en tiempo de ejecución. Editar config.toml o keys.toml nunca necesita reiniciar el daemon. Si un cambio no surte efecto, busca en los logs una línea ConfigWatcher: reloaded en vez de reiniciar.

Gestión de Cron

# List all cron jobs
opencrabs cron list

# Add a new 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"

Atajos de Teclado de la TUI

Troubleshooting

Common issues and how to fix them.

Windows Defender Blocking OpenCrabs

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

Add an exclusion:

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

Or via PowerShell (admin):

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

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

Binary Won’t Start or Crashes

Startup Errors

Run with debug logging to see what’s failing:

opencrabs -d chat

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

Download a Previous Version

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

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

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

/evolve: Update & Rollback

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

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

If /evolve Fails

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

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

Cargo Install Fallback

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

Check-Only Mode

The agent can check for updates without installing:

/evolve check_only=true

Bash Tool Safety

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

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

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

Older CPUs (Pre-2011 / No AVX)

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

What’s Affected

Symptoms

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

Fix: Build from Source with CPU Targeting

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

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

macOS with Apple Silicon

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

Config Issues

Config Won’t Load

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

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

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

Or reinitialize with defaults:

opencrabs init --force

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

Manual Backup

Always keep a backup of your critical files:

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

RSI Has Never Run

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

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

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

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

Checklist:

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

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

Channel Issues

Telegram

Bot not responding:

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

Regenerate bot token:

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

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

Telegram Won’t Connect / Reconnect

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

Fix:

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

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

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

WhatsApp

QR code / session expired:

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

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

# Re-pair via onboarding
opencrabs chat --onboard

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

Messages not received:

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

WhatsApp Won’t Connect / Wrong Number Replying

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

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

Full reset steps:

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

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

Common issues:

Discord

Bot not receiving messages:

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

Regenerate token: Discord Developer Portal → Bot → Regenerate Token

Slack

Both tokens required:

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

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

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

Trello

Setup:

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

General: Re-run Channel Setup

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

opencrabs chat --onboard

Or type /onboard:channels in the TUI.

Agent Hallucinating Tool Calls

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

Fix: Start a new session.

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

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

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

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

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

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

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

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

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

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

Daemon Stays Down

Si opencrabs service status dice stopped:

1. ¿Abriste la TUI? Abrir opencrabs apaga deliberadamente el daemon para que la sesión interactiva posea los canales. El daemon permanece apagado hasta que hagas opencrabs service start de nuevo.
2. Las builds antiguas pueden tener aún Restart=on-failure en vez de Restart=always. Regenera la unidad con opencrabs service install (luego service start) para adoptar la política de reinicio siempre.
3. La config, las claves, los comandos y las herramientas se recargan en caliente en tiempo de ejecución. Editar config.toml o keys.toml nunca necesita reiniciar el daemon. Si un cambio no surte efecto, busca en los logs una línea ConfigWatcher: reloaded en 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:

Comportamiento

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

Ejemplo

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