OpenCrabs

The autonomous AI agent. Single Rust binary. Every channel.

OpenCrabs is an open-source AI agent that runs in your terminal. It connects to any LLM provider, orchestrates 40+ built-in tools, and works from Telegram, Discord, Slack, WhatsApp, or the built-in TUI.

Why OpenCrabs?

Core Capabilities

• Multi-provider AI — Anthropic Claude, OpenAI, Google Gemini, OpenRouter (400+ models), MiniMax, Ollama, LM Studio, or any OpenAI-compatible API. Fallback provider chain for automatic failover
• Every channel — Telegram, Discord, Slack, WhatsApp, or the built-in TUI
• 40+ tools — File ops, bash, web search, code execution, image gen, document parsing, and more
• Persistent memory — 3-tier memory system: daily notes, long-term memory, semantic search
• Self-evolving — Type /evolve to download the latest version, or /rebuild to build from source
• Agent-to-Agent — Built-in A2A gateway for peer-to-peer agent communication
• Cron jobs — Schedule isolated or main-session tasks with cron expressions
• Voice — Speech-to-text (WhisperCrabs) and text-to-speech (ElevenLabs, OpenAI, Coqui)
• Plans — Structured multi-step task planning with approval workflow

Quick Links

• GitHub Repository
• Releases
• Issues
• Changelog

Installation

Three ways to get OpenCrabs running.

Option 1: Download Binary (recommended)

Grab a pre-built binary from GitHub Releases — available for Linux (amd64/arm64), macOS (amd64/arm64), and Windows.

# Download and extract
curl -fsSL https://github.com/adolfousier/opencrabs/releases/latest/download/opencrabs-$(uname -m)-$(uname -s | tr A-Z a-z).tar.gz | tar xz

# Run
./opencrabs

The onboarding wizard handles everything on first run.

/rebuild works even with pre-built binaries — it auto-clones the source to ~/.opencrabs/source/ on first use, then builds and hot-restarts.

Option 2: Build from Source

Required for /rebuild, adding custom tools, or modifying the agent.

Prerequisites:

• Rust nightly (2024 edition) — Install Rust, then rustup toolchain install nightly
• An API key from at least one supported provider
• SQLite (bundled via sqlx)
• Linux: build-essential, pkg-config, libssl-dev, libchafa-dev

git clone https://github.com/adolfousier/opencrabs.git
cd opencrabs

# Build & run (development)
cargo run --bin opencrabs

# Or build release and run directly
cargo build --release
./target/release/opencrabs

OpenCrabs uses keys.toml instead of .env for API keys. The onboarding wizard will help you set it up, or edit ~/.opencrabs/keys.toml directly.

Option 3: Docker

Run OpenCrabs in an isolated container. Build takes ~15min (Rust release + LTO).

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

Config, workspace, and memory DB persist in a Docker volume across restarts. API keys in keys.toml are mounted into the container at runtime — never baked into the image.

Updating

• Binary users: Type /evolve in the TUI to download the latest release
• Source users: git pull && cargo build --release, or type /rebuild in the TUI
• Docker users: docker compose pull && docker compose up -d

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
├── IDENTITY.md          # Agent identity
├── 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.

Feature Flags

# config.toml
[agent]
working_directory = "/path/to/default/dir"
thinking = "on"                # "on", "off", or "budget_XXk"

[a2a]
enabled = false
bind = "127.0.0.1"
port = 18790

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

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

First Session

When you launch OpenCrabs for the first time, the onboarding wizard walks you through setup.

Onboarding Flow

1. Provider selection — Choose your AI provider (Anthropic, OpenAI, Gemini, OpenRouter, or custom)
2. API key — Enter your API key
3. Model selection — Pick a default model (fetched live from the provider)
4. Channel setup (optional) — Connect Telegram, Discord, Slack, or WhatsApp
5. Image tools (optional) — Configure Gemini for image generation and vision

After onboarding, your agent boots up and introduces itself. It reads its brain files (SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md) and starts a conversation.

Bootstrap

On the very first run, the agent goes through a bootstrap phase:

• Gets to know you (name, preferences, work style)
• Establishes its identity (name, personality, emoji)
• Opens SOUL.md together to discuss values
• Sets up USER.md with your profile

