EdgeCrab 🦀

"Your SuperAgent — built in Rust."

License Rust crates.io PyPI npm CI Website

Changelog

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 (17 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. Runs on Linux, macOS, and Android (Termux).

Latest release: v0.10.0 — Hermes-parity terminal UX: live activity shelf with tool-progress tails, /agents delegation dashboard (kill · replay · Gantt · spawn pause), queued-message composer, /model instant hot-swap, and modular TUI overlay stack. Plus Ralph loop goals, LSP diagnostics, native web search, OpenAI proxy, and subscription OAuth.

Architecture

Architecture

hermes-agent soul  +  OpenClaw vision  =  EdgeCrab
   (reasoning)          (presence)        (Rust)
Metric EdgeCrab 🦀 hermes-agent ☤
Binary ~49 MB stripped release build Python venv + uv
Runtime bootstrap None Python + uv
Memory Workload-dependent native process ~80–150 MB
LLM providers 16 built-in varies
Messaging platforms 17 gateways 7 platforms
Tests 1629 passing (Rust) —
Migrate from hermes edgecrab migrate N/A

EdgeCrab — The Clash of the Crustaceans

Table of Contents

Why EdgeCrab?

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.

Quick Start (90 seconds)

Option A — npm (no Rust required)

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

Option B — pip (no Rust required)

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

Option C — cargo

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

Option D — build from source

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

Guided Setup Output

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

Choose LLM provider:
  [1] copilot      (GitHub Copilot — GPT-5 / Claude / Gemini catalog)  ← 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!

First Prompts

edgecrab "summarise the git log for today and open PRs"
edgecrab --model openai/gpt-5 "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

OpenAI-compatible proxy (Aider, Cline, OpenAI SDK)

Expose EdgeCrab-configured LLM providers to third-party clients — not the full agent API (distinct from the gateway api_server platform):

# Grok / xAI OAuth (recommended path)
edgecrab proxy setup grok             # writes config + token + client snippet
edgecrab proxy doctor
edgecrab proxy start --provider xai

# Or step by step
edgecrab proxy enable grok
edgecrab proxy token set
edgecrab proxy client                 # print OPENAI_API_BASE / Aider vars
edgecrab proxy start --provider xai

Point any OpenAI client at http://127.0.0.1:11434/v1 with Authorization: Bearer <proxy-token>. Map friendly names in ~/.edgecrab/config.yaml:

proxy:
  port: 11434
  model_aliases:
    claude-sonnet: anthropic/claude-sonnet-4-20250514
    gpt-4o: openai/gpt-4o
    nous-portal: forward:nous          # Mode A — credential forwarder
  forward_upstreams:
    nous:
      adapter: nous_portal          # OAuth refresh + invoke JWT (Hermes NousPortalAdapter)
      auth_provider: nous
      base_url: https://inference-api.nousresearch.com/v1
      # Or read-only: adapter: hermes_auth
      # Or static bearer: bearer_env: NOUS_API_KEY
    xai:
      adapter: xai_oauth
      auth_provider: xai-oauth
      base_url: https://api.x.ai/v1
  default_forward_upstream: nous   # optional: GET /v1/models → upstream (Hermes-style)
  cors_allow_origins: []           # e.g. ["http://localhost:3000"] for browser clients

Aider (~/.aider.conf.yml):

openai-api-base: http://127.0.0.1:11434/v1
openai-api-key: <your-proxy-token>

Default bind is loopback-only; use --allow-public only with a strong token.

What EdgeCrab Can Do

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.

ReAct Tool Loop

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.

Built-in Tools

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.

Semantic Code Intelligence (LSP)

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.

File Tools (file toolset)

Tool What it does
read_file Read file with optional start_line/end_line — path-jailed, canonicalized
write_file Write or create file (parent dirs auto-created)
patch_file Search-and-replace patch — exact string match, atomic write
search_files Regex + glob search across a directory tree

Terminal Tools (terminal toolset)

Tool What it does
terminal Execute shell command — persistent shell per task, env-var blocklist
manage_process Start/stop/list/kill/read background processes

Web Tools (web toolset)

Tool What it does
web_search Web search via Firecrawl → Tavily → Brave → DuckDuckGo fallback chain
web_extract Full-page extraction — HTML strip + PDF parse (EdgeParse) — SSRF-guarded

Browser Tools (browser toolset)

Tool What it does
browser_navigate Navigate Chrome via CDP
browser_snapshot Accessibility tree snapshot (text, not pixel)
browser_click Click element by @eN ref ID from snapshot
browser_type Type text into focused input
browser_screenshot Annotated screenshot with numbered elements
browser_console Capture/clear browser console log

Memory & Honcho Tools (memory + honcho toolsets)

Tool What it does
memory_read Read MEMORY.md and USER.md from ~/.edgecrab/memories/
memory_write Write/append to memory files (prompt-injection scanned)
honcho_profile Get/set user profile facts via Honcho cross-session model
honcho_context Retrieve contextually relevant Honcho memories for current task

Skills Tools (skills toolset)

Tool What it does
skill_manage Create, view, patch, delete, list skills

Session & Search (session toolset)

Tool What it does
session_search SQLite FTS5 full-text search across all past sessions

Delegation & MoA (delegation + moa toolsets)

Tool What it does
delegate_task Fork a sub-agent — single task or batch of up to 3 in parallel
mixture_of_agents Run task through Claude Opus 4.6, Gemini 2.5 Pro, GPT-4.1, DeepSeek R1 in parallel; synthesize consensus

Code Execution (code_execution toolset)

Tool What it does
execute_code Sandboxed Python / JS / Bash / Ruby / Perl / Rust execution with tool RPC

MCP Tools (mcp toolset)

Tool What it does
mcp_list_tools List tools exposed by all connected MCP servers
mcp_call_tool Call a named tool on any connected MCP server

Media Tools (vision / tts / transcribe toolsets)

Tool What it does
vision_analyze Analyze image via multimodal model (URL or local path)
text_to_speech Generate audio from text (OpenAI TTS or configured provider)
transcribe_audio Transcribe audio file (Whisper or Groq/OpenAI)

Automation Tools

Tool What it does
manage_todo_list Structured checklist — create, update, complete, delete items
manage_cron_jobs Schedule recurring and one-shot cron jobs
checkpoint Filesystem snapshot for rollback (create, list, restore, diff)
clarify Ask user a clarifying question (with optional choices)
send_message Send message via gateway to any connected platform
ha_get_states Fetch Home Assistant entity states
ha_call_service Call HA service (e.g. light.turn_on)
ha_trigger_automation Trigger HA automation
ha_get_history Fetch HA entity history

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

Sub-agent Delegation

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: "openai/gpt-4o"   # use a capable shared model for sub-agents
  max_subagents: 3
  max_iterations: 50

Sandboxed Code Execution

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())

