Introduction

OpenCrabs is a self-hosted, provider-agnostic AI orchestration agent that runs as a single Rust binary. It automates your terminal, browser, channels (Telegram/Discord/Slack/WhatsApp/Trello), and codebase, all while respecting your privacy and keeping you in control.

4,815+ tests across providers, tools, channels, TUI, self-healing, and browser automation.

What Makes OpenCrabs Different

Zero Telemetry, Not Even Opt-In

• OpenCrabs does not phone home. Ever. No analytics, no tracking, no usage statistics, no remote logging, no crash reports
• Your conversations, tools, memory, configuration, and API keys never leave your machine
• The only outbound traffic is what you explicitly initiate: LLM API calls, web searches, GitHub commands, browser automation
• Not a privacy-policy checkbox: there is no telemetry code to disable, no opt-out flag, no analytics service to block. There is simply nothing to send

Provider-Agnostic by Design

• 15 built-in providers + 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
• Native CLI integration — use Claude Code CLI, OpenCode CLI, and Codex CLI as providers without API keys
• Sticky fallback chain — auto-failover on rate limits or errors, health-aware persistence survives restarts
• Prompt caching across Anthropic, OpenRouter, Gemini, Qwen DashScope reduces costs up to 95%
• Context window override — cap or expand context for any model via config
• Xiaomi MiMo — 30+ models including the MiMo reasoning series, keyed provider

Multi-Agent Orchestration

• Sessions are fully isolated agents — each with its own brain, provider, model, working directory, and history
• Typed sub-agents: general, explore, plan, code, research with tailored tool access
• Team orchestration: team_create, team_broadcast, team_delete for coordinated workflows
• Per-call provider/model overrides — mix models across teams (plan with GLM, code with Deepseek, review with Kimi)
• A2A protocol — JSON-RPC 2.0 gateway for agent-to-agent communication

Channel-Native Communication

• Telegram, Discord, Slack, WhatsApp, Trello — full bot integration with DMs, groups, and threads
• Telegram rich messages — native tables, headings, lists, math via rich_messages config
• Draft message streaming — live “typing…” updates as tokens generate in DMs
• Collapsible blocks — <details>/<summary> sections for long outputs
• Forum topic session isolation — each topic in Telegram supergroups gets its own session
• Telegram reactions — the bot reads inbound emoji reactions and can reply with a reaction instead of a message when that fits
• Frame reactions (v0.3.61) — inbound reactions read by sentiment, agent addresses user by first name
• Mid-turn reactions (v0.3.61) — a reaction during a running turn injects into the current loop instead of firing a second turn
• Session inheritance — /new inherits the working directory from your most recent session
• /goal across all channels — set autonomous goals from Telegram, Discord, Slack, WhatsApp
• Voice support — local Whisper STT + Piper TTS, fully offline
• Cross-channel crash recovery — pending requests route back to originating channel on restart
• /cowork — create shared workspaces from channels and TUI
• /rename, /profiles, /cd — manage sessions, profiles, and directories from any channel

Self-Healing & Self-Improvement

• Recursive Self-Improvement (RSI) — agent analyzes performance, identifies patterns, and rewrites brain files
• Phantom tool call detection — catches when the model narrates changes without executing tools
• System brain rebuild — brain files rebuilt from disk when changed, no restart needed
• Proactive tool discovery — searches for available tools before claiming inability
• JIT tool activation — extended tools activated on-demand, no pre-registration needed
• Config auto-repair — auto-repair broken config.toml, never poison last-good config
• Context budget management — 65% soft / 90% hard compaction thresholds with LLM fallback
• Stuck stream detection — 2048-byte rolling window catches repeating patterns
• Gaslighting defense — strips tool-refusal preambles mid-turn
• Deliver build outcomes (v0.3.61) — rebuild/evolve results reach whoever asked, across channels and TUI

Terminal UI

• Native markdown rendering — emphasis, lists, links, and task items render directly in the terminal
• Real-time tok/s throughput meter — live tokens-per-second during streaming
• Group tool calls (v0.3.61) — consecutive tool calls collapse into one expandable block, keeping the TUI clean during multi-step operations
• Fold intermediate text (v0.3.61) — intermediate processing text folds into the same in-place log as tool calls, so only the final answer stays visible
• Session search — search filter + viewport scroll across all sessions
• Split panes — tmux-style parallel sessions with layout persistence
• Clipboard image paste — paste images from browser or any app directly into TUI
• Plan pinning — active plan pinned at end of prompt each turn
• Agent-driven onboarding — personalized first-time setup with guided flow
• /goal autonomous loop — set a goal and the agent loops until an LLM judge says it’s done, with pause/resume/status controls
• Self-goaling (v0.3.61) — agent can set and drive its own multi-turn goals via goal_manage tool without user invoking /goal

Developer Experience

• 50+ built-in tools — file ops, bash, web search, code execution, browser automation, image gen, voice, PDF rendering
• web_scrape — native URL-to-markdown scraping with SSRF protection, sitemap crawling, JS-shell detection, and profile-aware export
• Proactive tool discovery — agent finds tools before saying “I can’t”
• Skills system — workflow templates with fuzzy-finding, auto-registered as slash commands
• Dynamic tools — runtime-defined via TOML (HTTP + shell executors)
• Projects system — dedicated sessions with per-project brain overlays, file archiving, and color badges
• Hashline editing — hash-anchored file editing with batch support and collision detection
• Mission Control — full-screen dashboard with RSI inbox, activity log, and cron schedule
• RTK auto-download — bundled 4MB proxy for 53.5% token savings on 100+ commands
• Confidential file protection — SSH keys, .env, credentials protected by default
• AGENTS always-loaded — hard rules and governance enforced every turn

Browser Automation

• Full CDP support — navigate, click, type, screenshot, JS eval, find elements
• Headless or headed mode with element-specific screenshots
• Cookie/session persistence across browser sessions
• Per-session tab isolation — no cross-session DOM stomping

Project Directive Discovery (v0.3.59)

OpenCrabs auto-discovers rule files that other AI coding tools drop in a repo. Point the agent at any repository (via /cd, a channel workspace, or launching inside one) and it scans for conventions shipped by Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode, and the cross-tool AGENTS.md standard. No config, no import step.

The index rebuilds when you /cd into a new directory, so directive files are always current.

Quick Start

# 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/adolfousier/opencrabs/releases/latest | jq -r .tag_name || curl -s https://api.github.com/repos/adolfousier/opencrabs/releases/latest | grep -o '"tag_name":"[^"]*"' | cut -d'"' -f4)
curl -fsSL "https://github.com/adolfousier/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-${OS}-${ARCH}.tar.gz" | tar xz
./opencrabs

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

Auto-update enabled by default. Disable with [agent] auto_update = false in ~/.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           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Next Steps

• Installation — Install and configure
• Configuration — All config options
• Providers — Connect your LLM backends
• Channels — Connect Telegram, Discord, etc.
• Tools — Explore 50+ built-in capabilities
• Self-Healing — Resilience features
• Multi-Agent — Orchestrate sub-agents and teams