Introduction

OpenCrabs: автономный агент оркестрации ИИ, не привязанный к провайдеру, работающий как единый бинарный файл на Rust. Он автоматизирует ваш терминал, браузер, channels (Telegram/Discord/Slack/WhatsApp/Trello) и кодовую базу, уважая вашу приватность и оставляя контроль у вас.

11,091 тестов по providers, инструментам, channels, TUI, self-healing и автоматизации browser.

Что отличает OpenCrabs

Ноль телеметрии: даже опции включения нет

• OpenCrabs никогда не связывается с «домашним сервером». Никогда. Никакой аналитики, никакого трекинга, никакой статистики использования, никакого удалённого логирования, никаких отчётов о сбоях
• Ваши переписки, инструменты, память, конфигурация и API-ключи никогда не покидают вашу машину
• Единственный исходящий трафик: тот, который вы инициируете сами: вызовы LLM API, веб-поиск, команды GitHub, автоматизация браузера
• Это не галочка в политике приватности: нет кода телеметрии, который нужно отключать, нет флага отказа, нет аналитического сервиса, который нужно блокировать. Просто нечего отправлять

Независимость от провайдера заложена в дизайн

• 16 встроенных провайдеров + 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
• Нативная интеграция CLI: используйте Claude Code CLI, OpenCode CLI, Codex CLI и Command Code CLI как провайдеров без API-кл��чей
• Липкая цепочка fallback: автоматическое переключение при лимитах запросов или ошибках, данные о здоровье провайдеров переживают перезапуски
• Кэширование промптов в Anthropic, OpenRouter, Gemini, Qwen DashScope снижает расходы до 95%
• Переопределение окна контекста: ограничьте или расширьте контекст любой модели через конфигурацию (встроенный provider OpenCrabs это исключение: его окно зафиксировано на 200k)
• Xiaomi MiMo: более 30 моделей, включая рассуждающую серию MiMo, провайдер с API-ключом
• Moonshot AI (Kimi): эндпоинты API plan (api.moonshot.ai) и Coding plan (api.kimi.com), настройка reasoning-effort, окно контекста по тарифному плану

Multi-Agent Orchestration

• Sessions (полностью изолированные агенты) у каждой свой brain, провайдер, модель, рабочая директория и история
• Типизированные суб-агенты: general, explore, plan, code, research с настроенным доступом к инструментам
• Оркестрация команд: team_create, team_broadcast, team_delete для согласованных рабочих процессов
• Переопределение провайдера/модели на каждый вызов - миксуйте модели между командами (план на GLM, код на Deepseek, ревью на Kimi)
• Протокол A2A: шлюз JSON-RPC 2.0 для связи агентов между собой

Нативная коммуникация через channels

• Telegram, Discord, Slack, WhatsApp, Trello - полная интеграция ботов с личными сообщениями, группами и тредами
• Rich-сообщения Telegram: нативные таблицы, заголовки, списки, формулы через настройку rich_messages
• Стриминг черновиков сообщений: живые обновления «печатает…» по мере генерации токенов в личных сообщениях
• Сворачиваемые блоки: секции <details>/<summary> для длинных выводов
• Изоляция session по темам форума: каждая тема в супер-группах Telegram получает собственную session
• Реакции Telegram: бот читает входящие эмодзи-реакции и может ответить реакцией вместо сообщения, когда это уместно
• Реакции на кадр (v0.3.61): входящие реакции читаются по тональности, агент обращается к пользователю по имени
• Реакции посреди хода (v0.3.61): реакция во время выполняющегося хода внедряется в текущий цикл вместо запуска второго хода
• Подсказки продолжения (v0.3.69) (необязательные follow-up-кнопки в Telegram, Discord, Slack, WhatsApp; в TUI) заполнение без отправки
• Повторное закрепление карточки плана в Telegram (v0.3.71) - карточка плана заново закрепляется и вбирает текст, когда её засыпало сообщениями
• Полный захват истории групп (v0.3.73): в историю сохраняется каждое сообщение группы, даже от отправителей и ботов не из allowlist
• Корректный собеседник в группах (v0.3.73): отправитель из истории группы больше не принимается за текущего собеседника
• Наследование session: /new наследует рабочую директорию вашей последней session
• /goal во всех channels: ставьте автономные цели из Telegram, Discord, Slack, WhatsApp
• Голосовая поддержка: локальные Whisper STT + Piper TTS, полностью офлайн
• Восстановление после сбоя между channels: ожидающие запросы возвращаются в исходный channel после перезапуска
• /cowork: создавайте общие рабочие пространства из channels и TUI
• /rename, /profiles, /cd - управляйте sessions, профилями и директориями из любого channel

Самовосстановление и самоулучшение

• Рекурсивное самоулучшение (RSI): агент анализирует свою работу, находит паттерны и переписывает brain files

• Обнаружение фантомных вызовов инструментов - ловит моменты, когда модель описывает изменения, не выполняя инструменты

• Самовосстановление от фантомов (v0.3.72): ловит ходы без единого вызова инструментов, заявляющие критичные побочные эффекты (ship/push/tag/release)

• Правки конфигурации только через config_manager (v0.3.74) - агент никогда не редактирует config.toml/keys.toml напрямую; каждая запись проверяется до применения

• Дедупликация brain (v0.3.75): команда /dedup плюс проверки после записи и еженедельные межфайловые сканы не дают brain files расползаться дубликатами, с подтверждением через inline-клавиатуру Telegram

• Подсказки из brain files при промахах инструментов (v0.3.75) - релевантные заметки brain всплывают автоматически, когда вызов инструмента промахивается или падает

• Проактивная память (v0.3.76): релевантные воспоминания всплывают без запроса, когда контекст разговора совпадает со знаниями из памяти

• Естественные имена моделей (v0.3.76): /models opus работает; разговорные имена превращаются в точные ID моделей

