EdgeCrab

Option B — pip (no Rust required)

```bash pip install edgecrab-cli

OR: pipx install edgecrab-cli (isolated install)

edgecrab update 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!

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:

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

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

---

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

Quick Start (90 seconds)

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" } ])

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

---

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 C — cargo

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

~/.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/config.yaml

worktree: true ```

Inside the TUI, /worktree opens a report overlay for the current checkout and saved launch policy, and /worktree on|off|toggle updates that default for future launches.

/log opens a split-pane browser for ~/.edgecrab/logs/, and Enter drills into a per-entry inspector for the selected file tail. The overlay now live-follows by default, F toggles follow mode, and 1-5 or /log level <error|warn|info|debug|trace> persist the default log verbosity in config.yaml; the current process reloads its filter immediately when runtime log reloading is available.

Cleanup is conservative by design: EdgeCrab removes clean disposable worktrees on exit, but keeps worktrees that contain unpushed commits so the agent cannot silently destroy branch-local work.

---

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

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

---

Configuration

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

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

```bash

All CLI Commands

```bash

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:

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

MCP Server Integration

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

```yaml

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>

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

---

ACP / VS Code Copilot Integration

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

---