EdgeCrab 🦀

"Your SuperAgent — built in Rust."

EdgeCrab is a SuperAgent — a personal assistant and coding agent forged in Rust. It carries the soul of Nous Hermes Agent (autonomous reasoning, persistent memory, user-first alignment) and the always-on presence of OpenClaw (15 messaging gateways, smart-home integration), packaged as a stripped native release binary of about 49 MB on current macOS arm64 builds, with zero Python or Node.js runtime dependencies.

hermes-agent soul  +  OpenClaw vision  =  EdgeCrab
   (reasoning)          (presence)        (Rust)

• EdgeCrab 🦀
  • Architecture
  • Table of Contents
  • Why EdgeCrab?
  • Quick Start (90 seconds)
    • Option A — npm (no Rust required)
    • Option B — pip (no Rust required)
    • Option C — cargo
    • Option D — build from source
    • Guided Setup Output
    • First Prompts
  • What EdgeCrab Can Do
    • ReAct Tool Loop
    • Built-in Tools
    • Semantic Code Intelligence (LSP)
      • File Tools (file toolset)
      • Terminal Tools (terminal toolset)
      • Web Tools (web toolset)
      • Browser Tools (browser toolset)
      • Memory & Honcho Tools (memory + honcho toolsets)
      • Skills Tools (skills toolset)
      • Session & Search (session toolset)
      • Delegation & MoA (delegation + moa toolsets)
      • Code Execution (code_execution toolset)
      • MCP Tools (mcp toolset)
      • Media Tools (vision / tts / transcribe toolsets)
      • Automation Tools
    • Sub-agent Delegation
    • Sandboxed Code Execution
    • Browser Automation
    • 15 Messaging Gateways
    • Persistent Memory & Learning
    • Skills Library
    • Plugin System
    • Cron Scheduling
    • Checkpoints & Rollback
    • Profiles & Worktrees
    • Vision, TTS & Transcription
  • 15 LLM Providers
  • 6 Terminal Backends
  • MCP Server Integration
  • ACP / VS Code Copilot Integration
  • ratatui TUI
  • All CLI Commands
  • All Slash Commands
  • Security Model
  • Architecture
  • Configuration
  • SDK: Python & Node.js
    • Python SDK (edgecrab-sdk)
    • Node.js SDK (edgecrab-sdk)
  • Docker
  • Migrating from hermes-agent
  • Testing
  • Project Structure
  • Requirements & Build
  • Contributing
  • Release Channels
  • License

Most AI agents are either too constrained (coding agents that forget you exist after the session) or too heavy (Python runtimes, Node daemons, GBs of RAM). EdgeCrab is different.

It learns. Like Nous Hermes Agent, EdgeCrab maintains persistent memory across sessions, auto-generates reusable skills, and builds a cross-session Honcho user model that gets smarter over time.

It's everywhere. Like OpenClaw, EdgeCrab lives in your channels — Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, DingTalk, SMS, Email, Home Assistant, and more. Send it a voice memo on WhatsApp and get a PR back.

It's fast and lean. Unlike Python agents, EdgeCrab ships as a native Rust binary instead of a Python or Node.js runtime stack. Current stripped macOS arm64 release builds land around 49 MB, and security is compiled in — path jails, SSRF guards, command scanners — not runtime patches.

It's extensible. MCP servers, custom Rust tools, Python/JS sandboxes, sub-agents, Mixture-of-Agents consensus — the full toolkit for heavy-duty automation.

It's now plugin-native. Skill plugins inject prompt expertise, tool-server plugins expose external JSON-RPC tools, and script plugins run safe Rhai logic, all from ~/.edgecrab/plugins/ with persisted enable/disable policy.

npm install -g edgecrab-cli
edgecrab update              # channel-aware updater
edgecrab setup               # interactive wizard — detects API keys, writes config
edgecrab doctor              # verify health
edgecrab                     # launch TUI

pip install edgecrab-cli
# OR: pipx install edgecrab-cli  (isolated install)
edgecrab update
edgecrab setup && edgecrab doctor && edgecrab

cargo install edgecrab-cli
edgecrab update --check
edgecrab setup && edgecrab doctor && edgecrab

git clone https://github.com/raphaelmansuy/edgecrab
cd edgecrab
cargo build --workspace --release         # ~30 s first build
./target/release/edgecrab setup

EdgeCrab Setup Wizard
──────────────────────────────────────────────────────────────
✓ Detected GitHub Copilot (GITHUB_TOKEN)
✓ Detected OpenAI (OPENAI_API_KEY)

Choose LLM provider:
  [1] copilot      (GitHub Copilot — gpt-4.1-mini)  ← auto-detected
  [2] openai       (OpenAI — GPT-4.1, GPT-5, o3/o4)
  [3] anthropic    (Anthropic — Claude Opus 4.6)
  [4] ollama       (local — llama3.3)
  ...
Provider [1]: 1

✓ Config written to ~/.edgecrab/config.yaml
✓ Created ~/.edgecrab/memories/
✓ Created ~/.edgecrab/skills/

Run `edgecrab` to start chatting!

edgecrab "summarise the git log for today and open PRs"
edgecrab --model anthropic/claude-opus-4-6 "review this codebase for security issues"
edgecrab --model ollama/llama3.3 "explain this code offline"
edgecrab --quiet "count lines in src/**/*.rs"   # pipe-safe, no banner
edgecrab -C "continue-my-refactor"              # resume named session
edgecrab -w "explore that perf idea"            # isolated git worktree

EdgeCrab is an autonomous agent. Give it a goal in natural language; it reasons, calls tools, observes results, and loops until the task is done. Here's what it can actually reach.