• Роутинг провайдеров для плана и исполнения (v0.3.76) - направляйте планирование и исполнение на разные провайдеры/модели

• Таймаут цикла размышлений (v0.3.78): ловит бесконечные циклы рассуждений, запускает фантомную защиту со sticky fallback

• Эпистемический движок (v0.3.78): отсле��ивание убеждений с уровнями уверенности, когнитивная сеть OODA/BDI, шлюз Orient перед исполнением плана

• Шлюз проверки Ralph (v0.3.78): верификация задач по критериям с лимитом итераций; задачи обязаны соответствовать заявленным критериям приёмки

• Створы безопасности TOML (v0.3.78): настраиваемый на лету blocklist для bash с hot-reload, маскирование секретов в кавычках, проверка brain files

• Аналитика Mission Control (v0.3.78): фильтр Д/Н/М, сетка карточек в три колонки, вкладки phantom/model/streaming, отдельная БД событий

• Подключение OpenAI TTS (v0.3.78): выбор голоса и поле API-ключа в мастере первоначальной настройки

• Установка через Homebrew (v0.3.79): brew install opencrabs из homebrew-core: готовый бинарник, обе архитектуры, без тулчейна Rust

• /restart и /exit (v0.3.79): перезапуск или выключение из любого channel или из TUI; в channels только для owner, с объявлением перед действием

• Предохранитель квот (v0.3.79): провайдеры с исчерпанной квотой получают TTL-предохранитель и пропускаются при обходе fallback; исчерпание цепочки сообщается явно

• Состояние планов между sessions (v0.3.79): планы переживают границы session; изолированное исполнение задач плана включено по умолчанию, Ralph проверяет в директории самой session

