{"id":49376041,"url":"https://github.com/cogitave/clawtool","last_synced_at":"2026-05-24T01:01:27.303Z","repository":{"id":354004260,"uuid":"1221727619","full_name":"cogitave/clawtool","owner":"cogitave","description":"Tools. Agents. Wired. | the canonical tool layer","archived":false,"fork":false,"pushed_at":"2026-05-23T19:53:59.000Z","size":3513,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T20:21:43.682Z","etag":null,"topics":["agent-dispatch","agent-supervisor","ai-coding-agent","bash","biam","canonical-tools","claude-code","claude-code-plugin","codex","gemini","golang","marketplace-plugin","mcp","mcp-server","multi-agent","opencode","sandbox","search-first","structured-output","toolset"],"latest_commit_sha":null,"homepage":"https://github.com/cogitave/clawtool","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cogitave.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T15:52:38.000Z","updated_at":"2026-05-23T19:54:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cogitave/clawtool","commit_stats":null,"previous_names":["cogitave/clawtool"],"tags_count":166,"template":false,"template_full_name":null,"purl":"pkg:github/cogitave/clawtool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogitave%2Fclawtool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogitave%2Fclawtool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogitave%2Fclawtool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogitave%2Fclawtool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cogitave","download_url":"https://codeload.github.com/cogitave/clawtool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogitave%2Fclawtool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33417489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-dispatch","agent-supervisor","ai-coding-agent","bash","biam","canonical-tools","claude-code","claude-code-plugin","codex","gemini","golang","marketplace-plugin","mcp","mcp-server","multi-agent","opencode","sandbox","search-first","structured-output","toolset"],"created_at":"2026-04-28T02:04:49.110Z","updated_at":"2026-05-24T01:01:27.258Z","avatar_url":"https://github.com/cogitave.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clawtool\n\n[![Latest release](https://img.shields.io/github/v/release/cogitave/clawtool?display_name=tag\u0026sort=semver\u0026color=blue)](https://github.com/cogitave/clawtool/releases/latest)\n[![CI](https://github.com/cogitave/clawtool/actions/workflows/ci.yml/badge.svg)](https://github.com/cogitave/clawtool/actions/workflows/ci.yml)\n[![Release](https://github.com/cogitave/clawtool/actions/workflows/release.yml/badge.svg)](https://github.com/cogitave/clawtool/actions/workflows/release.yml)\n[![Go](https://img.shields.io/github/go-mod/go-version/cogitave/clawtool?logo=go)](go.mod)\n[![License](https://img.shields.io/github/license/cogitave/clawtool?color=brightgreen)](LICENSE)\n[![Conventional Commits](https://img.shields.io/badge/conventional--commits-1.0.0-yellow)](https://www.conventionalcommits.org)\n\n\u003e **Tools. Agents. Wired.**\n\u003e\n\u003e One canonical tool layer for every AI coding agent. Install once, use everywhere — across Claude Code, Codex, Gemini, OpenCode, Hermes, and Aider.\n\n## TL;DR — why would I install this?\n\nYou 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.\n\nclawtool 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:\n\n- `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).\n- `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.\n- A single sandbox profile (bwrap / sandbox-exec / docker / gVisor) governs every tool call, regardless of which agent triggered it.\n- Secrets live in one mode-0600 file, not scattered through five different `~/.config/\u003chost\u003e/` directories.\n- A 60-tool catalog stays usable because models bind to schemas through `ToolSearch` (BM25) on demand.\n\n**One install, one daemon, one identity, one tool surface — across every agent.** That's the whole pitch.\n\n## What clawtool is\n\n- **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).\n- **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).\n- **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 \u003cname\u003e \"...\"` 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.\n- **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`.\n- **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.\n- **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.\n- **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.\n- **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.\n\n## Quick install\n\nPick the path that matches your primary agent:\n\n```bash\n# 1) Claude Code primary user — use the marketplace plugin.\n#    Registers the MCP server, drops slash commands, loads the routing skill.\nclaude plugin marketplace add cogitave/clawtool\nclaude plugin install clawtool@clawtool-marketplace\n\n# 2) Codex / Gemini / OpenCode / Hermes primary user (or all of the above)\n#    — install the standalone binary; the onboard wizard claims each host.\ncurl -sSL https://raw.githubusercontent.com/cogitave/clawtool/main/install.sh | sh\n\n# 3) Building from source\ngo install github.com/cogitave/clawtool/cmd/clawtool@latest\n```\n\n### Setting up with Hermes\n\nHermes (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:\n\n```bash\n# Inbound: register clawtool as Hermes's MCP server.\n# Writes an mcp_servers.clawtool entry referencing the local binary.\nclawtool bridge add hermes\n\n# Outbound replacement: turn off Hermes's native Bash/Read/Edit/Write/Grep/\n# Glob/WebFetch/WebSearch so the model only sees mcp__clawtool__* tools.\nclawtool agents claim hermes\n\n# Reverse both at any time:\nclawtool agents release hermes\nclawtool bridge remove hermes\n```\n\nBoth 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.\n\nThe `install.sh` script:\n\n- 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`);\n- 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;\n- is safe to re-run; it doubles as an upgrade path. (You can also self-update with `clawtool upgrade` — atomic binary replacement, signed release.)\n\n## First run — what to expect\n\n```bash\nclawtool                    # no-args lands you in a friendly TUI menu;\n                            # if you haven't onboarded yet, it pre-selects\n                            # the wizard and tells you so.\nclawtool onboard            # interactive wizard — runs in ~30 seconds\nclawtool overview           # one-screen status of daemon + sandbox-worker + agents + bridges\nclawtool doctor             # deep diagnostic with fix hints per finding\nclawtool send --list        # lists every callable agent the daemon can dispatch to\nclawtool task list --active # see in-flight BIAM dispatches across all hosts\nclawtool dashboard          # live Bubble Tea TUI — tasks, frames, system events\nclawtool orchestrator       # split-pane TUI for watching multiple async dispatches\n```\n\nWhat the **onboard wizard** does (one-time, takes about 30 seconds):\n\n1. Detects host CLIs on `$PATH` (claude / codex / gemini / opencode / hermes).\n2. Asks **which CLI you'll mostly drive clawtool through** — that answer pre-selects defaults for the next two steps.\n3. 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.\n4. **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.\n5. Starts the long-running daemon (`clawtool daemon start`) so cross-session memory + dispatch survive shell restarts.\n6. Generates a BIAM identity (Ed25519 keypair, mode 0600) for signed multi-agent messaging.\n7. Drops a 0600 `secrets.toml` stub so per-source API keys have a place to land.\n8. Records telemetry consent (opt-in only — disabled by default).\n9. Writes an `~/.config/clawtool/.onboarded` marker so future sessions know setup is done.\n\nOnce 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.\n\n### Common questions\n\n- **\"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.\n- **\"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`, …).\n- **\"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.\n- **\"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`).\n- **\"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.\n\n## Architecture\n\n```\nhosts (claude / codex / gemini / opencode / hermes / aider)\n    │  MCP — stdio (Claude Code) or HTTP (codex/gemini via `mcp add --url`)\n    ▼\nclawtool serve --listen --mcp-http (the daemon)\n    │  bearer auth, WebSocket fan-in\n    │\n    ├── core tools (Bash, Read, Edit, Write, Grep, Glob, WebFetch, …)\n    ├── BIAM dispatch + TaskNotify fan-in (Ed25519, SQLite)\n    ├── secrets injection (per-instance API keys)\n    ├── sandbox profiles (bwrap / sandbox-exec / docker)\n    ├── portals (saved web-UI targets)\n    ├── aggregated MCP source servers (github, slack, postgres, …)\n    │\n    └── (optional) sandbox-worker fan-out\n        │  WebSocket dial, bearer auth\n        ▼\n        clawtool sandbox-worker (in a gVisor / docker container)\n            ├── exec / read / write / glob / grep handlers\n            ├── /workspace mount + path-jail (host paths invisible)\n            └── HTTP_PROXY → clawtool egress (allowlist; 403 deny)\n```\n\nThe 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.\n\nThe 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.\n\n## What's in the box\n\n### Core tools\n\n| Tool | Capability | Reference |\n|---|---|---|\n| 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) |\n| 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) |\n| BashKill | SIGKILL a background Bash task's process group. | [internal/tools/core/bash_bg_tool.go](internal/tools/core/bash_bg_tool.go) |\n| 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) |\n| Edit | Atomic temp+rename; line-ending and BOM preserve; ambiguity guard. | [internal/tools/core/edit.go](internal/tools/core/edit.go) |\n| Write | Atomic write; auto-create parents; Read-before-Write enforcement. | [internal/tools/core/write.go](internal/tools/core/write.go) |\n| Grep | ripgrep first, system grep fallback; .gitignore-aware; multi-pattern. | [internal/tools/core/grep.go](internal/tools/core/grep.go) |\n| Glob | doublestar `**` recursion; .gitignore-aware (toggleable); cross-platform forward-slash output. | [internal/tools/core/glob.go](internal/tools/core/glob.go) |\n| WebFetch | URL → clean article text via Mozilla Readability; SSRF guard; 10 MiB cap. | [internal/tools/core/webfetch.go](internal/tools/core/webfetch.go) |\n| WebSearch | Pluggable backend (Brave / Tavily / SearXNG); secrets-managed API key. | [internal/tools/core/websearch.go](internal/tools/core/websearch.go) |\n| ToolSearch | bleve BM25 ranking across the loaded catalog. | [internal/tools/core/toolsearch.go](internal/tools/core/toolsearch.go) |\n| SemanticSearch | Vector embeddings; lazy index. | [internal/tools/core/semanticsearch.go](internal/tools/core/semanticsearch.go) |\n| Verify | Multi-runner test/lint (Make / pnpm / go / pytest / cargo / just) with log excerpting. | [internal/tools/core/verify.go](internal/tools/core/verify.go) |\n| Commit | Git commit with Conventional Commits validation + Co-Authored-By block + pre_commit rules gate. | [internal/checkpoint/commit.go](internal/checkpoint/commit.go) |\n\n### Multi-agent dispatch\n\n| Tool | Capability | Reference |\n|---|---|---|\n| 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) |\n| AgentList | Snapshot of the supervisor's agent registry. | [internal/tools/core/agents_tool.go](internal/tools/core/agents_tool.go) |\n| TaskGet · TaskWait · TaskList · TaskNotify | BIAM task introspection + edge-triggered fan-in completion. | [internal/agents/biam](internal/agents/biam) |\n\n### Peer mesh (A2A)\n\nThe 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.\n\n| Surface | Capability | Reference |\n|---|---|---|\n| `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) |\n| `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/\u003csession\u003e.id`. | [internal/cli/peer.go](internal/cli/peer.go) |\n| `clawtool peer send \u003cpeer_id\\|--name N\\|--broadcast\u003e \"\u003ctext\u003e\"` | Enqueue notification / broadcast into the target peer's inbox. | [internal/cli/peer.go](internal/cli/peer.go) |\n| `clawtool peer inbox [--peek]` | Drain (or peek) the calling session's pending messages. | [internal/cli/peer.go](internal/cli/peer.go) |\n| `clawtool hooks install \u003cruntime\u003e` | Print the wiring snippet for codex / gemini / opencode (claude-code is bundled). | [internal/cli/hooks.go](internal/cli/hooks.go) |\n| `GET /v1/peers` · `POST /v1/peers/register` · `POST /v1/peers/{id}/messages` · `POST /v1/peers/broadcast` | Bearer-authed REST surface; persisted at `~/.config/clawtool/peers.json` + per-peer inbox files at `peers.d/`. | [internal/server/peers_handler.go](internal/server/peers_handler.go) · [internal/a2a](internal/a2a) |\n\n### Sandbox + worker\n\n| Surface | Capability | Reference |\n|---|---|---|\n| `clawtool serve --listen --mcp-http` | The persistent shared daemon. Bearer-auth WebSocket; hosts dial it. | [internal/server/http.go](internal/server/http.go) |\n| `clawtool daemon start \\| stop \\| status \\| restart \\| path \\| url` | Lifecycle of the persistent daemon. State at `~/.config/clawtool/daemon.json`. | [internal/daemon/daemon.go](internal/daemon/daemon.go) |\n| `clawtool sandbox-worker --listen :2024` | Worker process inside a docker / runsc container. WebSocket :2024, bearer auth, /workspace mount, path-jail. | [internal/sandbox/worker](internal/sandbox/worker) |\n| `clawtool egress --listen :3128 --allow ...` | HTTP/HTTPS allowlist proxy with CONNECT tunnel. 403 with `x-deny-reason`. | [internal/sandbox/egress](internal/sandbox/egress) |\n| Sandbox profiles | bwrap / sandbox-exec / docker engines. Fail-closed when profile policy can't be enforced. | [internal/sandbox](internal/sandbox) |\n\n### Rules engine\n\n| Tool | Capability | Reference |\n|---|---|---|\n| RulesCheck | Evaluate `.clawtool/rules.toml` against a Context (event + changed paths + commit message + tool calls). Returns Verdict per rule. | [docs/rules.md](docs/rules.md) · [internal/rules](internal/rules) |\n| RulesAdd | Append a rule to local or user rules.toml — same writer the CLI uses. | [internal/tools/core/rules_add_tool.go](internal/tools/core/rules_add_tool.go) |\n\n### Authoring scaffolders\n\n| Tool | Capability | Reference |\n|---|---|---|\n| AgentNew | Scaffold a Claude Code subagent persona. | [internal/agentgen](internal/agentgen) |\n| SkillNew | Generate an agentskills.io-standard skill folder. | [internal/skillgen](internal/skillgen) |\n| SkillList · SkillLoad | On-demand skill discovery + content load (claude.ai `/mnt/skills/public` mimic). | [internal/tools/core/skill_load_tool.go](internal/tools/core/skill_load_tool.go) |\n| McpList / McpNew / McpRun / McpBuild / McpInstall | MCP server scaffolder, runner, builder, installer (Go / Python / TypeScript). | [internal/mcpgen](internal/mcpgen) |\n\n### Browser + Portal\n\n| Tool | Capability | Reference |\n|---|---|---|\n| BrowserFetch · BrowserScrape | Headless browser via Obscura (CDP). | [internal/portal](internal/portal) |\n| Portal* | Saved web-UI targets — `PortalAsk` drives login flow → predicate → response extraction. | [internal/portal](internal/portal) |\n\n### Bridges + Recipes\n\n| Tool | Capability | Reference |\n|---|---|---|\n| BridgeList · BridgeAdd · BridgeRemove · BridgeUpgrade | Install canonical bridges (codex-plugin-cc, gemini-plugin-cc, opencode acp, hermes-agent). | [internal/setup/recipes/bridges](internal/setup/recipes/bridges) |\n| RecipeList · RecipeStatus · RecipeApply | Project-setup recipes (license / codeowners / dependabot / release-please / brain / etc.). | [internal/setup](internal/setup) |\n\nThe recipe catalog spans nine categories (governance / commits / release / ci / quality / supply-chain / knowledge / agents / runtime). Highlights beyond the basics: `mattpocock-skills`, `karpathy-llm-wiki`, `archon-template`, `bifrost-template`, `mcp-toolbox`, `semble`, `shell-mcp`, `clawtool-autonomous-loop`, `promptfoo-redteam`, `rtk-token-filter`, `mem0`, `superclaude`, `claude-flow`, `caveman`, `clawtool-relay`. Run `clawtool recipe list` for the full state matrix; `clawtool init --all` applies every Core-tagged recipe non-interactively (paired with `--summary-json` for scripted / chat-driven runs).\n\n### Source catalog\n\n`clawtool source catalog` lists all 19 built-in MCP source entries. As of v0.22.74:\n\n- **Reference servers** (anthropic-maintained): github, slack, postgres, sqlite, filesystem, fetch, brave-search, google-maps, memory, sequentialthinking, time, git.\n- **Productivity**: atlassian (Jira + Confluence), notion, exa (neural web search), context7 (live docs), playwright, desktop-commander.\n- **Database / search**: mcp-toolbox (Google's reference DB MCP — Postgres / MySQL / SQLite / BigQuery / Mongo / Redis / Spanner), semble (~98% fewer tokens than grep+read), shell-mcp (sandbox-aware shell execution).\n\n### Chat-driven setup\n\nclawtool exposes four MCP tools so an operator can drive the entire install-and-configure pipeline from a single chat message instead of context-switching to the CLI:\n\n| Tool | Capability | Reference |\n|---|---|---|\n| OnboardStatus | Read-only JSON: detected hosts, installed bridges, secrets readiness, daemon state. | [internal/tools/setup/onboard_status.go](internal/tools/setup/onboard_status.go) |\n| OnboardWizard | Runs `clawtool onboard --yes` end-to-end with per-step telemetry mirrored back to the model. | [internal/tools/setup/onboard_wizard.go](internal/tools/setup/onboard_wizard.go) |\n| InitApply | Applies recipes in the current repo (mirrors `clawtool init --all`); returns the `--summary-json` document. | [internal/tools/setup/init_apply.go](internal/tools/setup/init_apply.go) |\n| AutonomousRun | Kicks off `clawtool autonomous \"\u003cgoal\u003e\"` and streams `tick-N.json` writes back as task frames. | [internal/tools/setup/autonomous_run.go](internal/tools/setup/autonomous_run.go) |\n\nCompose them as **one message, full pipeline**: detect → onboard → init → autonomous loop, no shell context-switch.\n\n### Autonomous mode\n\n```bash\nclawtool autonomous \"Refactor the BIAM runner to use a fan-out scheduler\"\nclawtool autonomous --resume .clawtool/autonomous/final.json\nclawtool autonomous --watch ./repo\n```\n\nThe CLI builds a session prompt from the goal + iteration metadata, dispatches it to the chosen BIAM peer (default: claude), and ends when the agent emits `done: true` in `\u003cworkdir\u003e/.clawtool/autonomous/tick-N.json`, `--max-iterations` is hit, or the operator sends SIGINT. `--resume` continues a prior run from its `final.json`; `--watch` tails an existing run's tick stream into the terminal. Pair with `OnboardStatus` + `InitApply` (above) for the \"tek mesaj, tüm pipeline\" loop.\n\n### Self-direction stack — Ideator → Autopilot → Autonomous\n\nThree layers, one per question. Ideator surveys cheap repo-local signals and proposes work; Autopilot is the operator-gated TOML queue that decides when each proposal becomes pending; Autonomous is the dev loop above that actually runs it. Full reference: [docs/ideator.md](docs/ideator.md).\n\n| Verb | Capability | Reference |\n|---|---|---|\n| `clawtool ideate [--apply] [--top N] [--source \u003cname\u003e]` | Eleven cheap-on-fail signal sources: `adr_questions`, `adr_drafting`, `todos`, `ci_failures`, `manifest_drift`, `bench_regression`, `deps_outdated`, `deadcode_hits`, `vuln_advisories` (govulncheck, cached on go.sum hash; drops findings already covered by the workflow `GO_VERSION` pin), `stale_files` (heuristic fallback), `pr_review_pending` (open PRs awaiting review \u003e24h, age-banded priority). Bounded source concurrency (default 4; `CLAWTOOL_IDEATOR_MAX_CONCURRENCY=N` to override on slow filesystems). | [internal/ideator](internal/ideator) · [docs/ideator.md](docs/ideator.md) |\n| `clawtool autopilot {add\\|accept\\|next\\|done\\|skip\\|list\\|status}` | TOML queue at `~/.config/clawtool/autopilot/queue.toml` with `proposed → pending → in_progress → done/skipped` flow. Ideator-emitted items land at `proposed`; the operator-gate `accept` is non-negotiable so the agent can't silently drive its own pipeline past human review. | [internal/autopilot](internal/autopilot) |\n| MCP: `IdeateRun`, `IdeateApply`, `AutopilotStatus/List/Add/Accept/Next/Done/Skip`, `AutonomousRun` | Same three layers exposed to chat agents so the loop runs without context-switching. | [internal/tools/core](internal/tools/core) |\n\n### Project setup verbs\n\n| Verb | Capability |\n|---|---|\n| `clawtool init [--all] [--summary-json] [--yes]` | Apply the per-category recipe wizard. `--all` non-interactively applies every Core recipe; `--summary-json` emits a single decodable JSON document so InitApply / chat-driven flows can parse the result. |\n| `clawtool apm import [\u003cpath\u003e] [--dry-run] [--repo \u003cp\u003e]` | Import a microsoft/apm manifest (apm.yml). MCP servers register via `clawtool source add`; skills + playbooks land in `\u003crepo\u003e/.clawtool/apm-imported-manifest.toml`. |\n| `clawtool source registry [--backend mcp\\|smithery\\|both] [--limit N]` | Probe an upstream MCP catalog (registry.modelcontextprotocol.io and/or registry.smithery.ai) read-only — discovery before adopting a new server. |\n| `clawtool source inspect \u003cinstance\u003e [--format text\\|json]` | Audit a configured source's exposed tool surface by spawning the npm-published MCP Inspector against its stdio command. |\n| `clawtool playbook list-archon [--dir \u003cp\u003e] [--format \u003ctext\\|json\u003e]` | List Archon (coleam00/Archon) DAG workflows under `.archon/workflows/`. Read-only; phase 2 will wire execution. |\n\nThe repo also ships a top-level `playbooks/` directory — a markdown layer (Zhixiang Luo's 10xProductivity-style) of agent-readable tool integration recipes that live alongside the MCP source-server layer. See [playbooks/README.md](playbooks/README.md).\n\n## Configuration\n\n| Path | Purpose |\n|---|---|\n| `~/.config/clawtool/config.toml` | Primary config (XDG). Tool toggles, sources, agents, dispatch policy, sandbox profiles, `[sandbox_worker]` block. |\n| `~/.config/clawtool/secrets.toml` | Mode-0600 credential store for API keys / OAuth tokens / DB passwords. |\n| `~/.config/clawtool/daemon.json` | Persistent daemon state (pid, port, started_at, token_file, log_file). |\n| `~/.config/clawtool/listener-token` | Bearer token shared between hosts and the daemon. Mode 0600. |\n| `~/.config/clawtool/peers.json` | A2A peer registry (live claude-code / codex / gemini / opencode sessions on this host). |\n| `~/.config/clawtool/peers.d/\u003csession\u003e.id` | Session→peer_id pointer written by `clawtool peer register`; consumed by `peer heartbeat / deregister / inbox`. |\n| `~/.config/clawtool/peers.d/\u003cpeer_uuid\u003e.inbox.json` | Per-peer mailbox (256-message soft cap) persisted from the daemon's in-memory queue. |\n| `~/.config/clawtool/worker-token` | Bearer token shared between daemon and sandbox-worker. |\n| `~/.config/clawtool/identity.ed25519` | BIAM identity keypair (mode 0600). |\n| `~/.local/share/clawtool/biam.db` | SQLite task store (Ed25519-signed envelopes, status, history). |\n| `~/.local/state/clawtool/daemon.log` | Daemon stdout/stderr log. |\n| `./.clawtool/rules.toml` | Project-scoped rules (predicate → verdict). |\n| `./.clawtool/\u003cname\u003e.toml` | Project markers (mcp / brain / etc.). |\n| `./wiki/` (gitignored) | Operator's local Obsidian vault for ADRs, source surveys, and daily logs. Cross-references the source code; never enters CI. Created by the `karpathy-llm-wiki` / `brain` recipes. |\n\nDiagnostic 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).\n\n## Sandbox-worker quick path\n\n```bash\n# 1. Generate the worker bearer token\nclawtool sandbox-worker --init-token\n\n# 2. Build the worker image (one-time). Use a moving tag — the binary inside\n#    is keyed to your local clawtool version, not a frozen 0.21 release.\ndocker build -f Dockerfile.unified --target worker -t clawtool-worker:dev .\n\n# 3. Run the worker container\ndocker run --rm \\\n    -v \"$(pwd)\":/workspace \\\n    -p 127.0.0.1:2024:2024 \\\n    -v \"$XDG_CONFIG_HOME/clawtool/worker-token\":/etc/worker-token:ro \\\n    clawtool-worker:dev \\\n    sandbox-worker --token-file /etc/worker-token\n\n# 4. (Optional) Run the egress allowlist proxy\nclawtool egress --listen :3128 --allow .openai.com,.anthropic.com,.github.com \u0026\n\n# 5. Tell the daemon to route through the worker\ncat \u003e\u003e ~/.config/clawtool/config.toml \u003c\u003c'EOF'\n[sandbox_worker]\nmode = \"container\"\nurl  = \"ws://127.0.0.1:2024/ws\"\nEOF\nclawtool daemon restart\n```\n\nAfter 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.\n\n## Recently shipped\n\n- **Self-direction stack — Ideator → Autopilot → Autonomous** (v0.22.140 → v0.22.145) — Ten cheap-on-fail signal sources (CI failures, deadcode, deps_outdated with indirect-dep filter, manifest drift, BM25 regression, ADR open questions, ADR drafting age, TODOs, govulncheck advisories with workflow-pin filter + 12h cache, stale-files heuristic) feed an operator-gated TOML autopilot queue at `proposed → pending → in_progress → done`. The autonomous loop above consumes the queue. Bounded source concurrency (default 4) keeps wall time predictable on slow filesystems; vuln_advisories cache + workflow `GO_VERSION` filter keep the loop signal-rich without ghost alarms. Full reference: [docs/ideator.md](docs/ideator.md).\n- **Autonomous mode** (v0.22.71 + v0.22.74) — `clawtool autonomous \"\u003cgoal\u003e\"` runs a self-paced single-message dev loop against the chosen BIAM peer; the agent emits `tick-N.json` after each iteration, the loop ends on `done: true`, `--max-iterations`, or SIGINT. v0.22.74 added `--resume \u003cfinal.json\u003e` to continue a prior run and `--watch \u003cworkdir\u003e` to tail an existing run's tick stream into the terminal. Sister MCP tool `AutonomousRun` (v0.22.72) streams the same loop back to a chat-driving model.\n- **Chat-driven setup MCP tools** (v0.22.62) — `OnboardStatus`, `OnboardWizard`, `InitApply` so an operator can drive detect → onboard → recipe-apply from a single chat message instead of context-switching to the CLI. `init --all` (v0.22.56) and `init --summary-json` (v0.22.60) make the wizard scriptable.\n- **Catalog growth — DB / search / shell** (v0.22.63 → v0.22.70) — `mcp-toolbox` (Google's reference DB MCP), `semble` (~98% fewer tokens than grep+read), `shell-mcp` (sandbox-aware shell execution) joined the built-in source catalog. `clawtool source registry --backend mcp|smithery|both` (v0.22.50) lets the operator probe upstream catalogs read-only; `clawtool source inspect \u003cinstance\u003e` (v0.22.52) audits a configured source's tool surface via the npm-published MCP Inspector.\n- **APM + Archon importers** (v0.22.64 + v0.22.67) — `clawtool apm import` ingests a microsoft/apm manifest (sources register via `source add`; skills + playbooks land in `.clawtool/apm-imported-manifest.toml`). `clawtool playbook list-archon` surfaces Archon DAG workflows under `.archon/workflows/` (read-only; phase 2 will wire execution).\n- **A2A Phase 1 — peer discovery + messaging** (v0.22.36) — every running claude-code / codex / gemini / opencode session registers into a shared peer registry through bundled SessionStart hooks. Three independent transports (CLI `clawtool peer send`, raw HTTP `POST /v1/peers/{id}/messages`, MCP `SendMessage`) deliver inbox messages between sessions; `clawtool a2a peers` and the orchestrator TUI's new Peers tab show the live roster. Status-fidelity hooks flip peers between `busy` (UserPromptSubmit) and `online` (Notification idle_prompt) so operators see actual activity, not just registration timestamps.\n- **Single TUI, four aliases** (v0.22.36) — `clawtool dashboard`, `tui`, `orchestrator`, `orch` all open the same Bubble Tea program. The legacy parallel dashboard implementation was retired; one window, three tabs (Active · Done · Peers), shared watch-socket reconnect policy. `--plain` / `--once` snapshot mode kept for chat-visible monitoring.\n- **Architecture audit pass** (v0.22.36) — `internal/xdg` package consolidates the `XDG_CONFIG_HOME` fallback chain across the tree (~17 inline copies), `tools/core/atomic` writeAtomic helper exposes a single temp+rename primitive, and a deadcode sweep removed ~290 LoC of speculative test seams while wiring two genuine ones (`Client.Read/Write` round-trip test, `FrameSubsCount` symmetry test). Tree's `deadcode -test ./...` now reports empty.\n- **Auto-launch onboarding** (v0.22.16) — `install.sh` now auto-runs `clawtool onboard` on a TTY install (no [Y/n] prompt to dismiss). Bypass with `CLAWTOOL_NO_ONBOARD=1`. Plus per-step telemetry across the wizard (start / host_detect / bridge_install / mcp_claim / daemon_start / identity_create / secrets_init / telemetry_consent / finish) so we can finally see *where* in the funnel people drop off.\n- **Onboarded marker + nudges** (v0.22.13) — `~/.config/clawtool/.onboarded` is a single source of truth that three surfaces consume: install.sh skips the prompt when present, the Claude Code SessionStart hook stops nagging, and the `clawtool` no-args TUI no longer pre-selects the wizard.\n- **System-notification banner** (v0.22.12+v0.22.16) — daemon-pushed notifications (release-available, daemon-degraded) latch in both the orchestrator and dashboard TUIs, fade after 30s. Severity drives the tint, Kind drives the icon. The orchestrator gained an Active/Done tab + viewport-bounded sidebar at the same time.\n- **`SendMessage` real-time streaming** (v0.22.x) — BIAM runner broadcasts per-line `StreamFrame`s alongside Task transitions over a multiplexed unix socket (`WatchEnvelope{Kind: task | frame | system}`). The orchestrator's per-task ringbuffer renders within ~50ms instead of waiting on SQLite poll. (Replaces the older \"task watch v2\" item that used to live here.)\n- **Cross-process dispatch handoff** — CLI `clawtool send --async` now hands the prompt to the daemon over a dedicated dispatch socket, so frame fanout reaches every consumer (orchestrator, dashboard, `task watch`) regardless of which process originated the dispatch.\n- **`clawtool telemetry status / on / off` + `clawtool onboard --yes`** (v0.22.18) — the wizard's \"flip telemetry off any time\" hint now points at a real subcommand instead of dead-ending in \"unknown command\", and unattended onboarding (Docker, CI, automation scripts) is one flag away.\n- **Docker e2e harness** — `test/e2e/onboard/` builds an image with mock claude/codex/gemini binaries on PATH and runs `clawtool onboard --yes` against it; `CLAWTOOL_E2E_DOCKER=1 go test ./test/e2e/onboard/...` exercises the full host-detect → bridge-install → MCP-claim → daemon-start path end-to-end.\n\n## Roadmap\n\n- **A2A Phase 2 — cross-host mesh** — mDNS / Tailscale tsnet for discovery beyond a single host; WebSocket transport for push notifications (Phase 1 polls the registry every 2s); token + model surfacing in `clawtool.dispatch` once the bridge stream-parser exposes them. Extends the same `peer_id` identity tuple beyond local-mesh.\n- **Persona templates absorb (claude-octopus)** — `clawtool agent template apply \u003ccode-review-team\u003e` to scaffold curated bridges (`code-reviewer` + `test-writer` + `security-auditor`) with model + system_prompt + tool allowlist combos, so a fresh repo gets a working multi-agent setup in one command.\n- **Cross-host BIAM identity routing** — per-call `from_instance` parameter on `SendMessage` so codex / gemini / claude can mutually notify each other through the shared daemon.\n- **Onboarding state machine** — collapse `init` + `onboard` into one engine; per-feature opt-in matrix; verify-summary at the end (`send --list`, `bridge list`, `source check`, `sandbox doctor`). The v0.22.13–v0.22.18 nudge + auto-launch + telemetry-verb bundle covers the *discovery* half; the engine collapse is what's left.\n- **Sandbox-worker phase 2 follow-up** — wire `Client.Read` / `Client.Write` (round-trip-tested) through `tools/core` so Read/Edit/Write tool calls can route to the worker; per-conversation ephemeral workers; gVisor `runsc` runtime selection wired into the docker engine adapter.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/feature-shipping-contract.md](docs/feature-shipping-contract.md). The four-plane review checklist is enforced by CI; commits append no `Co-Authored-By` trailer for AI agents.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogitave%2Fclawtool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcogitave%2Fclawtool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogitave%2Fclawtool/lists"}