EdgeCrab uses a Reason → Act → Observe loop (ReAct pattern) implemented in crates/edgecrab-core/src/conversation.rs. Each turn:

1. System prompt built once per session (SOUL.md, AGENTS.md, memories, skills, date/time, cwd) — cached for Anthropic prompt cache hits
2. LLM decides what to do next (including parallel tool calls)
3. Security check runs before every tool execution (path jail, SSRF guard, command scan)
4. Tool executes — file I/O, shell, web, code, sub-agents, browser, etc.
5. Result injected back into context
6. Loop until no more tool calls (task done), Ctrl-C, or 90-iteration budget exhausted
7. Context compression fires at 50% of context window — prunes old tool outputs, then LLM-summarizes
8. Learning reflection auto-fires after ≥5 tool calls — agent can save new skills and update memory

The budget default is 90 iterations (max_iterations in config). Increase it for long autonomous tasks.

Tools are registered at compile time via the inventory crate — zero startup cost. The ToolRegistry dispatches by exact name with fuzzy (Levenshtein ≤3) fallback suggestions.

EdgeCrab now exposes a dedicated LSP subsystem through the lsp toolset. When a language server is configured, the agent can prefer semantic operations over grep-style guesses:

• Claude-parity navigation: lsp_goto_definition, lsp_find_references, lsp_hover, lsp_document_symbols, lsp_workspace_symbols, lsp_goto_implementation, lsp_call_hierarchy_prepare, lsp_incoming_calls, lsp_outgoing_calls
• EdgeCrab-only semantic edits: lsp_code_actions, lsp_apply_code_action, lsp_rename, lsp_format_document, lsp_format_range
• Deep analysis: lsp_inlay_hints, lsp_semantic_tokens, lsp_signature_help, lsp_type_hierarchy_prepare, lsp_supertypes, lsp_subtypes
• Diagnostics: lsp_diagnostics_pull, lsp_linked_editing_range, lsp_enrich_diagnostics, lsp_select_and_apply_action, lsp_workspace_type_errors

Built-in default server definitions now cover Rust, TypeScript, JavaScript, Python, Go, C, C++, Java, C#, PHP, Ruby, Bash, HTML, CSS, and JSON.

Control which toolsets are active:

edgecrab --toolset file,terminal "add tests"        # minimal dev
edgecrab --toolset all "go wild"                    # full capability
edgecrab --toolset coding "refactor this module"    # file+terminal+search+exec+lsp
edgecrab --toolset research "investigate this bug"  # web+browser+vision

EdgeCrab can spawn sub-agents that run the full ReAct loop with their own session state. This enables parallelism for complex tasks.

# Example: agent delegates 3 subtasks in parallel
delegate_task([
  { task: "Review auth module for security issues" },
  { task: "Write unit tests for the payment service" },
  { task: "Update API documentation" }
])
# → 3 sub-agents run concurrently, results aggregated

How it works (crates/edgecrab-tools/src/tools/delegate_task.rs):

• Sub-agents share LLM provider Arc + tool registry Arc
• Each child gets its own SessionState, ProcessTable, TodoStore, IterationBudget
• Max concurrent: 3 sub-agents in parallel (configurable via delegation.max_subagents)
• Max depth: 2 levels (parent → child → grandchild blocked)
• Children cannot use delegation, clarify, memory, code_execution, or messaging toolsets

Configure delegation:

delegation:
  enabled: true
  model: "anthropic/claude-sonnet-4"   # use cheaper model for sub-agents
  max_subagents: 3
  max_iterations: 50

The execute_code tool runs code in an isolated subprocess with strict resource limits:

• Languages: Python, JavaScript, Bash, Ruby, Perl, Rust
• Tool RPC: Scripts can call 7 tools via Unix domain socket — web_search, web_extract, read_file, write_file, search_files, terminal, session_search
• Limits: 50-tool call limit, 5-minute timeout, 50 KB stdout cap, 10 KB stderr cap
• Security: API keys/tokens stripped from child environment before execution

# Example: agent writes and executes this in a sandbox
import subprocess
result = subprocess.run(['cargo', 'test', '-p', 'edgecrab-core'], capture_output=True)
print(result.stdout.decode())

Chrome DevTools Protocol-based browser automation — no Selenium, no Playwright dependency. ElementCrab connects directly to a CDP endpoint.

Requirements: Chrome/Chromium binary, or set CDP_URL to an existing instance
Check:         edgecrab doctor  (reports browser availability)

The browser_snapshot tool returns an accessibility tree — not pixels — so the LLM can reason about page structure without vision costs. browser_screenshot adds numbered element overlays for precise clicking.

Start the gateway server and EdgeCrab becomes an always-on assistant in 15 messaging platforms simultaneously:

edgecrab gateway start           # runs in background
edgecrab gateway start --foreground   # keep in foreground
edgecrab gateway status          # check which platforms are live
edgecrab gateway stop

Streaming delivery: Edit-mode platforms (Telegram, Discord, Slack) receive live token streaming with 300ms edit intervals. Batch-mode platforms (WhatsApp, Signal, SMS, Email) accumulate the full response and send once.

Built-in gateway slash commands (send via chat):

/help      /new       /reset     /stop      /retry
/status    /usage     /background  /approve   /deny

Setup WhatsApp (one-time QR pairing):

edgecrab whatsapp      # launches QR code scanner wizard
# Scan with your phone — session persists across restarts
edgecrab gateway start

Cron-triggered messages: Schedule the agent to proactively message you:

# ~/.edgecrab/cron/daily-standup.json
schedule: "0 9 * * 1-5"     # every weekday at 9am
task: "Summarize open PRs and blockers for today's standup"
target: telegram             # deliver to your Telegram

EdgeCrab has a three-layer memory system:

Layer 1 — MEMORY.md (~/.edgecrab/memories/MEMORY.md): Free-form notes. The agent reads this at session start and can update it. You can also edit it directly.

Layer 2 — SQLite session history (~/.edgecrab/state.db): Every conversation stored in WAL-mode SQLite with FTS5 full-text search. Browse, search, and export sessions:

edgecrab sessions list                           # list recent sessions
edgecrab sessions search "auth bug from last week"  # FTS5 search
edgecrab sessions export <id> --format jsonl     # export session
edgecrab sessions browse                         # interactive browser

Layer 3 — Honcho cross-session user model: EdgeCrab builds a semantic model of you — your preferences, projects, working style — via the Honcho API. This context is injected at the start of new sessions to provide continuity.

Auto-learning: After ≥5 tool calls in a session, a learning reflection fires automatically. The agent can save new skills, update MEMORY.md, and record useful patterns without being asked.

Skills are reusable agent procedures — markdown files that define prompts, steps, and best practices for recurring tasks. Think recipe cards for your agent.

# Create a skill
edgecrab skills list                    # browse installed skills
edgecrab skills view git-workflow       # read a skill
edgecrab skills install my-skill.md    # install from file
edgecrab skills search "diagram"       # search remote skill sources
edgecrab skills install edgecrab:diagramming/ascii-diagram-master
edgecrab skills install hermes-agent:research/ml-paper-writing
edgecrab skills install raphaelmansuy/edgecrab/skills/research/ml-paper-writing
edgecrab skills update                 # refresh all remote-installed skills
edgecrab skills update ml-paper-writing

# Use a skill in a session
edgecrab -S git-workflow "review this branch for prod readiness"
edgecrab -S security,refactor          # load multiple skills

Inside TUI: /skills opens the installed-skill browser, and /skills search [query] opens the remote-skill browser with live search, source notes, and install/update actions.

Skills are saved to ~/.edgecrab/skills/ and loaded on demand. The agent can also create new skills mid-session during learning reflection.

Claude-style skill bundles with helper scripts are supported in the standalone skills runtime:

• bundled helper files under references/, templates/, scripts/, and assets/
• ${CLAUDE_SKILL_DIR} substitution to the concrete skill directory
• ${CLAUDE_SESSION_ID} substitution to the active EdgeCrab session id
• the same bundle rendering for skill_view and preloaded --skill / skills.preloaded flows
• parsing and display of when_to_use, arguments, argument-hint, allowed-tools, user-invocable, disable-model-invocation, context, and shell

Current boundary: EdgeCrab does not auto-execute Claude inline prompt-shell blocks and does not auto-fork a dedicated skill sub-agent from those metadata fields alone.

First principles:

• A skill is reusable guidance for the model.
• A plugin is an installable runtime unit that EdgeCrab discovers, enables, disables, updates, and audits.

That leads to a clean operational split:

• Use skills when the extension is instructions-first: procedures, examples, checklists, workflow scaffolding, or bundled helper files/scripts that the agent uses through normal tools.
• Use plugins when the extension needs executable code, tool registration, hooks, readiness checks, trust metadata, or install lifecycle management.
• A plain skill changes prompt behavior. It can bundle helper files such as scripts/, references/, templates/, and assets/, but it still does not register a new runtime service or plugin lifecycle on its own.
• A plugin may bundle a SKILL.md, but that bundled skill is still part of a plugin-managed runtime bundle.

Concrete examples:

• ~/.edgecrab/skills/security-review/SKILL.md is a standalone skill.
• ~/.edgecrab/skills/security-review/scripts/check.py can be bundled with that skill and referenced from SKILL.md.
• ~/.edgecrab/plugins/github-tools/plugin.toml is a plugin.
• ~/.edgecrab/plugins/calculator/plugin.yaml plus __init__.py is a Hermes plugin.
• A plugin of kind skill is still managed through edgecrab plugins ..., not edgecrab skills ....

Plugins extend EdgeCrab beyond the built-in tool inventory without forking the repo.

edgecrab plugins list
edgecrab plugins info github-tools
edgecrab plugins status
edgecrab plugins install github:edgecrab/plugins/github-tools
edgecrab plugins install hub:community/github-tools
edgecrab plugins install https://example.com/github-tools.zip
edgecrab plugins install ./plugins/github-tools
edgecrab plugins enable github-tools
edgecrab plugins disable github-tools
edgecrab plugins toggle [github-tools]
edgecrab plugins audit --lines 20
edgecrab plugins search github
edgecrab plugins search --source hermes weather
edgecrab plugins search --source hermes-evey telemetry
edgecrab plugins browse
edgecrab plugins update
edgecrab plugins remove github-tools

Inside the TUI, /plugins search ... and /plugins browse now open the same kind of async remote browser EdgeCrab already uses for skills and MCP: fuzzy filtering, background search, split-detail view, and one-key install or replace from official registries.

EdgeCrab now supports four plugin kinds:

• skill plugins load SKILL.md content from ~/.edgecrab/plugins/<name>/ into the session prompt with Hermes-compatible frontmatter, readiness checks, and platform filtering.
• tool-server plugins spawn a subprocess and proxy MCP-compatible newline-delimited JSON-RPC over stdio, including reverse host:* calls for platform info, memory/session access, secret reads, safe conversation message injection, logging, and delegated tool execution.
• script plugins load Rhai code for lightweight local extension points and tool handlers without shipping a separate daemon.
• hermes plugins load Hermes-style Python directory plugins with plugin.yaml + __init__.py register(ctx) compatibility, including requires_env setup gating, bundled SKILL.md loading, post_tool_call, on_session_start, pre_llm_call, and on_session_end.

EdgeCrab also discovers legacy Hermes plugin roots from ~/.hermes/plugins/, plus ./.hermes/plugins/ when HERMES_ENABLE_PROJECT_PLUGINS=true. Plugin installs now stage in quarantine, run a static security scan, resolve trust from their source, and stamp plugin.toml with a directory checksum before activation. Plugin state persists in config.yaml under plugins:. Disabled or setup-needed plugins are excluded from tool exposure or prompt injection without uninstalling them.

Runtime exposure is live:

• enabled plugin tools are registered into the plugins toolset and appear in /tools
• disabling a plugin removes its tools from the active registry without restarting EdgeCrab
• re-enabling a plugin re-exposes those tools immediately in the same TUI session

Inside the TUI you can verify that directly:

/plugins                 # open the installed-plugin browser overlay
/tools                   # shows active built-in + plugin tools
/plugins disable demo
/tools                   # demo plugin tools are gone
/plugins enable demo
/tools                   # demo plugin tools are back under the plugins toolset

Remote plugin search is cached by first principles:

• hub indexes and repo-backed source trees are cached under ~/.edgecrab/plugins/.hub/cache/
• repo-backed plugin descriptions are cached separately so repeated searches do not refetch plugin.yaml or SKILL.md
• expired cache is refreshed when possible, but stale cache is still used on refresh failure so plugin search degrades gracefully instead of going empty

Example: install a Hermes guide-style local plugin with a bundled skill:

calculator/
├── plugin.yaml
├── __init__.py
├── schemas.py
├── tools.py
├── SKILL.md
└── data/
    └── units.json

edgecrab plugins install ./calculator
edgecrab plugins info calculator
edgecrab plugins status

This repository also ships official Hermes-format examples that are indexed by the edgecrab-official search source:

edgecrab plugins search --source edgecrab calculator
edgecrab plugins search --source edgecrab json

edgecrab plugins install ./plugins/productivity/calculator
edgecrab plugins install ./plugins/developer/json-toolbox

edgecrab plugins info calculator
edgecrab plugins info json-toolbox

Those examples prove two different Hermes runtime surfaces:

• plugins/productivity/calculator registers tools plus a post_tool_call hook
• plugins/developer/json-toolbox registers tools plus a top-level CLI command

Example: install real Hermes assets directly from a local clone of NousResearch/hermes-agent:

edgecrab plugins install ~/src/hermes-agent/plugins/memory/holographic
edgecrab plugins info holographic

# pip entry-point plugins are discovered through the selected Python runtime
EDGECRAB_PLUGIN_PYTHON=~/.venvs/hermes/bin/python \
  edgecrab plugins list
EDGECRAB_PLUGIN_PYTHON=~/.venvs/hermes/bin/python \
  edgecrab entry-demo status

Standalone Hermes skills are browsed from the skills surface instead of the plugin browser:

edgecrab skills search 1password
edgecrab skills install hermes-agent:security/1password

Example: search and install curated community Hermes plugins from 42-evey/hermes-plugins:

edgecrab plugins search --source hermes-evey telemetry
edgecrab plugins install hub:hermes-evey/evey-telemetry
edgecrab plugins install hub:hermes-evey/evey-status
edgecrab plugins info evey-telemetry

For a step-by-step authoring tutorial, see docs/007_memory_skills/005_building_hermes_style_plugins.md and the site guide at site/src/content/docs/guides/build-hermes-plugin.md.

Compatibility proof currently covers:

• official repo Hermes examples calculator and json-toolbox, including search visibility and local end-to-end install/runtime proof
• guide-style Hermes plugin install and end-to-end tool execution from the upstream "Build a Hermes Plugin" contract
• real upstream Hermes plugin install and runtime execution for holographic
• real upstream Hermes optional-skill compatibility for 1password via local bundle install
• real upstream Python import/runtime shims plus cli.py register_cli(subparser) CLI bridging for honcho
• real 42-evey/hermes-plugins runtime execution for evey-telemetry and evey-status
• pip entry-point discovery and top-level Hermes CLI command execution through ctx.register_cli_command()
• Hermes hub indexing for upstream plugins/... directories and 42-evey repo-root Hermes directories in the plugin browser
• full Hermes VALID_HOOKS surface in the CLI runtime: pre_tool_call, post_tool_call, pre_llm_call, post_llm_call, pre_api_request, post_api_request, on_session_start, on_session_end, on_session_finalize, on_session_reset
• gateway per-chat session isolation and session-boundary parity proof for on_session_start, on_session_end, on_session_finalize, and on_session_reset

Schedule recurring or one-shot tasks:

edgecrab cron list
edgecrab cron add "0 9 * * 1-5" "Summarize open PRs for standup"
edgecrab cron add "@daily" "Update MEMORY.md with project progress"
edgecrab cron pause <id>
edgecrab cron resume <id>
edgecrab cron remove <id>
edgecrab cron run <id>      # manual trigger
edgecrab cron tick          # process due jobs (called by system cron)

Or from within a TUI session:

/cron list
/cron add "0 18 * * 5" "Generate weekly summary"

The manage_cron_jobs tool also lets the agent schedule its own follow-ups autonomously.

Before destructive operations, EdgeCrab creates filesystem snapshots:

# Manual checkpoint
edgecrab sessions
# → checkpoint auto-created before every file write