The bootstrap file (BOOTSTRAP.md) deletes itself when complete.

Key Commands

Approval Modes

Control how much autonomy the agent has:

Working Directory

The agent operates within a working directory for file operations. Change it with:

• /cd command in chat
• Directory picker in the TUI (Tab to select)
• config_manager set_working_directory tool

The working directory is persisted per-session — switching sessions restores the directory automatically.

CLI Commands

OpenCrabs supports several CLI modes.

Usage

opencrabs [COMMAND] [OPTIONS]

Commands

Chat Mode

# Default — launch TUI
opencrabs

# Same as above
opencrabs chat

Daemon Mode

Run OpenCrabs without the TUI — useful for servers where you only need channel bots.

opencrabs daemon

The agent processes messages from all connected channels (Telegram, Discord, Slack, WhatsApp) but without the terminal UI.

Cron Management

# 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 Keyboard Shortcuts

AI Provider Setup

OpenCrabs supports multiple AI providers. Configure them in config.toml and keys.toml at ~/.opencrabs/.

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.

MiniMax

Models: 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"

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.

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.

Image Generation & Vision

OpenCrabs supports image generation and vision analysis via Google Gemini. These features are independent of the main chat provider — use Claude for chat and Gemini for images.

Setup

1. Get a free API key from aistudio.google.com
2. Run /onboard:image in chat to configure interactively
3. Or add manually:

# keys.toml
[image]
api_key = "AIza..."

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

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

Agent Tools

When enabled, two tools become available automatically:

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 via Gemini

Incoming Images

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 model supports vision)
• Pass the path to analyze_image for Gemini analysis
• Use the path in bash commands or any tool that accepts file paths
• Reference it in replies with <<IMG:path>> to forward to channels

Model

Both tools use gemini-3.1-flash-image-preview — Gemini’s dedicated image model that supports both vision input and image output in a single request.

Per-Provider Vision Model

Separately from the Gemini analyze_image tool, any provider can have its own vision tool via vision_model. When the user sends an image and the chat model can’t handle it natively, the agent calls the provider’s vision tool — which sends the image to the vision_model on the same provider, gets a text description back, and uses that context to reply.

Example: User sends an image to MiniMax M2.5 (no native vision). The agent calls the vision tool, which sends the image to MiniMax-Text-01, gets the description, and M2.5 replies using that context.

See Provider Setup — Vision Model.

Channel Integrations

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

Supported Channels

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, or phone number
• 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:

Telegram

Connect OpenCrabs to Telegram for DMs and group chats.

Setup

1. Message @BotFather on Telegram
2. Create a new bot with /newbot
3. Copy the bot token
4. Add to keys.toml:

[channels.telegram]
bot_token = "123456:ABC..."

5. Enable in config.toml:

[channels.telegram]
enabled = true
owner_chat_id = 123456789  # Your Telegram user ID

Get your chat ID by messaging @userinfobot on Telegram.

Features

• DMs and groups — Works in private chats and group conversations
• 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

Agent Tools

The agent can use telegram_send with 19 actions:

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

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)
5. Copy the bot token
6. Add to keys.toml:

[channels.discord]
bot_token = "your-bot-token"

7. Enable in config.toml:

[channels.discord]
enabled = true

8. Invite the bot to your server using the OAuth2 URL with bot scope and Send Messages, Read Message History permissions

Features

• Server channels and DMs — Works in text channels and direct messages
• Button interactions — Provider picker, model picker, session switcher use Discord buttons
• 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
• Reactions — Agent can add emoji reactions to messages

Formatting Notes

• No markdown tables in Discord — use bullet lists instead
• Wrap multiple links in <url> to suppress embeds

Slack

Connect OpenCrabs to Slack workspaces.

Setup

1. Go to api.slack.com/apps
2. Create a new app
3. Enable Socket Mode
4. Add bot scopes: chat:write, channels:history, groups:history, im:history, reactions:write
5. Install to workspace
6. Copy the Bot Token and App-Level Token
7. Add to keys.toml:

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

8. Enable in config.toml:

[channels.slack]
enabled = true

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

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

1. Enable in config.toml:

[channels.whatsapp]
enabled = true

2. On first run, a QR code appears in the terminal
3. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
4. Scan the QR code

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

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

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

Trello

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

Setup

1. Get an API Key and Token from trello.com/power-ups/admin
2. Configure in keys.toml:

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

3. Configure boards and access:

# config.toml
[channels.trello]
enabled = true
boards = ["Board Name or ID"]
member_id = "your-member-id"
# poll_interval_secs = 300  # Optional: poll for @mentions

Tool Actions

The trello_send tool supports 22 actions:

Behavior

• 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 40+ tools available to the agent out of the box.

File Operations

Code Execution

Web & Network

Session & Memory

Image

Channel Integrations

System

System CLI Tools

The agent can also use CLI tools available on the system through bash:

• gh — GitHub CLI (PRs, issues, releases)
• docker — Container management
• ssh — Remote server access
• node / python3 — Script execution
• curl — HTTP requests
• ffmpeg — Media processing

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.

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

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. SECURITY.md — Security policies
8. 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.

IDENTITY.md

Agent identity created during bootstrap: name, creature type, vibe, emoji, prohibited patterns.

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.

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.

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.

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

Sessions

OpenCrabs supports multiple concurrent sessions, each with its own conversation history, provider, model, and working directory.

Creating Sessions

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

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

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)

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

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

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"

Options

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.

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.

Agent-to-Agent (A2A) Protocol

OpenCrabs includes a built-in A2A gateway implementing the A2A Protocol RC v1.0 for peer-to-peer agent communication.

Enabling

# config.toml
[a2a]
enabled = true
bind = "127.0.0.1"   # Loopback only (default)
port = 18790
# allowed_origins = ["http://localhost:3000"]  # CORS

No API keys required — A2A is config-only.

Endpoints

Examples

# Discover the agent
curl http://127.0.0.1:18790/.well-known/agent.json | jq .

# Send a message (creates a task)
curl -X POST http://127.0.0.1:18790/a2a/v1 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "What tools do you have?"}]
      }
    }
  }'

# Poll a task
curl -X POST http://127.0.0.1:18790/a2a/v1 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":"TASK_ID"}}'

Bee Colony Debate

Multi-agent structured debate via confidence-weighted voting (based on ReConcile, ACL 2024). Multiple “bee” agents argue across configurable rounds, enriched with knowledge context, then converge on a consensus answer.

Security

• Loopback only by default — binds to 127.0.0.1
• CORS locked down — no cross-origin requests unless allowed_origins is set
• No authentication — do not expose to public internet without a reverse proxy + auth layer

Voice (TTS & STT)

OpenCrabs supports text-to-speech and speech-to-text for voice interactions.

Text-to-Speech (TTS)

Supported Providers

Configuration

# config.toml
[voice.tts]
provider = "elevenlabs"
voice_id = "Rachel"
speed = 1.0

# keys.toml
[voice]
elevenlabs_api_key = "your-key"

Speech-to-Text (STT)

WhisperCrabs

OpenCrabs integrates with WhisperCrabs for floating voice-to-text input in the TUI. Type /whisper to launch.

Supported backends:

• OpenAI Whisper API
• Local whisper.cpp
• FasterWhisper

Voice Messages

When receiving a voice message on WhatsApp or Telegram:

1. Audio is downloaded and transcribed via STT
2. Text response is sent first (keeps chat searchable)
3. TTS audio response is generated and sent

Per-User Voice Preferences

# config.toml
[voice.preferences.username]
voice_id = "Adam"
speed = 1.2

Building from Source

Prerequisites

• Rust 1.93+ (nightly not required)
• SQLite3 development headers
• OpenSSL development headers (vendored by default)
• pkg-config (Linux/macOS)

macOS

brew install sqlite3 pkg-config

Ubuntu / Debian

sudo apt install build-essential pkg-config libsqlite3-dev libssl-dev

Arch Linux

sudo pacman -S base-devel sqlite openssl pkg-config

Clone and Build

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

The binary is at target/release/opencrabs.

Feature Flags

OpenCrabs uses Cargo features to toggle channel support:

Build with specific features:

# Minimal — TUI only, no channels
cargo build --release --no-default-features

# Only Telegram
cargo build --release --no-default-features --features telegram

