MCPcopy Index your code
hub / github.com/adolfousier/opencrabs

github.com/adolfousier/opencrabs @v0.3.63

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.3.63 ↗ · + Follow
9,682 symbols 29,783 edges 847 files 2,675 documented · 28%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

Rust Rust Edition Ratatui Docker CI GitHub Stars

🦀 OpenCrabs

The autonomous, self-improving AI agent. Single Rust binary. Every channel.

Autonomous, self-improving multi-channel AI agent built in Rust. Inspired by Open Claw.

    ___                    ___           _
   / _ \ _ __  ___ _ _    / __|_ _ __ _| |__  ___
  | (_) | '_ \/ -_) ' \  | (__| '_/ _` | '_ \(_-<
   \___/| .__/\___|_||_|  \___|_| \__,_|_.__//__/
        |_|

 🦀 The autonomous, self-improving AI agent. Single Rust binary. Every channel.

Author: Adolfo Usier

⭐ Star us on GitHub if you like what you see!

Why OpenCrabs?

OpenCrabs runs as a single binary on your terminal — no server, no gateway, no infrastructure. It makes direct HTTPS calls to LLM providers from your machine. Nothing else leaves your computer.

OpenCrabs vs Node.js Agent Frameworks

OpenCrabs (Rust) Node.js Frameworks (e.g. Open Claw)
Binary size 34–36 MB single binary, zero dependencies 1 GB+ node_modules with hundreds of transitive packages
Runtime None — runs natively Requires Node.js runtime + npm install
Attack surface Zero network listeners. Outbound HTTPS only Server infrastructure: open ports, auth layers, middleware
API key security Keys on your machine only. zeroize clears them from RAM on drop, [REDACTED] in all debug output Keys in env vars or config. GC doesn't guarantee memory clearing. Heap dumps can leak secrets
Data residency 100% local — SQLite DB, embeddings, brain files, all in ~/.opencrabs/ Server-side storage, potential multi-tenant data, network transit
Supply chain Single compiled binary. Rust's type system prevents buffer overflows, use-after-free, data races at compile time npm ecosystem: typosquatting, dependency confusion, prototype pollution
Memory safety Compile-time guarantees — no GC, no null pointers, no data races GC-managed, prototype pollution, type coercion bugs
Concurrency tokio async + Rust ownership = zero data races guaranteed Single-threaded event loop, worker threads share memory unsafely
Native TTS/STT Built-in local speech-to-text (whisper.cpp) and text-to-speech — ~130 MB total stack, fully offline No native voice. Requires external APIs (Google, AWS, Azure) or heavy Python dependencies (PyTorch, ~5 GB+)
Telemetry Zero. No analytics, no tracking, no remote logging Server infra typically includes monitoring, logging pipelines, APM

What stays local (never leaves your machine)

  • All chat sessions and messages (SQLite)
  • Tool executions (bash, file reads/writes, git)
  • Memory and embeddings (local vector search)
  • Voice transcription in local STT mode (whisper.cpp, on-device)
  • Brain files, config, API keys

What goes out (only when you use it)

  • Your messages to the LLM provider API (Anthropic, OpenAI, GitHub Copilot, etc.)
  • Web search queries (optional tool)
  • GitHub API via gh CLI (optional tool)
  • Browser automation (optional, browser feature — auto-detects Chromium-based browsers via CDP, not Firefox)
  • Dynamic tool HTTP requests (only when you define HTTP tools in tools.toml)

🔒 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. No "anonymous telemetry." Nothing.

Your data stays on your machine. Your conversations, your tools, your memory, your configuration, your API keys — all of it. The only outbound traffic is what you explicitly initiate: LLM API calls, web searches, GitHub commands, browser automation.

Other AI harnesses silently collect usage data, performance metrics, and behavioral analytics. OpenCrabs makes a different bet: what happens on your machine stays on your machine.

This isn't a privacy policy checkbox. It's an architectural decision. There is no telemetry code to disable, no opt-out flag to set, no analytics service to block. There's simply nothing to send.

Table of Contents

🎬 Full onboard

https://github.com/user-attachments/assets/833dd5e9-3bcc-432a-96ac-3a5bb97b5966

🎬 Demo

https://github.com/user-attachments/assets/7f45c5f8-acdf-48d5-b6a4-0e4811a9ee23

🖥️ Split Panes

Split Panes

🎯 Core Features

AI & Providers

Feature Description
Multi-Provider Xiaomi MiMo, Anthropic Claude, OpenAI, GitHub Copilot (uses your Copilot subscription), OpenRouter (400+ models), MiniMax, Google Gemini, z.ai GLM (General API + Coding API), Claude CLI, OpenCode CLI, Codex CLI (uses your ChatGPT/Codex subscription), Qwen Native (free OAuth with multi-account rotation), Qwen Code CLI (1k free req/day), and any OpenAI-compatible API (Ollama, LM Studio, LocalAI). Model lists fetched live from provider APIs — new models available instantly. Custom provider dialog: paste-by-default for API keys, Enter-to-load live models, typed-not-in-list models accepted and merged. Each session remembers its provider + model and restores it on switch
Fallback Providers Configure a chain of fallback providers — if the primary fails, each fallback is tried in sequence automatically. Any configured provider can be a fallback. Config: [providers.fallback] providers = ["openrouter", "anthropic"]
Per-Provider Vision Set vision_model per provider — the LLM calls analyze_image as a tool, which uses the vision model on the same provider API to describe images. The chat model stays the same and gets vision capability via tool call. Gemini vision takes priority when configured. Auto-configured for known providers (e.g. MiniMax) on first run
Prompt Caching Caches the stable context prefix (system prompt, brain files, earlier turns) on every caching-capable provider — Anthropic native (default), OpenAI/OpenRouter (cache_enabled), Qwen/Alibaba (zero-config auto), Xiaomi (server-side). Averaging ~87% cache efficiency in real use; watch it live in the Cache Efficiency card of /usage. Big reason a larger context window stays affordable
Context Window & Auto-Compaction Per-provider context_window override (default 200k, works on every provider); transparent auto-compaction at 65% (soft, background) / 90% (hard) of the window gives effectively unlimited session memory with no manual clearing
Real-time Streaming Character-by-character response streaming with animated spinner showing model name and live text
Local LLM Support Run with LM Studio, Ollama, or any OpenAI-compatible endpoint — 100% private, zero-cost
Usage Dashboard Per-message token count and cost displayed in header; /usage opens an interactive dashboard with daily activity charts, cost breakdowns by project/provider/model/activity, core tool usage stats, and period filtering (Today/Week/Month/All-Time). Sessions are auto-categorized on startup (Development, Bug Fixes, Features, Refactoring, Testing, Documentation, CI/Deploy, etc.). Estimated costs for historical sessions shown as ~$X.XX
Context Awareness Live context usage indicator showing actual token counts (e.g. ctx: 45K/200K (23%)); auto-compaction at 70% with tool overhead budgeting; accurate tiktoken-based counting calibrated against API actuals
3-Tier Memory (1) Brain MEMORY.md — user-curated durable memory, loaded on demand in the main session (see Brain Files), (2) Daily Logs — auto-compaction summaries at ~/.opencrabs/memory/YYYY-MM-DD.md, (3) Hybrid Memory Search — FTS5 keyword search + vector embeddings combined via Reciprocal Rank Fusion. Three modes: Local (embeddinggemma-300M, 768-dim, no API key, works offline), API (any OpenAI-compatible /v1/embeddings endpoint: OpenAI, Ollama, Jina, etc.), or FTS5-only (no embeddings, VPS-friendly, ~0 RAM overhead). Auto-detects VPS environments and disables local embeddings
Dynamic Brain System System brain assembled from workspace MD files (SOUL, USER, AGENTS, TOOLS, MEMORY) — all editable live between turns
Multi-Agent Orchestration Spawn typed child agents (General, Explore, Plan, Code, Research) for parallel task execution. Five tools: spawn_agent, wait_agent, send_input, close_agent, resume_agent. Each type gets a role-specific system prompt and filtered tool registry. Configurable subagent provider/model. Children run in isolated sessions with auto-approve — no recursive spawning
Recursive Self-Improvement ⚠️ Experimental. Automatic feedback ledger tracks every tool execution, user correction, and provider error. Three tools: feedback_record (log observations), feedback_analyze (query patterns), self_improve (autonomously apply brain file changes — no human approval). Changes logged to ~/.opencrabs/rsi/improvements.md with daily archives. Startup digest injects performance summary into system prompt. Upstream template sync — automatically detects new releases, fetches updated brain file templates from the repo, diffs against local files, and appends only new sections (never overwrites user customizations). Backups created before every merge. Zero tokens spent when version unchanged. Zero setup — works out of the box via auto-migration

Multimodal Input

Feature Description
Image Attachments Paste image paths or URLs into the input — auto-detected and attached as vision content blocks for multimodal models. Also supports pasting raw image data from the clipboard (copied from a browser, screenshot tool, or any app) — on macOS via the clipboard as PNG, on Linux via wl-paste/xclip. The bytes are written to a temp file and routed through the existing image pipeline
Video Attachments Send a video on any channel (mp4, m4v, mov, webm, mkv, avi, 3gp, flv) or paste a video path in the TUI — the agent calls the analyze_video tool, which routes through Google Gemini's multimodal video API (inline ≤18 MB, resumable Files API for larger). Requires image.vision.enabled = true with a Gemini API key in config.toml. Phase 1 is Gemini-native; a frame-extraction fallback for non-Gemini providers (ffmpeg → analyze_image per frame) is on the roadmap
PDF Support Attach PDF files by path — native Anthropic PDF support; for other providers, text is extracted locally via pdf-extract. Scanned / image-only PDFs (no embedded text) are rendered to page images so vision models can read them — this needs poppler (pdftoppm) on the system: macOS brew install poppler, Debian/Ubuntu apt install poppler-utils, Fedora dnf install poppler-utils. The one-line installer sets this up automatically; without it, the PDF is still saved and its path handed to the agent (text extraction and the pdf_to_images tool can be retried once poppler is present)
Document Parsing Built-in parse_document tool extracts text from PDF, DOCX, XLSX, XLS, CSV, HTML, TXT, MD, JSON, XML. Excel files are parsed into readable table format with sheet headers
Document Generation Built-in generate_document tool creates XLSX (live Excel formulas), DOCX, and PDF natively in Rust with zero host dependencies, plus PPTX via python-pptx when present. Full styling per format: brand colors, page headers/footers with logos and page numbers, zebra tables, frozen headers, autofilters, number formats, PowerPoint brand templates. Image blocks embed PNG/JPEG inline with optional captions in PDF and DOCX. Generated files are delivered as downloadable attachments on Telegram/WhatsApp/Discord. See Document Generation
Voice (STT) Voice notes transcribed via **Gro

Extension points exported contracts — how you extend this code

Tool (Interface)
(no doc) [83 implementers]
src/brain/tools/trait.rs
RetryableError (Interface)
Trait for errors that can be classified as retryable [3 implementers]
src/utils/retry.rs
OptionalExt (Interface)
Extension trait for rusqlite optional queries [1 implementers]
src/channels/whatsapp/store/mod.rs
PoolExt (Interface)
Extension trait for Pool convenience methods [1 implementers]
src/db/database.rs
Provider (Interface)
(no doc) [30 implementers]
src/brain/provider/trait.rs
OptionalExt (Interface)
Extension trait for rusqlite to add `.optional()` to query results [1 implementers]
src/db/repository/file.rs
OptionalExt (Interface)
Extension trait for rusqlite to add `.optional()` to query results [1 implementers]
src/db/repository/session.rs
OptionalExt (Interface)
Extension trait for rusqlite to add `.optional()` to query results [1 implementers]
src/db/repository/project.rs

Core symbols most depended-on inside this repo

clone
called by 2532
src/tui/events.rs
is_empty
called by 1545
src/config/secrets.rs
len
called by 1087
src/config/secrets.rs
get
called by 821
src/tui/pane/state.rs
path
called by 436
src/config/profile.rs
get
called by 400
src/brain/tools/registry.rs
context
called by 374
src/services/context.rs
insert
called by 329
src/db/repository/cron_job.rs

Shape

Function 6,549
Method 2,368
Class 618
Enum 135
Interface 12

Languages

Rust100%
Python1%

Modules by API surface

src/brain/provider/custom_openai_compatible.rs100 symbols
src/tests/self_healing_test.rs88 symbols
src/config/types.rs87 symbols
src/tests/subagent_test.rs84 symbols
src/tests/rsi_test.rs83 symbols
src/brain/agent/service/builder.rs74 symbols
src/tests/qwen_tool_extractor_test.rs70 symbols
src/tests/onboarding_wizard_test.rs70 symbols
src/tests/fallback_vision_test.rs68 symbols
src/channels/telegram/handler.rs67 symbols
src/tests/voice_onboarding_test.rs66 symbols
src/tests/telegram_resume_test.rs66 symbols

For agents

$ claude mcp add opencrabs \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact