Clawtool

clawtool

[](https://github.com/cogitave/clawtool/releases/latest) [](https://github.com/cogitave/clawtool/actions/workflows/ci.yml) [](https://github.com/cogitave/clawtool/actions/workflows/release.yml) [](go.mod) [](LICENSE) [](https://www.conventionalcommits.org)

> Tools. Agents. Wired. > > One canonical tool layer for every AI coding agent. Install once, use everywhere — across Claude Code, Codex, Gemini, OpenCode, Hermes, and Aider.

TL;DR — why would I install this?

You probably already have one or more AI coding agents on your machine: Claude Code, Codex, Gemini CLI, OpenCode, Hermes, Aider. Each one ships its own slightly-different Bash tool, slightly-different Read/Edit/Write, its own MCP server list, its own sandbox story, its own way of "calling another agent". They don't share state, they don't share secrets, and adding a new tool means re-registering it everywhere.

clawtool collapses that. One binary runs as a long-lived daemon. Every host CLI is wired to it as an MCP server (Claude Code via plugin, codex/gemini/opencode via mcp add). After that:

• Bash, Read, Edit, Write, Grep, Glob, WebFetch, WebSearch are the same tool with the same behavior in every host (timeout-safe, structured JSON, format-aware reads — PDF / Word / Excel / Jupyter / HTML).
• SendMessage lets any agent dispatch work to any other agent (claude → codex, codex → gemini, etc.) — async via the BIAM protocol with Ed25519-signed envelopes, edge-triggered fan-in, and a SQLite task store you can clawtool task list from a normal terminal.
• A single sandbox profile (bwrap / sandbox-exec / docker / gVisor) governs every tool call, regardless of which agent triggered it.
• Secrets live in one mode-0600 file, not scattered through five different ~/.config// directories.
• A 60-tool catalog stays usable because models bind to schemas through ToolSearch (BM25) on demand.

One install, one daemon, one identity, one tool surface — across every agent. That's the whole pitch.

What clawtool is

• Canonical core tools. Higher-quality replacements for native Bash, Read, Edit, Write, Grep, Glob, WebFetch — timeout-safe with process-group SIGKILL, structured JSON output (stdout/stderr/exitcode/durationms/timed_out/cwd), format-aware reads (PDF, Word, Excel, HTML, Jupyter), atomic writes, deterministic line cursors. Cross-platform parity (Linux, macOS, WSL2).
• Multi-agent dispatch. A single SendMessage entry point routes prompts to Claude, Codex, Gemini, OpenCode, Hermes, or Aider (six BIAM peers). Async via the BIAM (Bidirectional Inter-Agent Messaging) protocol — Ed25519-signed envelopes, SQLite task store, edge-triggered TaskNotify fan-in. Per-instance secrets injection, per-call sandbox profiles, true async (--async returns immediately; clawtool task cancel aborts).
• Peer mesh (A2A Phase 1). Live discovery + messaging across every claude-code / codex / gemini / opencode session on the host. Each runtime auto-registers via session hooks; the orchestrator TUI's Peers tab shows the live roster. clawtool peer send "..." and clawtool peer send --broadcast "..." deliver inbox messages between sessions — three independent transports (CLI, raw HTTP, MCP) all backed by the same daemon registry. Wire shape mirrors Linux Foundation A2A's Agent Card.
• Sandbox parity with claude.ai. Bash/Read/Edit/Write tool calls can route through a separate gVisor/docker container instead of the host process. The clawtool sandbox-worker binary mirrors claude.ai's process_api (PID 1, WebSocket :2024, bearer auth). The clawtool egress proxy mirrors claude.ai's allowlist gateway (HTTP/HTTPS, CONNECT tunnel, 403 with x-deny-reason). On-demand skill mount via SkillList + SkillLoad MCP tools mirrors /mnt/skills/public.
• Shared MCP fan-in. A single persistent clawtool serve --listen --mcp-http daemon backs every host; codex / gemini / claude all dial it instead of spawning per-host stdio children. One BIAM identity, one task store, one bearer-auth'd endpoint.
• One orchestrator TUI. clawtool orch (aliases: dashboard, tui, orchestrator) opens a Bubble Tea panel with three sidebar tabs — Active dispatches · Done dispatches · Peers — over the same watch socket. --plain / --once modes print stdout snapshots for chat-visible monitoring.
• Search-first discovery. The 60-tool catalog stays usable because models bind to schemas via ToolSearch (bleve BM25) instead of holding every JSON schema in context.
• Marketplace plugin. First-class Claude Code plugin: claude plugin install clawtool@clawtool-marketplace registers the MCP server, drops slash commands, and loads the routing skill — no manual claude mcp add-json editing.

Quick install

Pick the path that matches your primary agent:

# 1) Claude Code primary user — use the marketplace plugin.
#    Registers the MCP server, drops slash commands, loads the routing skill.
claude plugin marketplace add cogitave/clawtool
claude plugin install clawtool@clawtool-marketplace

# 2) Codex / Gemini / OpenCode / Hermes primary user (or all of the above)
#    — install the standalone binary; the onboard wizard claims each host.
curl -sSL https://raw.githubusercontent.com/cogitave/clawtool/main/install.sh | sh

# 3) Building from source
go install github.com/cogitave/clawtool/cmd/clawtool@latest

Setting up with Hermes

Hermes (NousResearch's hermes-agent) doesn't ship a hermes mcp add subcommand, so clawtool edits Hermes's ~/.hermes/config.yaml directly to wire both directions of the bridge:

# Inbound: register clawtool as Hermes's MCP server.
# Writes an mcp_servers.clawtool entry referencing the local binary.
clawtool bridge add hermes

# Outbound replacement: turn off Hermes's native Bash/Read/Edit/Write/Grep/
# Glob/WebFetch/WebSearch so the model only sees mcp__clawtool__* tools.
clawtool agents claim hermes

# Reverse both at any time:
clawtool agents release hermes
clawtool bridge remove hermes

Both commands are idempotent (run twice = same state) and surgical (your other YAML keys round-trip unchanged). clawtool agents status hermes shows what's currently disabled.

The install.sh script:

• detects your OS / arch (linux+darwin × amd64+arm64), downloads the matching tarball, verifies SHA-256 against the published checksums.txt, and atomically installs to ~/.local/bin/clawtool (override with CLAWTOOL_INSTALL_DIR);
• when run interactively (TTY), auto-launches clawtool onboard immediately after install — no extra prompt to dismiss; the wizard runs the moment the binary lands. curl|sh / CI / Docker layers skip auto-launch automatically (no TTY); set CLAWTOOL_NO_ONBOARD=1 to opt out elsewhere;
• is safe to re-run; it doubles as an upgrade path. (You can also self-update with clawtool upgrade — atomic binary replacement, signed release.)

First run — what to expect

clawtool                    # no-args lands you in a friendly TUI menu;
                            # if you haven't onboarded yet, it pre-selects
                            # the wizard and tells you so.
clawtool onboard            # interactive wizard — runs in ~30 seconds
clawtool overview           # one-screen status of daemon + sandbox-worker + agents + bridges
clawtool doctor             # deep diagnostic with fix hints per finding
clawtool send --list        # lists every callable agent the daemon can dispatch to
clawtool task list --active # see in-flight BIAM dispatches across all hosts
clawtool dashboard          # live Bubble Tea TUI — tasks, frames, system events
clawtool orchestrator       # split-pane TUI for watching multiple async dispatches

What the onboard wizard does (one-time, takes about 30 seconds):

1. Detects host CLIs on $PATH (claude / codex / gemini / opencode / hermes).
2. Asks which CLI you'll mostly drive clawtool through — that answer pre-selects defaults for the next two steps.
3. Offers to install missing bridges (Claude Code marketplace plugins for codex / gemini, binary check for opencode / hermes). Bridges are how clawtool fans SendMessage calls out to the right CLI.
4. Registers clawtool as an MCP server in every detected host (mcp add for codex / gemini / opencode) — every host dials one shared daemon instead of spawning per-host stdio children. This is the fan-in.
5. Starts the long-running daemon (clawtool daemon start) so cross-session memory + dispatch survive shell restarts.
6. Generates a BIAM identity (Ed25519 keypair, mode 0600) for signed multi-agent messaging.
7. Drops a 0600 secrets.toml stub so per-source API keys have a place to land.
8. Records telemetry consent (opt-in only — disabled by default).
9. Writes an ~/.config/clawtool/.onboarded marker so future sessions know setup is done.

Once onboarded, both Claude Code's SessionStart hook and the no-args TUI stay quiet about setup; if the marker is missing, both surfaces nudge you back to clawtool onboard — you'll never wonder why the agents can't see clawtool's tools yet.

Common questions

• "Do I have to install the binary if I only use Claude Code?" No — the marketplace plugin is enough for Claude Code. You'd only want the binary too if you also use codex / gemini / opencode and want the shared daemon, or if you want the clawtool CLI on your terminal.
• "What writes my MCP config?" clawtool onboard shells out to each host's own mcp add command — it doesn't poke at config files behind your back. You can audit / remove with the host's own tools (claude mcp list, codex mcp list, …).
• "Where does state live?" Everything is under ~/.config/clawtool/ (config, secrets, identity, daemon state) and ~/.local/share/clawtool/ (BIAM SQLite store) by default. Honors XDG_CONFIG_HOME / XDG_DATA_HOME. See the [Configuration](#configuration) table below.
• "Is the daemon always running?" Only after onboard. It's a normal user-process (not a system service); clawtool daemon stop kills it cleanly. It auto-restarts when a host MCP call comes in (daemon.Ensure).
• "How do I update?" clawtool upgrade does a signed self-replacement. New releases also push a system notification through the daemon, so any host with clawtool wired in will surface a "vX → vY available" banner without you having to check.

Architecture

hosts (claude / codex / gemini / opencode / hermes / aider)
    │  MCP — stdio (Claude Code) or HTTP (codex/gemini via `mcp add --url`)
    ▼
clawtool serve --listen --mcp-http (the daemon)
    │  bearer auth, WebSocket fan-in
    │
    ├── core tools (Bash, Read, Edit, Write, Grep, Glob, WebFetch, …)
    ├── BIAM dispatch + TaskNotify fan-in (Ed25519, SQLite)
    ├── secrets injection (per-instance API keys)
    ├── sandbox profiles (bwrap / sandbox-exec / docker)
    ├── portals (saved web-UI targets)
    ├── aggregated MCP source servers (github, slack, postgres, …)
    │
    └── (optional) sandbox-worker fan-out
        │  WebSocket dial, bearer auth
        ▼
        clawtool sandbox-worker (in a gVisor / docker container)
            ├── exec / read / write / glob / grep handlers
            ├── /workspace mount + path-jail (host paths invisible)
            └── HTTP_PROXY → clawtool egress (allowlist; 403 deny)

The asymmetry that matters: the orchestrator dials the worker, not the reverse. clawtool's daemon owns connection lifetimes for both legs — hosts dial the daemon, the daemon dials the worker. This is the canonical sandbox shape every claude.ai-style mimic converges on.

The project adheres to a four-plane shipping contract ([docs/feature-shipping-contract.md](docs/feature-shipping-contract.md)) — every new feature or tool must land on the MCP plane (core logic + registration), the marketplace plane (slash commands + manifest), the skill plane (SKILL.md routing-map row), and the surface-drift test allowlist (or get a real backing tool). The TestSurfaceDrift_* test family enforces this at CI time.

What's in the box

Core tools

| Tool | Capability | Reference | |---|---|---| | Bash | Shell exec; timeout-safe via process-group SIGKILL; structured JSON; background=true for async via BashOutput / BashKill. | [internal/tools/core/bash.go](internal/tools/core/bash.go) | | BashOutput | Snapshot of a background Bash task — live stdout / stderr / status / exitcode. | [internal/tools/core/bashbgtool.go](internal/tools/core/bashbgtool.go) | | BashKill | SIGKILL a background Bash task's process group. | [internal/tools/core/bashbgtool.go](internal/tools/core/bashbgtool.go) | | Read | Format-aware (PDF / docx / xlsx / csv / html / ipynb / json / yaml / toml / xml); deterministic line cursors; binary refusal. | [internal/tools/core/read.go](internal/tools/core/read.go) | | Edit | Atomic temp+rename; line-ending and BOM preserve; ambiguity guard. | [internal/tools/core/edit.go](internal/tools/core/edit.go) | | Write | Atomic write; auto-create parents; Read-before-Write enforcement. | [internal/tools/core/write.go](internal/tools/core/write.go) | | Grep | ripgrep first, system grep fallback; .gitignore-aware; multi-pattern. | [internal/tools/core/grep.go](internal/tools/core/grep.go) | | Glob | doublestar ** recursion; .gitignore-aware (toggleable); cross-platform forward-slash output. | [internal/tools/core/glob.go](internal/tools/core/glob.go) | | WebFetch | URL → clean article text via Mozilla Readability; SSRF guard; 10 MiB cap. | [internal/tools/core/webfetch.go](internal/tools/core/webfetch.go) | | WebSearch | Pluggable backend (Brave / Tavily / SearXNG); secrets-managed API key. | [internal/tools/core/websearch.go](internal/tools/core/websearch.go) | | ToolSearch | bleve BM25 ranking across the loaded catalog. | [internal/tools/core/toolsearch.go](internal/tools/core/toolsearch.go) | | SemanticSearch | Vector embeddings; lazy index. | [internal/tools/core/semanticsearch.go](internal/tools/core/semanticsearch.go) | | Verify | Multi-runner test/lint (Make / pnpm / go / pytest / cargo / just) with log excerpting. | [internal/tools/core/verify.go](internal/tools/core/verify.go) | | Commit | Git commit with Conventional Commits validation + Co-Authored-By block + precommit rules gate. | [internal/checkpoint/commit.go](internal/checkpoint/commit.go) |

Multi-agent dispatch

| Tool | Capability | Reference | |---|---|---| | SendMessage | Forward prompts to claude / codex / gemini / opencode / hermes / aider. --async for BIAM, --unattended injects the host's elevation flag (claude --dangerously-skip-permissions, codex --dangerously-bypass-approvals-and-sandbox, gemini/opencode/hermes --yolo, aider --yes). | [internal/agents/supervisor.go](internal/agents/supervisor.go) | | AgentList | Snapshot of the supervisor's agent registry. | [internal/tools/core/agentstool.go](internal/tools/core/agentstool.go) | | TaskGet · TaskWait · TaskList · TaskNotify | BIAM task introspection + edge-triggered fan-in completion. | [internal/agents/biam](internal/agents/biam) |

Peer mesh (A2A)

The runtime-side primitive is clawtool peer: every claude-code / codex / gemini / opencode session that ships clawtool's bundled hooks auto-registers itself in the daemon's peer registry, so multiple parallel sessions can discover each other and exchange notifications without spawning extra MCP servers.

| Surface | Capability | Reference | |---|---|---| | clawtool a2a card · clawtool a2a peers | Emit this instance's A2A Agent Card; list every registered peer with status / backend / circle filters. | [internal/cli/a2a.go](internal/cli/a2a.go) | | clawtool peer register / heartbeat / deregister | Runtime-side primitives bundled hooks fire on SessionStart / Stop / SessionEnd. Session-keyed peer-id state at ~/.config/clawtool/peers.d/.id. | [internal/cli/peer.go](internal/cli/peer.go) | | clawtool peer send "" | Enqueue notifi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cogitave
• Source: cogitave/clawtool
• License: MIT
• Homepage: https://github.com/cogitave/clawtool

Install and usage instructions live in the source repository linked above.