# Inside TUI
/rollback                    # restore last checkpoint
/rollback checkpoint-abc123  # restore specific checkpoint

Configuration:

checkpoints:
  enabled: true
  max_snapshots: 50    # keep last 50 checkpoints per session

The checkpoint tool is also available to the agent itself — it can snapshot before risky operations and offer rollback if something goes wrong.

Profiles give EdgeCrab isolated runtime homes with separate config.yaml, .env, SOUL.md, memories, skills, plugins, hooks, MCP tokens, and state.db. EdgeCrab now seeds three starter profiles by default: work, research, and homelab.

edgecrab profile list                # default + bundled starters
edgecrab profile show work
edgecrab profile use work            # sticky default profile
edgecrab -p research "compare SDKs"  # one-shot override
edgecrab profile alias work --name w
edgecrab profile list

Starter profile examples:

# ~/.edgecrab/profiles/work/config.yaml
model:
  default: "anthropic/claude-opus-4.6"
  max_iterations: 90

display:
  personality: "technical"
  tool_progress: "verbose"
  show_cost: true

reasoning_effort: "high"

# ~/.edgecrab/profiles/research/config.yaml
model:
  default: "openai/gpt-5"
  max_iterations: 120

display:
  personality: "teacher"

reasoning_effort: "high"

In the TUI, /profile now mirrors Hermes and shows the active profile name plus its effective home directory. /profiles opens the interactive browser, and /profile show <name> jumps that browser to a specific profile. Inside it: Enter switch, C config, S SOUL, M memory, T tools, A alias, E export, D delete, N create, I import, O rename, Tab or Left/Right cycle detail views, and Home/End jump through results. The runtime switch is live, not deferred to the next launch.

Worktrees isolate each agent session in a separate git worktree:

edgecrab -w "explore that refactor idea safely"
# Creates ~/.edgecrab/worktrees/<name>/, runs there
# Changes stay isolated — merge or discard when done

# Vision: analyze an image
edgecrab "What's in this screenshot?" --attach screenshot.png

# TTS: speak the response
edgecrab --quiet "Write a haiku about Rust" | say   # pipe to macOS say
# Or the agent can generate audio directly via text_to_speech tool

# Transcription: send a voice note via WhatsApp gateway
# → EdgeCrab transcribes it with Whisper and responds

Vision providers: any multimodal model (Claude, GPT-4o, Gemini). TTS providers: OpenAI TTS, edge-tts (offline). Transcription: Whisper (local), Groq Whisper, OpenAI Whisper.

EdgeCrab ships with 15 LLM providers out of the box (13 cloud, 2 local). Over 200 models are compiled in, with user override via ~/.edgecrab/models.yaml.

Switch provider at any time:

edgecrab --model anthropic/claude-opus-4-6 "deep code review"
edgecrab --model ollama/llama3.3 "work offline"
edgecrab --model groq/llama-3.3-70b-versatile "quick task"

Hot-swap inside TUI:

/model groq/llama-3.3-70b-versatile
/reasoning high                      # enable extended thinking (Anthropic/OpenAI)

Smart routing (experimental): automatically selects cheap vs full model by turn complexity:

model:
  smart_routing:
    enabled: true
    cheap_model: "groq/llama-3.3-70b-versatile"

Mixture of Agents: Run a single prompt through 4 frontier models simultaneously and get a synthesized consensus:

/model moa    # Claude Opus 4.6 + Gemini 2.5 Pro + GPT-4.1 + DeepSeek R1 → aggregated

The terminal tool is pluggable. Select your execution environment:

terminal:
  backend: docker
  docker:
    image: "python:3.12-slim"
    container_name: "edgecrab-sandbox"

EdgeCrab is a full MCP (Model Context Protocol) client. Connect any MCP server and its tools become available to the agent automatically.

# ~/.edgecrab/config.yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"]

  my-api-server:
    url: "https://my-server.example.com/mcp"
    bearer_token: "${MY_API_TOKEN}"   # env-backed bearer token works
    enabled: true

edgecrab mcp list                                 # show configured MCP servers
edgecrab mcp install filesystem --path "/tmp/ws" # install a curated preset
edgecrab mcp doctor                              # static checks + live probe
edgecrab mcp doctor filesystem                   # diagnose one configured server
edgecrab mcp remove server-name
/mcp                                             # open the TUI MCP browser
/reload-mcp                                      # hot-reload in TUI without restart

The agent uses mcp_list_tools and mcp_call_tool to discover and invoke MCP server capabilities. The TUI MCP browser supports install, view, test, diagnose, and remove flows, and quoted --path / name= values are parsed safely for Unix and Windows-style paths. HTTP MCP servers that rely on OAuth-style bearer access tokens are supported through either bearer_token, /mcp-token set <server> <token>, or env-backed config values such as bearer_token: "${MY_API_TOKEN}".

EdgeCrab implements the Agent Communication Protocol — JSON-RPC 2.0 over stdio — enabling it to run as a VS Code Copilot agent, in Zed, JetBrains, and any ACP-compatible runner.

edgecrab acp           # starts ACP server on stdin/stdout
edgecrab acp init      # scaffold agent.json manifest for a workspace

The acp_registry/agent.json manifest declares capabilities for extension discovery. The ACP adapter uses a restricted ACP_TOOLS subset that excludes interactive-only tools (clarify, send_message, text_to_speech).

60 fps capable, GPU-composited full-screen TUI built with ratatui.

Layout:

┌────────────────────────────────────────────────────────────┐
│  output area (markdown-rendered, mouse-scrollable)          │
│  ⚙  file_read  src/main.rs                                  │
│     → 342 lines read                                        │
│                                                             │
│  The `main` function initializes the agent loop and...      │
├────────────────────────────────────────────────────────────┤
│ ● anthropic/claude-opus-4-6  1,234t  $0.023  [/commands]  │
├────────────────────────────────────────────────────────────┤
│ ❯ Type your message…                                        │
└────────────────────────────────────────────────────────────┘

Features:

• Streaming output with token-by-token rendering
• Fish-style ghost text (type-ahead) completion
• Tab-complete slash commands with fuzzy match overlay
• Multi-line input (Shift+Enter for newlines)
• Mouse scroll in output area
• Approval dialogs for dangerous operations (inline, non-blocking)
• Clarify dialogs — agent asks questions without blocking the loop
• Secret-request overlays — prompt for missing API keys mid-session
• Session spinner + model name + token count + cost in status bar

Theme customization (~/.edgecrab/skin.yaml):

user_fg:      "#89b4fa"   # Catppuccin blue
assistant_fg: "#a6e3a1"   # Catppuccin green
system_fg:    "#f9e2af"   # Catppuccin yellow
error_fg:     "#f38ba8"   # Catppuccin red
tool_fg:      "#cba6f7"   # Catppuccin mauve
status_bg:    "#313244"
status_fg:    "#cdd6f4"
border_fg:    "#6c7086"
prompt_symbol: "❯"
tool_prefix:   "⚙"

# Launch
edgecrab                          # interactive TUI
edgecrab "prompt here"            # TUI + auto-submit
edgecrab --quiet "prompt"         # no banner, pipe-safe output
edgecrab --model p/m "prompt"     # specify LLM
edgecrab --toolset web,file "p"   # restrict toolsets
edgecrab --session id "p"         # use specific session
edgecrab --resume title "p"       # resume by title
edgecrab -C "p"                   # continue last session
edgecrab -w "p"                   # isolated git worktree
edgecrab -S skill1,skill2 "p"     # preload skills

# Setup & diagnostics
edgecrab setup [--section s] [--force]    # interactive wizard
edgecrab doctor                           # full health check
edgecrab version                          # version + providers
edgecrab migrate [--dry-run]              # import hermes-agent state

# Sessions
edgecrab sessions list
edgecrab sessions browse
edgecrab sessions export <id> [--format jsonl]
edgecrab sessions delete <id>
edgecrab sessions rename <id> <title>
edgecrab sessions prune [--older-than 30d]
edgecrab sessions stats

# Configuration
edgecrab config show
edgecrab config edit
edgecrab config path
edgecrab config set <key> <value>

# Tools
edgecrab tools list
edgecrab tools enable <toolset>
edgecrab tools disable <toolset>

# Providers
edgecrab auth list
edgecrab auth status [copilot|provider/<name>|mcp/<server>]
edgecrab auth add copilot --token <github-token>
edgecrab auth add provider/openai --token <api-token>   # writes ~/.edgecrab/.env and ~/.edgecrab/auth.json
edgecrab auth add mcp/<server> --token <bearer-token>
edgecrab auth login [copilot|mcp/<server>]
edgecrab login <target>
edgecrab logout [target]                                 # clears local auth cache; provider targets also clear auth.json metadata
edgecrab mcp list
edgecrab mcp add <name>
edgecrab mcp remove <name>

# Plugins
edgecrab plugins list
edgecrab plugins info <name>
edgecrab plugins status
edgecrab plugins install <source>
edgecrab plugins audit [--lines 20]
edgecrab plugins search <query>
edgecrab plugins search --source hermes <query>
edgecrab plugins browse
edgecrab plugins refresh
edgecrab plugins toggle [name]
edgecrab plugins update [name]
edgecrab plugins remove <name>

# Cron
edgecrab cron list
edgecrab cron add "<schedule>" "<task>"
edgecrab cron run <id>
edgecrab cron tick
edgecrab cron remove <id>
edgecrab cron pause <id>
edgecrab cron resume <id>

# Gateway
edgecrab gateway start [--foreground]
edgecrab gateway stop
edgecrab gateway restart
edgecrab gateway status
edgecrab gateway configure [--platform <name>]
edgecrab webhook subscribe <name> [--events push,pull_request] [--skill code-review] [--deliver github_comment] [--deliver-extra repo=org/repo] [--deliver-extra pr_number=42] [--rate-limit 30] [--max-body-bytes 1048576]
edgecrab webhook list
edgecrab webhook test <name>
edgecrab webhook path
edgecrab whatsapp               # WhatsApp QR pairing wizard
edgecrab status                 # overall gateway status

# Cleanup
edgecrab uninstall --dry-run
edgecrab uninstall --purge-data --yes

# Skills
edgecrab skills list
edgecrab skills view <name>
edgecrab skills search <query>
edgecrab skills install <path|edgecrab:path|owner/repo/path>
edgecrab skills update [name]
edgecrab skills remove <name>

# Profiles
edgecrab profile list
edgecrab profile use <name>
edgecrab profile create <name>
edgecrab profile delete <name>
edgecrab profile show [name]
edgecrab profile alias <name> [--name alias]
edgecrab profile rename <old> <new>
edgecrab profile export <name> [--output path]
edgecrab profile import <path> [--name name]

# ACP
edgecrab acp                    # start ACP stdio server
edgecrab acp init [--workspace] [--force]

# Shell completion
edgecrab completion bash
edgecrab completion zsh
edgecrab completion fish

Type these inside the TUI (after ❯):

Every built-in slash command is also reachable from argv with edgecrab slash <command...>.

Keyboard shortcuts:

Security is compiled in — not an afterthought. EdgeCrab applies defense-in-depth at seven independent layers:

Path safety and SSRF use Rust's type system as the primary control — not runtime checks alone. If your code doesn't have a SanitizedPath, it can't call file I/O. Period.

EdgeCrab is an 11-crate Rust workspace. The dependency graph is a strict DAG — no circular dependencies, no feature flags that reverse the graph.

edgecrab-types      (shared types — no deps on other crates)
       ↑
edgecrab-security   (path safety, SSRF, cmd scan — types only)
edgecrab-cron       (standalone cron store + schedule parser)
       ↑
edgecrab-tools      (ToolRegistry + built-in tool implementations)
edgecrab-lsp        (language-server client, document sync, semantic tools)
edgecrab-state      (SQLite WAL + FTS5 session store)
       ↑
edgecrab-core       (Agent, ReAct loop, prompt builder, compression)
       ↑
edgecrab-cli    edgecrab-gateway    edgecrab-acp    edgecrab-migrate

Key design decisions (from the code):

1. Single binary — Static linking embeds all deps (TLS, SQLite, Aho-Corasick). No shared libraries except OS.
2. Type-level security — SanitizedPath and SafeUrl are distinct types in edgecrab-types. Bypassing sanitization is a compile error.
3. Compile-time tool registry — inventory::submit!() registers tools at link time. Zero startup cost. All tools present or absent by feature flag, not runtime config.
4. Single system prompt per session — Built once, cached in SessionState.cached_system_prompt. Compression never rebuilds it (preserves Anthropic prompt cache hits).
5. Hot-swappable model — RwLock<Arc<dyn LLMProvider>> in Agent. In-flight conversations keep their Arc clone; swap affects only new turns.

EdgeCrab uses layered config: defaults → ~/.edgecrab/config.yaml → EDGECRAB_* env vars → CLI flags. Later layers win.

# ~/.edgecrab/config.yaml

model:
  default_model: "ollama/gemma4:latest"
  max_iterations: 90          # ReAct loop budget per session
  streaming: true
  smart_routing:
    enabled: false
    cheap_model: ""

display:
  skin: "catppuccin"
  show_reasoning: false

tools:
  enabled_toolsets: null       # null = all toolsets active
  disabled_toolsets: null
  file:
    allowed_roots: []          # empty = cwd only
  custom_groups:
    backend-dev:
      - read_file
      - write_file
      - terminal
      - session_search

lsp:
  enabled: true
  file_size_limit_bytes: 10000000
  servers:
    rust:
      command: "rust-analyzer"
      args: []
      file_extensions: ["rs"]
      language_id: "rust"
      root_markers: ["Cargo.toml", "rust-project.json"]

memory:
  enabled: true

skills:
  enabled: true
  preloaded: []

delegation:
  enabled: true
  model: null                  # null = use default model
  max_subagents: 3
  max_iterations: 50

terminal:
  backend: local               # local | docker | ssh | modal | daytona | singularity
  docker:
    image: "ubuntu:22.04"

browser:
  record_sessions: false

checkpoints:
  enabled: true
  max_snapshots: 50

gateway:
  host: "0.0.0.0"
  port: 8642
  enabled_platforms: []        # ["telegram", "discord", ...]
  whatsapp:
    enabled: false
    mode: "self-chat"          # self-chat | any-sender
    allowed_users: []

security:
  path_restrictions: []

mcp_servers:
  my-server:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-example"]
    enabled: true

Key environment variables:

EDGECRAB_MODEL=anthropic/claude-opus-4-6
EDGECRAB_MAX_ITERATIONS=120
EDGECRAB_TERMINAL_BACKEND=docker
EDGECRAB_SKIP_MEMORY=false
EDGECRAB_SAVE_TRAJECTORIES=true

Both SDKs wrap the OpenAI-compatible HTTP API exposed by EdgeCrab's API server gateway adapter.

Python 3.10+ — async-first, streaming, CLI.

pip install edgecrab-sdk

from edgecrab import Agent

# Simple chat
agent = Agent(model="anthropic/claude-opus-4-6")
reply = agent.chat("Explain Rust ownership in 3 sentences")
print(reply)

# Async streaming
import asyncio
from edgecrab import AsyncAgent

async def main():
    agent = AsyncAgent(model="openai/gpt-4o")
    async for token in agent.stream("Write a Rust hello-world"):
        print(token, end="", flush=True)

asyncio.run(main())

Built-in CLI:

edgecrab chat "Hello, EdgeCrab!"
edgecrab models
edgecrab health

Full docs: sdks/python/README.md

Node 18+ — TypeScript-first, streaming, CLI.

npm install edgecrab-sdk

import { Agent } from 'edgecrab-sdk';

// Simple chat
const agent = new Agent({ model: 'anthropic/claude-opus-4-6' });
const reply = await agent.chat('Explain Rust ownership');
console.log(reply);

// Streaming
for await (const token of agent.stream('Write a README')) {
  process.stdout.write(token);
}

CLI via npx:

npx edgecrab-sdk chat "Hello!"
npx edgecrab-sdk models

Full docs: sdks/node/README.md

Run EdgeCrab as a gateway server in a container:

# Pull multi-arch GHCR image
docker pull ghcr.io/raphaelmansuy/edgecrab:latest

# Run gateway server
docker run -p 8642:8642 \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" \
  -v "$HOME/.edgecrab:/root/.edgecrab" \
  ghcr.io/raphaelmansuy/edgecrab:latest

# Or with docker-compose
docker compose up -d

The Docker image is multi-stage, ~50 MB (distroless final stage). Multi-arch: linux/amd64 + linux/arm64. Uses rustls-tls — no OpenSSL dependency for clean cross-compilation.

