repository·main·Indexed 21 days ago
https://github.com/adolfousier/opencrabsA high-performance, privacy-focused autonomous AI agent delivered as a single Rust binary. OpenCrabs runs locally, managing its own memory, tools, and brain files while communicating directly with LLM providers like Anthropic, OpenAI, and GitHub Copilot. It features a zero-telemetry architecture, a three-tier memory system, multi-agent orchestration, and multimodal support for images, video, and PDFs. It also includes integrated STT/TTS capabilities and a real-time usage dashboard for monitoring token consumption and costs.
OpenCrabs provides over 40 built-in tools that the AI agent can use during a conversation. These tools are categorized into several functional groups:
hashline_edit for precise, hash-anchored editing), executing shell commands via bash, and parsing various document formats.web_search, exa_search, brave_search), making HTTP requests, and native URL-to-markdown scraping via web_scrape.generate_image), analyzing images via vision models, and analyzing video files via multimodal APIs.plan (for structured work), config_manager, cron_manage (scheduling), and evolve (self-updating).OpenCrabs automatically processes incoming files, images, and documents across various channels.
analyze_image tool (Google Gemini vision)..txt, .md, .json, .csv, and source code are extracted as UTF-8 and included inline (up to 8,000 characters). In the TUI, users can paste or type the file path.mp4, m4v, mov, webm, mkv, avi, 3gp, and flv are routed to analyze_video if image.vision.enabled = true and a Gemini API key is provided.Channel Capabilities Matrix:
| Channel | Images | Text Files | Documents | Audio (In) | Audio (Out) | Image Gen |
|---|---|---|---|---|---|---|
| Telegram | Vision | Inline | STT | TTS (send_voice) | Native | |
| Vision | Inline | STT | TTS (audio_message) | Native | ||
| Discord | Vision | Inline | STT | TTS (response.ogg) | Attachment | |
| Slack | Vision | Inline | STT | TTS (Upload) | Upload | |
| Trello | Vision | Inline | — | — | — | Attachment |
| TUI | Path $\to$ Vision | Path $\to$ Inline | — | STT | — | [IMG: name] |
OpenCrabs is an agentic system composed of several interacting layers designed for autonomy, self-healing, and recursive improvement.
Key components include:
message send, tasks get, tasks cancel).The Telegram interface for Plan Mode follows specific UI patterns to maintain a smooth user experience during the 1.5s edit loop:
open_group_msg_id).refresh_flow loop to update the live duration and activity. Because Telegram clients may reset the 'expand/collapse' state of a message upon every edit, the UI is designed to keep critical information (plan title, checklist progress like 2/7, and active goal one-liner) in the always-visible chrome (header or summary).plan init has succeeded. During the 'Editing' phase, Approve and Discard appear on the latest flow message, but Approve is refused if a turn is currently running.OpenCrabs uses a structured memory system located in ~/.opencrabs/memory/ to maintain context across sessions. It distinguishes between daily logs and long-term distilled knowledge.
memory/YYYY-MM-DD.md)Automatically triggered by:
MEMORY.md)Updated when high-level information changes:
- NEVER push without explicit approval).You can spawn typed child agents to execute tasks in parallel. Available agent types include General, Explore, Plan, Code, and Research. Each type has a specific system prompt and a filtered set of tools.
Agent Control Tools:
spawn_agent: Create a new child agent.wait_agent: Wait for an agent to complete.send_input: Provide input to an agent.close_agent: Terminate an agent session.resume_agent: Resume a paused agent.Child agents run in isolated sessions with auto-approval and do not support recursive spawning.
OpenCrabs uses a three-tier memory architecture to maintain context and long-term knowledge:
MEMORY.md): User-curated durable memory loaded on demand into the main session.~/.opencrabs/memory/YYYY-MM-DD.md.Memory Search Modes:
embeddinggemma-300M (768-dim). Works offline with no API key. Automatically disabled in VPS environments./v1/embeddings endpoint (e.g., OpenAI, Ollama, Jina).The MEMORY.md file serves as the dedicated storage for an agent's long-term memory. It is used to store user-specific facts, corrections, preferences, and lessons learned during interactions to prevent repeated mistakes.
Key Distinctions:
SOUL.md).Structure of the Memory File:
The evaluation harness (src/eval/) is used to measure context engineering and memory recall quality. It is gated behind the eval feature and cfg(test).
Offline Evaluation: Uses a fixture replay provider to drive the agent loop from scripted responses without network access. It checks context manifests, compaction fidelity, and recall metrics (precision@k, recall@k, etc.).
Live Evaluation: Uses a chain of providers to act as a majority-vote judge panel. You can configure this in your configuration file:
[agent]
# Ordered chain of provider names; each judge uses that provider's own default_model.
eval_providers = ["anthropic", "openrouter", "zhipu"][agent]
eval_providers = ["anthropic", "openrouter", "zhipu"]When implementing Plan Mode, the Umbrella Plan (src/docs/reference/plans/plan-mode/umbrella.md) is the Single Source of Truth (SSOT) for the full product narrative and locked decisions.
While individual ADRs (Clusters A-D) serve as execution slices, if a product question or lifecycle edge case conflicts between an ADR and the Umbrella Plan, always trust the Umbrella Plan.