clawtool

clawtool

Tools. Agents. Wired.

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

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, or Hermes. 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).
• 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.
• Search-first discovery. A 50+ 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

# Claude Code marketplace path (recommended)
claude plugin marketplace add cogitave/clawtool
claude plugin install clawtool@clawtool-marketplace

# Or direct binary install
curl -sSL https://raw.githubusercontent.com/cogitave/clawtool/main/install.sh | sh

# Or from source
go install github.com/cogitave/clawtool/cmd/clawtool@latest

Onboarding

clawtool onboard            # interactive wizard — host detection, MCP claims, identity, telemetry consent
clawtool overview           # one-screen status of daemon + sandbox-worker + agents + bridges
clawtool doctor             # full diagnostic with fix hints per finding

The wizard:

1. Detects host CLIs (claude / codex / gemini / opencode / hermes).
2. Offers to install missing bridges (Claude Code marketplace plugins for codex / gemini, binary checks for opencode / hermes).
3. Registers clawtool as an MCP server in every detected host (codex / gemini / opencode) — points each at the persistent shared daemon. This is the fan-in step: every host dials one daemon, not a per-host stdio child.
4. Generates a BIAM identity (Ed25519 keypair, mode 0600) for clawtool send --async.
5. Records telemetry consent.
6. Optional: drops repo-level recipes via clawtool init.

Architecture

hosts (claude / codex / gemini / opencode / hermes)
    │  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. Design context: wiki/decisions/029-sandbox-worker.md.

The project adheres to a four-plane shipping contract (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

Multi-agent dispatch

Sandbox + worker

Rules engine

Authoring scaffolders

Browser + Portal

Bridges + Recipes

Configuration

Diagnostic surfaces: clawtool overview (one-screen status), clawtool doctor (deep diagnostic with fix hints), clawtool dashboard (live Bubble Tea TUI), clawtool sandbox doctor (engine availability), clawtool source check (credential verification).

Sandbox-worker quick path

# 1. Generate the worker bearer token
clawtool sandbox-worker --init-token

# 2. Build the worker image (one-time)
docker build -f Dockerfile.worker -t clawtool-worker:0.21 .

# 3. Run the worker container
docker run --rm \
    -v "$(pwd)":/workspace \
    -p 127.0.0.1:2024:2024 \
    -v "$XDG_CONFIG_HOME/clawtool/worker-token":/etc/worker-token:ro \
    clawtool-worker:0.21 \
    sandbox-worker --token-file /etc/worker-token

# 4. (Optional) Run the egress allowlist proxy
clawtool egress --listen :3128 --allow .openai.com,.anthropic.com,.github.com &

# 5. Tell the daemon to route through the worker
cat >> ~/.config/clawtool/config.toml <<'EOF'
[sandbox_worker]
mode = "container"
url  = "ws://127.0.0.1:2024/ws"
EOF
clawtool daemon restart

After this, every Bash tool call (from any host — claude / codex / gemini) executes inside the worker container, behind the egress allowlist, with model-generated code never touching the operator's host process.

Roadmap

• Cross-host BIAM identity routing (#196) — per-call from_instance parameter on SendMessage so codex / gemini / claude can mutually notify each other through the shared daemon. Tasarım turu pending.
• Onboarding state machine (#194, ADR-027) — collapse init + onboard into one engine; per-feature opt-in matrix; verify-summary at the end (send --list, bridge list, source check, sandbox doctor).
• Task watch v2 (#185) — Unix socket push from BIAM runner to consumers; eliminates the 250ms poll.
• Orchestrator multi-pane TUI ships: clawtool orchestrator (alias orch) is a split-pane Bubble Tea TUI that auto-spawns one stdout-tail pane per active BIAM dispatch and fades panes 5 s after they hit terminal. Backed by the daemon's task-watch Unix socket — sub-50ms reaction time, no SQLite poll. clawtool dashboard also subscribes for its tasks pane. Design: ADR-028.
• Sandbox-worker phase 2 follow-up — Read/Edit/Write routing through the worker (Phase 2 covered Bash); per-conversation ephemeral workers; gVisor runsc runtime selection wired into the docker engine adapter.

Contributing

See CONTRIBUTING.md and docs/feature-shipping-contract.md. The four-plane review checklist is enforced by CI; commits append no Co-Authored-By trailer for AI agents.

License

MIT