Release Profile

The release profile is optimized for size and speed:

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
strip = true
panic = "abort"

There’s also a release-small profile for minimal binary size:

cargo build --profile release-small

Running Tests

cargo test --all-features

Linting

Always use clippy with all features:

cargo clippy --all-features

Self-Update

If you build from source, use git pull && cargo build --release instead of /evolve. The /evolve command downloads pre-built binaries from GitHub Releases.

Architecture

High-Level Overview

┌─────────────────────────────────────────────────┐
│                    TUI (ratatui)                 │
├────────┬────────┬──────────┬────────────────────┤
│Telegram│Discord │  Slack   │     WhatsApp       │
├────────┴────────┴──────────┴────────────────────┤
│                 Brain (Agent Core)               │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Providers│ │  Tools   │ │  Memory (3-tier) │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
├─────────────────────────────────────────────────┤
│              Services / DB (SQLite)              │
├─────────────────────────────────────────────────┤
│         A2A Gateway (axum) │ Cron Scheduler     │
└─────────────────────────────────────────────────┘

Source Layout

src/
├── main.rs              # Entry point, CLI parsing
├── lib.rs               # Library root
├── cli/                 # CLI argument parsing (clap)
├── config/              # Configuration types and loading
├── db/                  # SQLite database layer
│   ├── models.rs        # Data models (Session, Message, etc.)
│   └── repository/      # Query functions per entity
├── migrations/          # SQL migration files
├── services/            # Business logic layer
│   └── session.rs       # Session management service
├── brain/               # Agent core
│   ├── agent/           # Agent service, context, tool loop
│   │   └── service/     # Builder, context, helpers, tool_loop
│   ├── provider/        # LLM provider implementations
│   ├── tools/           # 40+ tool implementations
│   └── memory/          # 3-tier memory system
├── tui/                 # Terminal UI (ratatui + crossterm)
│   ├── app/             # App state, input, messaging
│   └── render/          # UI rendering modules
├── channels/            # Messaging platform integrations
│   ├── telegram/        # Teloxide-based bot
│   ├── discord/         # Serenity-based bot
│   ├── slack/           # Slack Socket Mode
│   └── whatsapp/        # WhatsApp Web pairing
├── a2a/                 # Agent-to-Agent gateway (axum)
├── cron/                # Cron job scheduler
├── memory/              # Vector search + FTS5
├── docs/                # Embedded doc templates
├── tests/               # Integration tests
└── benches/             # Criterion benchmarks

Key Crates

Data Flow

1. Input arrives from TUI, channel, A2A, or cron trigger
2. Brain builds context (system prompt + brain files + memory + conversation)
3. Provider streams the LLM response via the selected provider
4. Tool Loop executes any tool calls, feeds results back to the LLM
5. Response is delivered back to the originating channel
6. DB persists messages, token usage, and session state

Database

SQLite with WAL mode. Tables:

• sessions — Session metadata, provider, model, working directory
• messages — Conversation history per session
• usage_ledger — Permanent token/cost tracking
• memory_* — FTS5 and vector tables for semantic memory

Migrations run automatically on startup from src/migrations/.

Concurrency Model

• Tokio async runtime with multi-threaded scheduler
• Each channel runs as an independent tokio task
• Sessions are isolated — each has its own conversation state
• Tool execution uses tokio::task::block_in_place for sync operations
• A2A gateway runs as a separate axum server task

Contributing

Getting Started

1. Fork the repository on GitHub
2. Clone your fork and create a branch:

   git clone https://github.com/YOUR_USERNAME/opencrabs.git
   cd opencrabs
   git checkout -b my-feature
   

3. Build and test:

   cargo clippy --all-features
   cargo test --all-features
   

Code Style

• Run cargo clippy --all-features before committing — never cargo check
• Follow existing patterns in the codebase
• Keep changes focused — one feature or fix per PR
• Add tests for new functionality in src/tests/

Pull Requests

• Write a clear title and description
• Reference any related issues
• Ensure all tests pass
• Keep PRs small and reviewable

Adding a New Tool

1. Create a new file in src/brain/tools/
2. Implement the tool handler function
3. Register it in the tool registry
4. Add the tool description to src/docs/reference/templates/TOOLS.md
5. Add tests in src/tests/