Browser Automation

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.

17 Messaging Gateways

Start the gateway server and EdgeCrab becomes an always-on assistant in 17 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
Platform Transport Auth
Telegram Long-poll REST TELEGRAM_BOT_TOKEN
Discord WebSocket gateway DISCORD_BOT_TOKEN
Slack Socket Mode WebSocket SLACK_BOT_TOKEN + SLACK_APP_TOKEN
WhatsApp Baileys bridge (local Node subprocess) edgecrab whatsapp QR pairing
Signal signal-cli HTTP + SSE SIGNAL_HTTP_URL + SIGNAL_ACCOUNT
Matrix Client-Server REST + long-poll sync MATRIX_HOMESERVER + MATRIX_ACCESS_TOKEN
Mattermost REST v4 + WebSocket MATTERMOST_URL + MATTERMOST_TOKEN
DingTalk Stream SDK (no public webhook) DINGTALK_APP_KEY + DINGTALK_APP_SECRET
SMS Twilio REST v2010 TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN
Email SMTP (lettre, rustls) + inbound webhook EMAIL_PROVIDER + EMAIL_FROM + EMAIL_API_KEY
Home Assistant WebSocket + REST HASS_URL + HASS_TOKEN
Webhook axum HTTP POST any HTTP caller
API Server axum OpenAI-compatible HTTP API_SERVER_PORT (optional)
Feishu/Lark REST FEISHU_APP_ID + FEISHU_APP_SECRET
WeCom WebSocket + REST + heartbeat WECOM_BOT_ID + WECOM_SECRET
iMessage BlueBubbles REST + webhook + attachments BLUEBUBBLES_SERVER_URL + BLUEBUBBLES_PASSWORD
WeChat iLink Bot API POST-poll + AES CDN media WEIXIN_TOKEN + WEIXIN_ACCOUNT_ID

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

Persistent Memory & Learning

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 Library

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.

Skills Vs Plugins

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 ....

Plugin System

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

Cron Scheduling

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.

Checkpoints & Rollback

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 & Worktrees

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: "openai/gpt-5"
  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 .worktrees/edgecrab-<id>/ inside the current git repo
# Changes stay isolated on an ephemeral branch until you merge or discard them

You can also enable always-on worktree mode in config:

# ~/.edgecrab/config.yaml
worktree: true

Inside the TUI, /worktree opens a report overlay for t