# Clawtool

> Tools. Agents. Wired. | the canonical tool layer

- **Type:** MCP server
- **Install:** `agentstack add mcp-cogitave-clawtool`
- **Verified:** Pending review
- **Seller:** [cogitave](https://agentstack.voostack.com/s/cogitave)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cogitave](https://github.com/cogitave)
- **Source:** https://github.com/cogitave/clawtool
- **Website:** https://github.com/cogitave/clawtool

## Install

```sh
agentstack add mcp-cogitave-clawtool
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/exit_code/duration_ms/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:

```bash
# 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:

```bash
# 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

```bash
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 / exit_code. | [internal/tools/core/bash_bg_tool.go](internal/tools/core/bash_bg_tool.go) |
| BashKill | SIGKILL a background Bash task's process group. | [internal/tools/core/bash_bg_tool.go](internal/tools/core/bash_bg_tool.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 + pre_commit 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/agents_tool.go](internal/tools/core/agents_tool.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](https://github.com/cogitave)
- **Source:** [cogitave/clawtool](https://github.com/cogitave/clawtool)
- **License:** MIT
- **Homepage:** https://github.com/cogitave/clawtool

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cogitave-clawtool
- Seller: https://agentstack.voostack.com/s/cogitave
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.