Adding a New Provider

1. Implement the provider in src/brain/provider/
2. Register it in the provider registry via crabrace
3. Add configuration docs to src/docs/reference/templates/
4. Document setup in docs/src/brain/providers.md

Reporting Issues

Open an issue at github.com/adolfousier/opencrabs/issues with:

• OpenCrabs version (opencrabs --version)
• OS and architecture
• Steps to reproduce
• Expected vs actual behavior
• Relevant log output (from ~/.opencrabs/logs/)

License

OpenCrabs is MIT licensed. By contributing, you agree that your contributions will be licensed under the same terms.

Security

Threat Model

OpenCrabs runs locally on your machine with access to your filesystem and shell. Security focuses on:

1. API key protection — Keys never leave your machine except to their respective providers
2. Network exposure — Minimal attack surface by default
3. Tool execution — Sandboxed with user approval

API Key Storage

Keys are stored in ~/.opencrabs/keys.toml:

• File permissions: 600 (owner read/write only)
• Keys are loaded into memory with zeroize — zeroed on drop
• Keys are never logged or included in conversation history
• Keys are never sent to any provider other than their own

Network Security

A2A Gateway

• Binds to 127.0.0.1 (loopback) by default
• CORS disabled unless explicitly configured
• No authentication built-in — use a reverse proxy for public exposure

Channel Connections

• All channel APIs use TLS (HTTPS/WSS)
• Telegram: long polling over HTTPS
• Discord: WebSocket with TLS
• Slack: Socket Mode (WebSocket)
• WhatsApp: Noise protocol encryption

Tool Approval

Tools that modify your system require approval:

• File writes — Shows the file path and diff
• Shell commands — Shows the exact command before execution
• Git operations — Push, commit, branch operations

Auto-approve mode (--auto-approve) bypasses this for automation use cases like cron jobs.

Data Storage

• All data stored locally in ~/.opencrabs/opencrabs.db (SQLite)
• No telemetry or analytics
• No data sent to OpenCrabs servers (there are none)
• Conversation history stays on your machine

Reporting Vulnerabilities

If you discover a security vulnerability, please report it responsibly:

• Email: adolfo@meetneura.ai
• Do not open a public issue for security vulnerabilities
• We will acknowledge receipt within 48 hours

Changelog

For the full changelog, see CHANGELOG.md on GitHub.

Recent Releases

v0.2.59 (2026-03-07)

Added:

• Fallback provider chain — Configure multiple fallback providers tried in sequence on failure
• Per-provider vision_model — Auto-swap model when images are present
• Session working directory persistence — /cd changes persist to DB, restored on session switch

Fixed:

• Update checker uses proper semver comparison instead of string inequality
• Home directory collapsed to ~/... in TUI footer and help screen

v0.2.58 (2026-03-07)

Fixed:

• Vision images in OpenAI-compatible providers — ContentBlock::Image was silently dropped. Changed OpenAIMessage.content to serde_json::Value for polymorphic content support

Docs:

• Image & file handling in brain templates — Added <<IMG:path>> documentation to AGENTS.md and TOOLS.md

v0.2.57 (2026-03-07)

Added:

• Two-step /models flow — Provider picker first, then model picker
• /new and /sessions commands for all channels
• User-defined slash commands on channels
• Custom commands visible in /help
• Emoji picker in TUI (: trigger)
• VOICE.md template

Fixed:

• Context counter accuracy — System brain tokens now counted
• Stream bleed between sessions
• Session switch shows name instead of UUID

v0.2.56 (2026-03-06)

Added:

• Daily release check notification

Fixed:

• Context counter showing 243/200K when real usage was 19K
• Streaming stop_reason overwritten by deferred usage delta

v0.2.55 (2026-03-06)

Added:

• Cumulative usage ledger — Deleting sessions no longer resets usage stats

Fixed:

• Compaction overhaul — Zero-truncation, DB persistence, exhaustive summaries

v0.2.54 (2026-03-05)

Added:

• Agent-to-Agent (A2A) protocol gateway
• Bee Colony structured debate
• Plans system with approval workflow

For older releases, see the full changelog.