EdgeCrab imports your entire hermes-agent state in one command:

# Preview first (no changes made)
edgecrab migrate --dry-run

# Live migration
edgecrab migrate

# OpenClaw import
edgecrab claw migrate --dry-run
edgecrab claw migrate

The migrator is in crates/edgecrab-migrate/. It returns a MigrationReport with per-item MigrationStatus (Success/Skipped/Failed). Config format differences are handled automatically.

For OpenClaw, EdgeCrab imports the parts that map cleanly into EdgeCrab-native state (SOUL.md, memories, skills, selected .env keys, selected config sections) and archives unsupported OpenClaw-only config under ~/.edgecrab/migration/openclaw/ for manual review.

# Root convenience target
cargo run

# Run all unit + integration tests
cargo test --workspace

# Run only a specific crate
cargo test -p edgecrab-core
cargo test -p edgecrab-tools
cargo test -p edgecrab-gateway

# Run E2E tests (requires a configured LLM provider)
cargo test --workspace -- --include-ignored

# Lint (zero warnings policy)
cargo clippy --workspace -- -D warnings

# Format check
cargo fmt --check

# Build documentation
cargo doc --no-deps --open

Current: 1629 tests passing (unit + integration). The codebase has a zero-clippy-warnings policy enforced in CI.

Note: 8 gap-audit tests in edgecrab-cli require the hermes-agent source tree at ../hermes-agent/. Skip them when developing standalone: cargo test --workspace --exclude edgecrab-cli

edgecrab/
├── crates/
│   ├── edgecrab-types/         Shared types — Message, Role, ToolCall, errors
│   ├── edgecrab-security/      Path jail, SSRF, cmd scanner, injection, redact
│   ├── edgecrab-state/         SQLite WAL + FTS5 session store
│   ├── edgecrab-cron/          Cron parser, job store, scheduler
│   ├── edgecrab-tools/         ToolRegistry + built-in tool implementations
│   │   └── tools/
│   │       ├── file.rs         read_file, write_file, patch_file, search_files
│   │       ├── terminal.rs     terminal, manage_process
│   │       ├── web.rs          web_search, web_extract
│   │       ├── browser.rs      CDP browser automation (6 tools)
│   │       ├── memory.rs       memory_read, memory_write, Honcho tools
│   │       ├── delegate_task.rs Sub-agent delegation + batch parallelism
│   │       ├── execute_code.rs Sandboxed multi-language code execution
│   │       ├── vision.rs       vision_analyze, text_to_speech, transcribe_audio
│   │       └── ...             session, cron, checkpoint, skills, mcp, todo, HA
│   ├── edgecrab-lsp/           LSP client, document sync, diagnostics, semantic edits
│   ├── edgecrab-core/
│   │   └── src/
│   │       ├── agent.rs        AgentBuilder, Agent, StreamEvent, fork_isolated
│   │       ├── conversation.rs execute_loop() — the ReAct engine
│   │       ├── compression.rs  Context window compression
│   │       ├── prompt_builder.rs System prompt assembly from 9+ sources
│   │       ├── model_router.rs Smart routing (cheap vs full model)
│   │       └── model_catalog.rs 200+ models, user-overridable YAML
│   ├── edgecrab-cli/           ratatui TUI, slash commands, skin engine, profiles
│   ├── edgecrab-gateway/       axum + 15 platform adapters, streaming delivery
│   ├── edgecrab-acp/           ACP JSON-RPC 2.0 stdio adapter
│   └── edgecrab-migrate/       hermes-agent import + schema migrations
├── sdks/
│   ├── python/                 Python SDK (edgecrab-sdk on PyPI)
│   └── node/                   Node.js SDK (edgecrab-sdk on npm)
├── site/                       Astro documentation website
├── docs/                       Specification documents
├── acp_registry/
│   └── agent.json              VS Code Copilot agent manifest
├── .github/workflows/          CI + 4 release workflows (Rust/Python/Node/Docker)
├── Dockerfile                  Multi-stage, distroless, multi-arch
└── docker-compose.yml          One-command gateway deployment

# Debug build (fast iteration)
cargo build --workspace

# Release build (optimized, ~3× faster startup than debug)
cargo build --workspace --release

# Cross-compile for Linux on macOS
cargo build --release --target x86_64-unknown-linux-musl

The release binary is statically linked — no OpenSSL, no libc versions to worry about. Drop it on any Linux box and it runs.

EdgeCrab welcomes contributions. The codebase has a zero-clippy-warnings policy and enforces cargo fmt.

git clone https://github.com/raphaelmansuy/edgecrab
cd edgecrab
cargo build --workspace                    # verify it compiles
cargo test --workspace                     # run test suite
cargo clippy --workspace -- -D warnings    # must be warning-free

Adding a new tool:

1. Create crates/edgecrab-tools/src/tools/my_tool.rs
2. Implement the ToolHandler trait (name, schema, execute, toolset, emoji)
3. Register with inventory::submit!(RegisteredTool { handler: &MyTool })
4. Declare in crates/edgecrab-tools/src/tools/mod.rs

Adding a new gateway:

1. Create crates/edgecrab-gateway/src/my_platform.rs
2. Implement PlatformAdapter trait
3. Register in crates/edgecrab-gateway/src/run.rs

Security reporting: security@elitizon.com

See CONTRIBUTING.md for full details.

Release automation: .github/workflows/release-rust.yml, release-python.yml, release-node.yml, release-docker.yml.

Apache-2.0 — see LICENSE.

Built by Elitizon · inspired by Nous Hermes Agent and OpenClaw.