• Система тем (v0.5.0): проверенные пресеты, интерактивный выбор и ваши собственные темы из ~/.opencrabs/themes/*.toml; truecolor определяется автоматически с запасным уровнем ANSI-256, а пресет, контраст которого сделал бы текст нечитаемым, отклоняется

• Структурная память кода (v0.5.0): tree-sitter строит индекс символов и графа вызовов рядом с текстовым индексом, поэтому запрос «кто вызывает X» идёт по реальным рёбрам вызовов, а концептуальные вопросы остаются на текстовом пути (#1324)

• Передача файла по SSH (v0.5.0): файл, перетащенный в TUI на удалённом хосте, забирается через уже открытое соединение, с opencrabs drop-agent на стороне клиента (#1289)

• Вердикты доставки notify (v0.5.0): session_notify возвращает машиночитаемый результат отправки, квитанции внедрения глубины 3 делают notify_id проверяемым, а доставка перенаправляется в ту session, которой сейчас принадлежит channel

• Фоновое сжатие контекста (v0.5.0): суммаризатор работает вне хода, а не удерживает session на время работы

• Скрытие токена при записи (v0.5.0): ошибка provider с URL больше не может попасть в log вместе с токеном бота, откуда бы её ни записали (#1322)

• Telegram-userbot только на приём (v0.5.0, экспериментально): захват MTProto за feature-флагом, с локальным входом по QR/коду/2FA; сохраняет разрешённый текст для последующего доступа и никогда не действует от имени пользователя

• Привязка ко времени (v0.5.1): агент всегда знает, который час: каждый ход несёт отметку времени в часовом поясе пользователя, а системный промпт остаётся байт-в-байт стабильным для кэширования провайдером (#1516)

• Сессии cron для каждой задачи (v0.5.1): каждая запланированная задача получает собственную сессию, так что два одновременно работающих задания не делят контекст и провайдеров (#1511)

• Фильтр по glob’ам skill (v0.5.1): список globs: может отклонять вызовы инструментов по совпавшим файлам, пока агент не прочитал тело skill (#1515)

• Записи конфигурации проверяются по структуре (v0.5.1) - защитный барьер и подсказки секций config_manager теперь выводятся из самого типа Config и не расходятся с опубликованным кодом (#1508)

• Дизайны планов отклоняются при записи (v0.5.1): некорректный дизайн плана отбивается сразу с перечислением недостающих секций, а отклонённая запись восстанавливает scaffold вместо стирания черновика (#1507)

• Обратное давление по бюджету провайдера (v0.5.1): провайдер, сообщивший о бюджете выходных токенов, запускает одно ограниченное сжатие и повтор вместо каскада 400-х (#1518)

• Токены A2A и конфиг только для owner (v0.5.1): токены A2A привязываются к выпустившему их gateway, а config.toml/keys.toml переходят в режим owner-exclusive, секреты вычищаются из логов

• Режим сервера ACP (v0.5.2): opencrabs acp говорит на Agent Client Protocol поверх stdio JSON-RPC, поэтому Zed, MonoCode и любой ACP-клиент управляют тем же brain, что и ваши channels, со стримингом прогресса и подтверждениями, возвращающимися в редактор (#1540)

• Работа с shadow-DOM в browser (v0.5.2): разрешение селекторов проходит сквозь shadow roots, поэтому автоматизация достаёт web components, ранее невидимые для инструментов

• Полная поверхность WhatsApp (v0.5.2): нативные голосовые сообщения, входящие видео/стикеры/геолокация/контакты, голоса в опросах, восстановление presence и media, подтверждения реакций, стриминг с редактированием на месте, исчезающие сообщения, блокировка контактов, закрепление/пересылка/профиль, обновления статуса, поиск newsletters, кнопки native flow, история по каждому чату

• Живой tracing и нативные таблицы в Discord (v0.5.2) - длинные ходы транслируются как живой ответ с tracing, ответы автоматически уходят в thread, markdown-таблицы отображаются нативно, а ходы с инструментами больше не публикуют финальный ответ дважды (#1603, #1608)

• Форум-темы Telegram и /clear (v0.5.2): создание и переименование тем форума с привязкой session, а /clear запускает свежую session без вызова summariser (#1585)

• Бюджет payload меню команд (v0.5.2): setMyCommands в Telegram молча отклоняет тела запросов больше ~7,8 КБ, сообщая BOT_COMMANDS_TOO_MUCH; описания теперь сокращаются по уровням, чтобы всё меню поместилось (#1613)

• Cron с триггерами (v0.5.3): job выполняет pre-flight проверку и запускается только при выполнении вашего условия (непустой output, exit code, regex), пропущенные runs стоят 0 токенов, а сработавший trigger может отправить goal в session (#233)

• Windows как первая платформа (v0.5.3): платформенная обработка shell, чтение BOM/UTF-16, fallback для tilde и cwd, CI собирает Windows и блокирует PR (#627)

• Эпистемическая память (v0.5.3): факты в MEMORY.md несут confidence и decay (#1643), холодные секции архивируются сами, а opencrabs memory prune показывает, что остыло, прежде чем что-то менять (#1657)

• Завершённый движок тем (v0.5.3): каждый виджет TUI берёт цвета из темы, suite-guard срабатывает на любой новый сырой ANSI-сайт, и темы могут объявлять canvas background (#1634)

• Опросы предложений в WhatsApp (v0.5.3): наборы follow-up, не влезающие в лимит нативных кнопок, рендерятся опросом, и голос выбирает опцию (#1616)

• Семейство sessions ACP (v0.5.4): sessions стали первоклассными на поверхности ACP: context meter восстанавливается при загрузке и обновляется вместе с usage updates, session/load воспроизводит transcript и восстанавливает model сессии, set_model сохраняется между процессами, нативный session/set_mode применяет approval policy на стороне сервера, session/compact делает push, а session/new предлагает живой каталог models

• Интерактивная передача терминала (v0.5.4): !vi/!nano интерактивно занимают терминал и возвращают его, не тронув session; только терминалы Unix, в Windows сохраняется захват через pipe (#1744, #1759)

• Универсальный paste & drop (v0.5.4): общий router для attachments принимает любой тип файла при вставке или перетаскивании и классифицирует код, docs, архивы и данные, чтобы каждый попадал в нужный pipeline (#1740, #1743)

• Поисковый движок Serper (v0.5.4): serper_search добавляет результаты Google SERP, а fan-out web_search дедуплицирует по URL между engines (#1731)

• Decision cache (v0.5.4): decide_cached отвечает на повторные решения из кольца повторного использования L1 с tiers shadow/live и конфигурацией [decisions] (#1648)

• Стоимость от provider и единая цепочка timeouts (v0.5.4) - ledger usage предпочитает стоимость, реально сообщённую provider, оценкам из таблицы (#1707), а флаги таймаута разрешаются [providers.<name>] -> [agent] -> default для всех providers (#1688)

• Скомпилированные команды /architecture и /attach, опциональный audit trail (v0.5.4) - обе команды поставляются как скомпилированные arms, а опциональный audit trail записывает, что выполнялось, с viewer /audit (#933, #1705)

• Нативная поверхность Discord (v0.5.5): нативные опросы через send_poll, TTS-ответы доставляются голосовыми сообщениями, а commands.toml проецируется в нативные slash-команды, чтобы ваши собственные команды появлялись в picker Discord (#1848, #1849, #1850)

• Flow groups и write governors (v0.5.5): Discord и Slack открывают flow group в начале turn с живыми часами, покрывающими размышление, и текст активности возглавляет строку, а один общий governor записи бюджетит каждое редактирование и делает park на 429 (#1841, #1843, #1844, #1845, #1807, #1808, #1809, #1910, #1912, #2012)

• /respond_to и /cowork (v0.5.5): режимы respond_to и open для каждого канала в конфиге, плюс две команды, чтобы менять их прямо из самого канала (#2014, #2015)

• Дисциплина rate limit в Telegram (v0.5.5): инструментированные polls getUpdates и handoffs хендлеров для триажа stall, подсекундный floor интервалов между поверхностями с телеметрией admission, пауза 429 для каждого чата за единым accessor Cooldown, и markdown-ссылки на локальные файлы доставляются как документы (#1927, #1916, #1968)

• Жизненный цикл sessions ACP v1 (v0.5.5): пять методов v1 жизненного цикла sessions реализованы, а plan публикуется как нативное plan update v1 (#1815)

• Общий footer диалогов, кликабельные URL, timeline онбординга (v0.5.5): все диалоги делят один command footer с прямыми глаголами одобрения a/r, URL и пути к файлам кликабельны, а онбординг перестроен в timeline шагов слева с прямыми командами настройки (#1775, #1772, #1979, #1980, #1981, #1982)

• Ретайрмент cron one-shot (v0.5.5): one-shot jobs уходят на пенсию при доставке вместо повторного срабатывания через год, каждый доставленный run несет свой run id, а cron-отчеты Discord приходят как один пост форума (#544, #1703, #1851)

• Первый запуск без настройки (v0.5.11): свежая установка попадает прямо в чат со встроенным provider уже настроенным, config.toml и keys.toml созданы, а агент вас приветствует. Мастер настройки включается опционально через /onboard или --onboard (#2079)

• Первый ход, который не может обрушить процесс (v0.5.11): рабочие потоки агента работают на стеке в 16 MiB, поэтому первый ход больше не переполняет стек по умолчанию (#2080)

• Теги релиза только при зелёном CI (v0.5.11): workflow релиза читает заключение CI-запуска самого коммита до публикации. Красный запуск проваливает релиз, ещё идущий запуск ожидается, а коммит без запуска тоже проваливается (#2078)

• Evolve перезапускает нужные юниты (v0.5.11): плановый перезапуск нацелен на разрешённые имена юнитов вместо glob-шаблона обнаружения opencrabs*.service, который также совпадал с временным юнитом, выполняющим перезапуск, и заставлял systemd останавливать собственный исполнитель (#2081)

• Guest queries в Telegram получают полную поверхность (v0.5.12): тег в чате, куда бота никогда не приглашали, запускает ту же поверхность инструментов, тот же блок живого статуса и тот же rich-рендеринг, что и обычный turn, с одним отменяемым turn на guest session и rate limiting (#2087, #2109, #2133, #2135, #2138, #2143)

• После порога tool calls требуется план (v0.5.12): когда turn превышает порог tool calls, агент обязан остановиться и написать план, прежде чем продолжить (#2128)

• Transcript сохраняется при переключении session (v0.5.12): карта свёрнутых блоков индексируется стабильным anchor из role и timestamp вместо UUID, генерируемого при каждом рендере, поэтому переключение session и возврат больше не сворачивают все открытые вами turn (#2155)

• Headless-установки настраивают встроенный provider (v0.5.12): opencrabs run, daemon, agent, acp и cron создают встроенный токен на чистом home так же, как это уже делала TUI, а status и doctor остаются только для чтения (#2151)

• Режим починки doctor –fix (v0.3.83): застрявшие строки cron, устаревшие маркеры и сломанные права чинятся на месте, а не только отображаются в отчёте

• Блокировки записи на каждый путь (v0.3.83): одновременные записи в один файл выстраиваются в очередь; последний писатель больше молча не побеждает

• Изоляция worktree суб-агентов (v0.3.83): каждый дочерний агент получает свой worktree и ветку, так что веерный запуск не затирает общее дерево

• Критерии приёмки с учётом типа проекта (v0.3.83): критерии плана применяются к тулчейну, который проект реально использует (#1133)

• Проверка планов с пониманием проекта (v0.3.83): планы проверяются командами самого проекта, а не всегда cargo, и проект находится из папки session

• /stop отменяет немедленно (v0.3.83): прерывает даже во время рукопожатия с провайдером и пауз между повторами (#1148)

• Возобновление session через A2A (v0.3.83): sessions возобновляются по id контекста, шлюз адресуется по профилю (#1159, #1161)

• Настройки размышлений DeepSeek (v0.3.83): DeepSeek получает параметры thinking, которые он реально читает, плюс обработку ходов только с вызовами инструментов

• Корреляция логов по session_id (v0.3.82): каждый ход открывает span трассировки со своим session id, у задач cron и движка RSI свои span, так что один grep восстанавливает весь ход из общего дневного лога

• Надёжность логгера (v0.3.82): логгер перестаёт терять события и писать в терминал TUI; зависшая запись больше не глушит логирование остальных потоков

• Защита пользовательских brain files (v0.3.82): SOUL.md, USER.md и MEMORY.md никогда не пополняются из upstream, а директивы направляются в AGENTS.md, который загружается всегда

• Унификация секций конфигурации (v0.3.82): устаревшее написание [gateway] мигрирует на диске в [a2a], так что одно имя переживает цикл перезагрузки

• Кэширование по хэшу чанков (v0.3.82): память пропускает повторное встраивание чанков, чьё содержимое не менялось

• Пре-релизные бинарники (v0.3.82): пять платформенных целей плюс SHA256SUMS, публикуются как катящийся пре-релиз, чтобы контрибьюторы тестировали невышедший код, не дожидаясь тега. Запуск по требованию, не на каждый push

• Выход по rate-limit (v0.3.82): при длинном окне ограничений Telegram возврат происходит немедленно, вместо того чтобы парковать отправку в очереди

• Собственное хранилище памяти (v0.3.81): зависимость qmd убрана; поиск на SQLite FTS5 + векторный живёт в самом коде

• Внешние пути индексов (v0.3.81): поиск по памяти читает индексы вне директории профиля; по умолчанию запрет в общих sessions

• Mermaid картинками в Telegram (v0.3.81): диаграммы рендерятся картинками, а таблицы остаются в нативном форматировании

• Размышления Qwen между ходами (v0.3.81): preserve_thinking, настройки thinking по семейству, рекомендуемый уровень усилий по умолчанию, хостуемый Qwen доступен отовсюду

• Фикс потери ключей в keys.toml (v0.3.81) - API-ключи провайдеров больше не теряются во время работы; ��овреждённые ключи самолечатся

• Раннее обнаружение циклов (v0.3.81): повторяющиеся раунды инструментов ловятся до того, как провайдер отклонит ход

• Ворота движка RSI (v0.3.81): автономный RSI по умолчанию выключен для headless-демонов, включается через rsi_enabled

• Область поиска memory_search (v0.3.80): ищите по дневным логам (memory), brain files (brain) или по обоим сразу (all); brain files индексируются при записи

• Чанкованный поиск по памяти (v0.3.80): документы нарезаются на чанки перед встраиванием, поэтому поздние чанки тоже находятся; релевантность ранжируется BM25

• Нативный рендеринг Slack (v0.3.80): таблицы и заголовки приходят в собственном формате Slack вместо сырого markdown

• Команды channel только для owner (v0.3.80): пользовательские команды и skills в группах доступны только owner на catch-all-ветке channel

• Ворота сходимости RSI (v0.3.80): самоулучшение ставится на паузу при сходимости, откатывается при сериях без улучшений, хэширует находки по стабильной идентичности

• Защита от циклов (v0.3.80): защита от повторных объявлений и почти одинаковых повторов на всех инструментах; срабатывания детектора циклов доходят до цепочки fallback

• Режим инвентаризации браузера (v0.3.80): голый browser_find перечисляет каждый кликабельный элемент на странице

• Обновление шаблонов brain files (v0.3.80): шаблоны AGENTS.md, BOOT.md и SOUL.md изменились; сидинг никогда не перезаписывает существующие файлы, поэтому сверьте с src/docs/reference/templates/ и смёржите вручную, если хотите новые дефолты

• Пересборка системного brain: brain files пересобираются с диска при изменении, перезапуск не нужен

• Проактивный поиск инструментов: сначала ищет доступные инструменты, и только потом признаёт бессилие

• Многоязычный анализатор промптов (v0.3.67): общий PromptAnalyzer с мягкими подсказками в TUI и Telegram, 6 языковых пакетов (EN/ES/FR/ID/PT/RU)

• Режим планов (v0.3.67-v0.3.68): треки design/checklist, постоянная карточка плана, команда /plan <query>, самосогласование агентом при выданной пользователем автономии

• Разворачивание кликом (v0.3.69): левый клик по блоку вызова инструмента или размышлений разворачивает только его, в дополнение к Ctrl+O

• review_gate для skills (v0.3.70): объявление во frontmatter для рискованных skills, требующих одоб��ения пользователя перед побочными эффектами

• JIT-активация инструментов: расширенные инструменты активируются по запросу, предварительная регистрация не нужна

• Автопочинка конфигурации: сломанный config.toml чинится автоматически, последняя рабочая конфигурация никогда не портится

• Управление бюджетом контекста: пороги компакции 65% мягкий / 90% жёсткий с fallback на LLM

• Обнаружение зависшего стрима: скользящее окно в 2048 байт ловит повторяющиеся паттерны

• Защита от газлайтинга: вырезает преамбулы с отказом от инструментов посреди хода

• Доставка результатов сборки (v0.3.61): результаты rebuild/evolve доходят до того, кто просил, во всех channels и TUI

Терминальный UI

• Нативный рендеринг markdown: выделение, списки, ссылки и чекбоксы задач рендерятся прямо в терминале
• Счётчик скорости в реальном времени: живые токены в секунду во время стриминга
• Отображение версии (v0.3.73): работающая версия показывается в шапке TUI и в /help + /usage в channels
• Трёхпозиционное разворачивание размышлений (v0.3.74) - клик или Ctrl+O переключает блок размышлений свёрнут → ограничен → полностью, так что он никогда не заливает экран
• Заголовки на каждый ход (v0.3.75): каждый ход получает однострочный заголовок-сводку, его рассуждения сворачиваются в него, и ходы по умолчанию свёрнуты, поэтому обзор остаётся чистым
• Группировка вызовов инструментов (v0.3.61): последовательные вызовы инструментов сворачиваются в один разворачиваемый блок, сохраняя TUI чистым во время многошаговых операций
• Сворачивание промежуточного текста (v0.3.61): промежуточный текст обработки сворачивается в тот же журнал на месте, что и вызовы инструментов, поэтому виден только финальный ответ
• Поиск по sessions: поисковый фильтр + прокрутка вьюпорта по всем sessions
• Разделённые панели: параллельные sessions в стиле tmux с сохранением раскладки
• Вставка картинок из буфера: вставляйте картинки из браузера или любого приложения прямо в TUI
• Закрепление плана: активный план прикалывается в конец промпта на каждый ход
• Онбординг под руководством агента: персонализированная первичная настройка с ведением по шагам
• Автономный цикл /goal: поставьте цель, и агент крутится, пока LLM-судья не скажет «готово», с управлением пауза/продолжить/статус
• Самопостановка целей (v0.3.61): агент может ставить и вести собственные многоходовые цели через инструмент goal_manage, без команды /goal от пользователя

Опыт разработчика

• 50+ встроенных инструментов: файловые операции, bash, веб-поиск, исполнение кода, автоматизация браузера, генерация картинок, голос, рендеринг PDF
• Единый параллельный веб-поиск (v0.3.73): web_search, exa_search и brave_search работают параллельно под одним инструментом web_search
• web_scrape: нативное превращение URL в markdown с защитой от SSRF, обходом sitemap, обнаружением JS-заглушек и экспортом с учётом профиля
• Обнаружение ��апчи DDG (v0.3.73): капча DuckDuckGo детектируется по HTTP 202 + структурной проверке формы
• Встроенный skill /github: полное управление gh CLI для issues, PR, код-ревью и управления репозиториями
• Проактивный поиск инструментов: агент находит инструменты, прежде чем сказать «не могу»
• Система skills: шаблоны рабочих процессов с нечётким поиском, автоматически регистрируются как slash-команды
• Динамические инструменты: определяются на лету через TOML (исполнители HTTP + shell)
• Система проектов: выделенные sessions с брейн-оверлеями на каждый проект, архивацией файлов и цветными значками
• Hashline-редактирование: редактирование файлов с привязкой к хэшам строк, пакетными правками и обнаружением коллизий
• Mission Control: полноэкранная панель с входящими RSI, журналом активности и расписанием cron
• Автозагрузка RTK: встроенный прокси в 4 МБ для экономии 53,5% токенов на 100+ командах
• Защита конфиденциальных файлов: SSH-ключи, .env, креды защищены по умолчанию
• AGENTS загружается всегда: жёсткие правил�� и управление применяются на каждом ходу
• debug_logs из конфигурации (v0.3.71): переключение дебаг-логов с hot-reload, без перезапуска
• Область маскирования секретов (v0.3.71): маскирование в рамках глобально/группа/личка командой /redact
• Область маскирования секретов (v0.3.71): маскирование в рамках глобально/группа/личка командой /redact
• debug_logs из конфигурации (v0.3.71): переключение дебаг-логов с hot-reload, без перезапуска
• Сторож Tmux (v0.3.71): прибивает только панель, предупреждение за 30 с, автоматический повторный attach
• Трёхпозиционный шлюз планов (v0.3.71): GateDecision, bash уходит на одобрение в Editing после инициализации
• ToolHints в стиле MCP (v0.3.71): модель рисков для классификации инструментов, питает шлюз планов

Browser Automation

• Полная поддержка CDP: навигация, клики, ввод, скриншоты, JS eval, поиск элементов
• Режим headless или headed со скриншотами отдельных элементов
• Сохранение cookies/session между сессиями браузера
• Изоляция вкладок на каждую session: никакого затаптывания DOM между sessions

Обнаружение директив проекта (v0.3.59)

OpenCrabs автоматически находит файлы правил, которы�� другие ИИ-инструменты для кодинга оставляют в репозитории. Укажите агенту на любой репозиторий (через /cd, рабочее пространство channel или запуск внутри него) - и он просканирует конвенции от Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode и межинструментального стандарта AGENTS.md. Без конфигурации, без шага импорта.

Индекс пересобирается, когда вы делаете /cd в новую директорию, поэтому файлы директив всегда актуальны.

Быстрый старт

# 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

Автообновление включено по умолчанию. Отключите через [agent] auto_update = false в ~/.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           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Следующие шаги

• Установка: установка и настройка
• Конфигурация: все параметры конфигурации
• Провайдеры: подключите ваши LLM-бэкенды
• Channels: подключите Telegram, Discord и другие
• Инструменты: изучите 50+ встроенных возможностей
• Самовосстановление: устойчивость к сбоям
• Мультиагентность: оркестрация суб-агентов и команд

Сообщество и поддержка

• Сообщество в Telegram: присоединяйтесь к группе OpenCrabs: вопросы, советы и новости релизов
• ��понсировать на GitHub: поддержите проект, чтобы крабы были сыты
• Buy Me A Coffee: разовая поддержка, если OpenCrabs сэкономил вам полдня

Нашли баг или нужна фича? Заведите issue на 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.

Способ 1: Homebrew (рекомендуется на macOS и 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.

Запустите opencrabs после установки. Он попадает прямо в чат со встроенным provider уже активным, поэтому crab вас приветствует и можно начинать общение. Запустите opencrabs --onboard, когда нужен мастер настройки.

Способ 2: скачать бинарник (все платформы)

Возьмите готовый бинарник из 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

Он попадает прямо в чат со встроенным provider уже активным. Запустите opencrabs --onboard, когда нужен мастер настройки.

Windows: платформа первого класса (v0.5.3): платформенная обработка shell, чтение BOM/UTF-16 и fallback tilde/cwd встроены, CI собирает Windows на каждый PR (#627).

Проверьте загрузку (необязательно): каждый релиз публикует файл SHA256SUMS рядом с tarball-ами.

Нужны права терминала. OpenCrabs читает и пишет brain files, конфигурацию и файлы проектов. Терминалу нужен доступ к файловой системе, иначе ОС заблокирует операции.

ОС	Что делать
macOS	Системные настройки → Конфиденциальность и безопасность → Полный доступ к диску → включите ваш терминал (Alacritty, iTerm2, Terminal и т.д.). Если его нет в списке, нажмите «+» и добавьте из /Applications/. Без этого macOS будет бесконечно спрашивать «хочет доступ к данным других приложений».
Windows	Запустите терминал (Windows Terminal, PowerShell, cmd) от администратора при первом запуске или дайте терминалу право записи в %USERPROFILE%\.opencrabs\ и директории проектов. Windows Defender тоже может спросить - нажмите «Разрешить».
Linux	Убедитесь, что ваш пользователь владеет ~/.opencrabs/ и директориями проектов. В системах с SELinux/AppArmor процессу терминала нужен доступ на чтение/запись к этим путям. Терминалам из Flatpak/Snap может понадобиться --filesystem=home или аналогичное разрешение.

/rebuild работает даже с готовыми бинарниками: при первом использовании он сам клонирует исходники в ~/.opencrabs/source/, затем собирает и перезапускается на лету.

Способ 3: сборка из исходников

Нужно для /rebuild, добавления своих инструментов или модификации агента.

Быстрая установка (рекомендуется)

Скрипт установки сам определяет вашу платформу (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) и ставит все зависимости сборки + 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

Ручная установка

Если предпочитаете установить зависимости самостоятельно:

• Rust stable: установите Rust. Стабильный тулчейн работает начиная с v0.2.85
• API-ключ хотя бы одного поддерживаемого провайдера
• SQLite (встроен через 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 использует keys.toml вместо .env для API-ключей. Мастер настройки поможет всё настроить, либо редактируйте ~/.opencrabs/keys.toml напрямую.

Способ 4: Docker

Запустите OpenCrabs в изолированном контейнере. Сборка занимает ~15 минут (Rust release + LTO).

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

Конфигурация, рабочее пространство и БД памяти живут в Docker-томе и переживают перезапуски. API-ключи из keys.toml монтируются в контейнер во время работы - никогда не запекаются в образ.

Автозапуск при загрузке

Держите OpenCrabs фоновым демоном, который стартует вместе с системой.

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.

Статус: systemctl --user status opencrabs | Логи: 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

Обновите путь в ProgramArguments под место вашей установки.

Windows (Планировщик задач)

1. Win + R → taskschd.msc
2. Создать простую задачу → Имя: OpenCrabs
3. Триггер: При входе в систему
4. Действие: Запустить программу → C:\Users\<you>\.cargo\bin\opencrabs.exe, Аргументы: daemon
5. В Свойства > Параметры отметьте Если задача выполнена с ошибкой, перезапускать каждую 1 минуту

Или через 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

Обновление

• Пользователи Homebrew: brew upgrade opencrabs (если ввести /evolve в установке из Homebrew, он передаёт управление Homebrew - бинарником продолжает управлять brew, а старый tap удалён в пользу автобампов homebrew-core)
• Пользователи бинарников: введите /evolve в TUI, чтобы скачать последний релиз
• Пользователи исходников: git pull && cargo build --release или введите /rebuild в TUI
• Пользователи 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.

Видеоинструкции есть на странице Видео по онбордингу.

Быстрый старт (3 минуты)

Быстрый путь позволяет начать разговор с агентом меньше чем за 3 минуты.

Расширенная настройка (7 минут)

Полная настройка с Telegram, локальным голосом, Vision и генерацией изображений.

Ход онбординга

Мастер работает с клавиатуры в TUI и состоит из 8 шагов. Перемещайтесь стрелками, Tab переходит вперёд, Esc возвращает назад.

Настройка каналов (шаг 4)

На экране каналов доступно 5 интеграций: Telegram, Discord, WhatsApp, Slack, Trello.

• Space включает и выключает канал
• Enter на включённом канале открывает экран его настройки (токен, ID, списки разрешённых)
• Enter на Continue или Tab переходит к следующему шагу
• На каждом экране настройки канала есть кнопка Test Connection

Полное руководство по навигации см. в разделе Обзор каналов.

Повторный запуск настройки

Можно перейти к любому шагу, не запуская весь мастер заново:

После онбординга агент запускается и представляется. Он читает свои brain files (SOUL.md, AGENTS.md, TOOLS.md) и начинает разговор.

Bootstrap

При самом первом запуске агент проходит фазу bootstrap:

• Знакомится с вами (имя, предпочтения, стиль работы)
• Определяет свою идентичность (имя, характер, эмодзи)
• Вместе с вами открывает SOUL.md, чтобы обсудить ценности
• Заполняет USER.md вашим профилем

Файл bootstrap (BOOTSTRAP.md) удаляется сам после завершения.

Перенос из другого инструмента

Уже используете ClaudeCode, OpenClaw, Hermes или другой harness для AI-агентов? Ваш агент может перенести существующие данные (память, skills, пользовательские команды, предпочтения) в свои brain files на естественном языке. Ручное перекладывание файлов не нужно.

Это работает с любым агентом или harness для программирования, который хранит конфигурацию локально. Миграция ищет каталоги конфигурации другого инструмента в вашей файловой системе, читает их содержимое и переносит его в формат brain files OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).

Миграция под контролем

Если хотите проверить, что будет перенесено, до начала переноса:

Найди мои данные ClaudeCode/OpenClaw/Hermes локально (или данные любого другого агентского harness, который я использовал), проведи аудит миграции в наши brain files, сообщи, когда закончишь, и выполни перенос только после моего подтверждения и одобрения.

Агент:

1. Ищет в файловой системе каталоги конфигурации другого инструмента
2. Читает и разбирает все нужные файлы (память, команды, skills, предпочтения)
3. Составляет аудит с точным указанием, что куда переносится
4. Ждёт вашего подтверждения
5. Выполняет миграцию и выдаёт полный отчёт

Автономная миграция

Если нужно просто всё сделать:

Найди мои существующие данные агента или harness локально и перенеси всё в наши brain files без моего одобрения. Спланируй и выполни миграцию сразу, по завершении сообщи полный отчёт.

Агент пропускает этап аудита, планирует миграцию внутренне, выполняет её и выдаёт сводку всего перенесённого.

Что переносится

Совет: запускайте миграцию сразу после онбординга, пока контекст свежий. У агента уже есть USER.md и SOUL.md из мастера, поэтому он может объединить данные, а не перезаписывать их.

Основные команды

Режимы одобрения

Настройте, насколько автономен агент:

Рабочая папка

Агент работает в рабочей папке для файловых операций. Изменить её можно так:

• Команда /cd в чате
• Выбор папки в TUI (Tab для выбора)
• Инструмент config_manager set_working_directory

Рабочая папка сохраняется для каждой session. При переключении session папка восстанавливается автоматически.

Подсказка фильтра моделей (v0.3.78)

В выборе модели при онбординге теперь всегда показывается подсказка фильтра над списком моделей (“Type to filter…”). Раньше подсказка появлялась только после начала ввода, поэтому пользователи не знали о фильтре. Кроме того, точно введённый ID модели теперь важнее совпадения по подстроке: если ввести claude-opus-4-8 полностью, выбирается именно эта модель, даже если в других моделях есть такая же подстрока.

Видео по онбордингу

Видеоинструкции по установке и первоначальной настройке OpenCrabs доступны на YouTube-канале OpenCrabs. Для каждой ОС есть видео с быстрым стартом и видео с расширенной настройкой. Нажмите на миниатюру, чтобы воспроизвести видео здесь.

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)

Все видео: youtube.com/@OpenCrabs

На странице Онбординг есть пошаговые инструкции для быстрого старта и расширенной настройки в текстовом виде.

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 полноценный CLI с 20+ субкомандами для управления каждым аспектом агента.

Использование

opencrabs [COMMAND] [OPTIONS]

Команды

Флаги конфигурации

Горячие клавиши (TUI)

Предложение обновления при старте

Когда доступна новая версия, по центру экрана заставки появляется диалог с предложением принять (Enter) или пропустить (Esc). Принятие автоматически запускает /evolve. После обновления бинарник перезапускается, и заставка показывает новую версию.

Команды channels

/doctor, /help, /usage, /evolve, /restart, /exit и системные команды работают напрямую в Telegram, Discord, Slack и WhatsApp, минуя LLM. Они исполняются мгновенно и возвращают результат в channel.

/restart и /exit объявляют о себе перед действием: когда процесс уже убит, докладывать об ошибке некому. Обе команды только для owner, как и любая другая, меняющая работающий процесс. /exit: единственная команда, из которой нет пути назад через чат: для восстановления нужен доступ к машине, где работает OpenCrabs.

С v0.3.80 остановка своими словами тоже работает: просьба остановиться естественным языком действует в channels и в TUI, а не только голое слово «stop».

Вся логика команд channels централизована в src/channels/commands.rs (847 строк): общий обработчик, убирающий дублирование логики команд между 5 реализациями channels. Каждый channel делегирует к try_execute_text_command() для единообразного поведения.

/evolve в channels теперь выполняется напрямую (скачивает и устанавливает бинарник), без обращения к LLM. Раньше шло через агента.

Режим чата

# Default: launch TUI
opencrabs

# Same as above
opencrabs chat

Режим агента

Неинтерактивный режим для скриптов и автоматизации:

# Interactive multi-turn chat
opencrabs agent

# Single-message mode
opencrabs agent -m "Какие файлы менялись сегодня?"

Режим демона против TUI

OpenCrabs работает в одном из двух режимов. Выберите подходящий машине. Для одного профиля запускайте только что-то одно.

Почему не оба сразу?

Кред бота (например, токен Telegram) может держать только один живой опрос getUpdates. Если демон и TUI одновременно владеют токеном одного профиля, он�� дерутся (HTTP 409), и channel отваливается.

TUI всегда побеждает

Когда вы открываете TUI, пока для того же профиля работает демон, TUI сначала выключает демона, забирает channels и показывает об этом баннер. Ваши channels уже настроены, поэтому они просто возобновляются без переподключения. Демон остаётся выключенным, пока вы не запустите его снова (opencrabs service start или повторный opencrabs daemon).

На машине, где обычно работает демон, повседневный поток такой: открывайте opencrabs, когда хотите поработать с агентом; закрывайте TUI и делайте opencrabs service start, когда снова нужен headless-режим.

Автозапуск при загрузке

• Демон: используйте установщик сервиса (opencrabs service install); он настраивает systemd (Linux) / launchd (macOS) на старт при загрузке и перезапуск при падении. Это рекомендуемая схема для постоянной работы.
• TUI: чтобы терминальный интерфейс открывался автоматически при входе, используйте автозапуск терминала/десктопа, а не установщик сервиса:
  • Linux-десктоп: положите файл .desktop в ~/.config/autostart/ с Exec=x-terminal-emulator -e opencrabs.
  • macOS: Системные настройки > Основные > Объекты входа > добавьте скрипт .command, запускающий opencrabs.
  • VPS по SSH: запускайте внутри tmux/screen и переподключайтесь. На headless-VPS вам обычно нужен демон, а не TUI.

Настоятельно рекомендуется ежедневным пользователям. Если планируете пользоваться OpenCrabs каждый день, попросите его настроить себя как системный сервис. Просто скажите что-то вроде «настрой себя запускаться вместе с компьютером» или «убери автозапуск сервиса». Агент сам настроит и уберёт launchd (macOS) или systemd (Linux) автоматически.

Держим TUI работающим на VPS (tmux)

Если вам нужен полноценный интерактивный TUI всегда под рукой на удалённом сервере (а не headless-демон), tmux - ваш путь. Ваша session переживает обрывы SSH, сон ноутбука и капризные соединения.

1. Установите tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Найдите, куда установлен opencrabs

which opencrabs

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

3. Запустите именованную сессию tmux

tmux new -s opencrabs

4. Запустите opencrabs внутри неё

opencrabs

5. Отключитесь (opencrabs продолжит работать)

Нажмите Ctrl+B, затем D. Теперь можно закрыть SSH - opencrabs продолжит работать.

6. Подключитесь позже

tmux attach -t opencrabs

Вот и всё. Возвращайтесь с любой машины, подключайтесь и продолжайте с места, где остановились. Если вам нужны только channels (Telegram, Discord, Slack, WhatsApp) в headless-режиме без TUI, демон подойдёт лучше: opencrabs service install && opencrabs service start.

Эндпоинт здоровья

Добавьте в config.toml, чтобы открыть проверку здоровья:

[daemon]
health_port = 8080

Затем GET http://localhost:8080/health возвращает 200 OK с JSON-статусом. Полезно для сторожа systemd, мониторов аптайма или балансировщиков.

Управление сервисом

Установите OpenCrabs как системный сервис (launchd на macOS, systemd на Linux):

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

Сервисы с учётом профилей

Каждый профиль получает собственный независимый сервис:

# 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

Несколько профилей могут работать одновременно как демоны-сервисы с полной изоляцией.

Переменная окружения OPENCRABS_PROFILE

Поставьте OPENCRABS_PROFILE=hermes, чтобы выбирать профиль без флага -p. Полезно для сервисов systemd, задач cron и режима демона.

Траблшутинг: демон не поднимается

Если opencrabs service status говорит stopped:

1. Вы открывали TUI? Запуск opencrabs намеренно выключает демона, чтобы интерактивная session завладела channels. Демон остаётся выключенным, пока вы снова не выполните opencrabs service start.
2. Старые сборки могут ещё иметь Restart=on-failure вместо Restart=always. Перегенерируйте юнит через opencrabs service install (затем service start), чтобы получить политику вечного перезапуска.
3. Конфигурация, ключи, команды и инструменты перезагружаются на лету. Правка config.toml или keys.toml никогда не требует перезапуска демона. Если изменение не применяется, поищите в логах строку ConfigWatcher: reloaded вместо перезапуска.

Управление 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"

Горячие клавиши 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

Если opencrabs service status говорит stopped:

1. Вы открывали TUI? Запуск opencrabs намеренно выключает демона, чтобы интерактивная session завладела channels. Демон остаётся выключенным, пока вы снова не выполните opencrabs service start.
2. Старые сборки могут ещё иметь Restart=on-failure вместо Restart=always. Перегенерируйте юнит через opencrabs service install (затем service start), чтобы получить политику вечного перезапуска.
3. Конфигурация, ключи, команды и инструменты перезагружаются на лету. Правка config.toml или keys.toml никогда не требует перезапуска демона. Если изменение не применяется, поищите в логах строку ConfigWatcher: reloaded вместо перезапуска.

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:

Поведение

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

Пример

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