\n\n**When a coding agent dies mid-task, the task frees itself.**\n\n**rhizome-mcp** gives autonomous coding agents crash-safe task coordination over MCP: claims are renewable expiring leases, `in_progress` is derived — never stored — and an interrupted attempt hands its checkpoint to whichever session picks the work up next. One static Go binary, one SQLite database per project. No daemon, no accounts, no cloud.\n\nIt works with agents from different products at once — Claude Code, Codex, GitHub Copilot, VS Code, and any other MCP-compatible client — giving them one shared, durable view of project work.\n\n
\n \n
\n
Recorded from real server output by demo/record.sh — nothing staged.
\n\n**[Why](#why)** · **[How it compares](#how-it-compares)** · **[Quick start](#quick-start)** · **[Monitor your project](#monitor-your-project)** · **[MCP surface](#mcp-surface)** · **[Documentation](#documentation)**\n\n## Why\n\nAI coding agents are concurrent, context-limited, and interruptible. A `TODO.md` or a single chat context doesn't survive that. rhizome-mcp is built around those failure modes:\n\n- **Crash-safe claiming.** Issues are claimed atomically with renewable leases. `in_progress` is never a stored status — it is derived from an active lease, so a vanished agent can't lock an issue forever. When the lease expires, the issue becomes claimable again. A partial unique index guarantees at most one active attempt per issue at the database level.\n- **Token-efficient by contract.** Compact list projections (a 100-issue page stays under 64 KB — enforced by an integration test), graph nodes that exclude free-text bodies at the SQL layer, snippet-only search, delta sync via event IDs, and a bounded single-call work-context package.\n- **Durable project memory.** Checkpoints with next steps, supersedable decision records, append-only event history, and FTS5 full-text search across issues, comments, decisions, and notes. A fresh session resumes from the last checkpoint instead of re-deriving state.\n- **Planning and dependency graphs.** Cycle-checked `blocks` relations, epics, claimable entry-point highlighting, and atomic batch planning (up to 50 issues, 100 relations, and 20 decisions in one all-or-nothing transaction).\n- **Review workflow.** Review requests pin an exact issue version and event position; approving changed code is structurally impossible — a stale request can only be superseded and re-pinned.\n\n \n Watch a stale approval get refused\n
\n \n- **Resource reservations.** A claim can atomically reserve files, directories, globs, or logical resources (a port, a migration window, a deploy slot); an overlapping claim fails fast with the holder and its lease expiry named, instead of two agents colliding later.\n\n \n Watch a reservation conflict fail a claim atomically\n
\n \n- **Concurrency discipline throughout.** Optimistic versioning on mutations, replay-safe idempotency keys, stable machine-actionable error codes.\n- **Human observability without a server.** `rhizome-mcp board` prints live leases, blockers, and the review queue, or writes a self-contained HTML snapshot; the CLI reads everything as tables, JSON, or Mermaid.\n\nThis repository tracks its own backlog through the server it ships — work is selected, claimed, checkpointed, and reviewed via rhizome-mcp itself ([AGENTS.md](AGENTS.md)).\n\n**Use it when** several agent sessions (or several agent products) work the same repository over time and you need handoffs, parallel work, and recovery after crashes or context limits.\n\n**Skip it if** you need a hosted multi-user tracker with auth, permissions, and a web UI — this is a local single-developer tool by design.\n\n## How it compares\n\nCompare agent task trackers on guarantees under failure, not on feature lists — local-first SQLite storage and MCP support are table stakes in this category.\n\n| When things go wrong | rhizome-mcp | beads | Kata | Guild |\n| --- | --- | --- | --- | --- |\n| Task frees itself after a crash | **Yes** — expiring lease | No | No | No |\n| Double-claim prevented at the storage layer | **Yes** | Atomic claim | Atomic claim | Atomic claim |\n| Stale review approval impossible | **Yes** — version-pinned | No | No | No |\n| Response sizes bounded by a tested contract | **Yes** — ≤ 64 KiB / 100 issues | No | No | No |\n| Interrupted attempt resumable by another session | **Yes** — checkpoints | No | No | Note only |\n\nFull comparison with sources, pinned versions, and honest \"choose X if\" guidance: **[How rhizome-mcp compares](https://odrin.github.io/rhizome-mcp/#/compare)**.\n\n## Quick start\n\n### Install and run\n\nChoose the approach that matches your workflow:\n\n#### Zero-install trial via npm\n\nTry `rhizome-mcp` immediately with no separate binary install, no Go toolchain:\n\n```bash\nnpx rhizome-mcp serve\n```\n\nWorks with any MCP client. See [packages/npm/README.md](packages/npm/README.md) for platform coverage. Great for quick evaluation.\n\n#### Claude Code plugin\n\n```\n/plugin marketplace add Odrin/rhizome-mcp\n/plugin install rhizome-mcp@rhizome\n```\n\nRegisters the MCP server (via `npx`, no binary install) and adds the `rhizome-task-workflow` and `rhizome-execution-plan` skills. Each repository you track still needs a one-time `npx rhizome-mcp init` in its root.\n\n#### VS Code\n\nInstall [Rhizome MCP](https://marketplace.visualstudio.com/items?itemName=odrin.rhizome-mcp) (`odrin.rhizome-mcp`) from the Marketplace or [Open VSX](https://open-vsx.org/extension/odrin/rhizome-mcp). The extension bundles the platform binary, registers the MCP server automatically, and adds `Rhizome: Initialize Project` to the Command Palette. No terminal, no `mcp.json` editing. Details: [docs/10-vscode-extension.md](docs/10-vscode-extension.md).\n\nPrefer a standalone binary with a plain `mcp.json` entry instead? Install the binary below and use this one-click link: [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22rhizome-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22rhizome-mcp%22%2C%22args%22%3A%5B%22serve%22%5D%7D).\n\n#### Native binary installer\n\nDownload and install a release binary for your platform. Verifies checksums, installs to `~/.local/bin` by default:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.sh | sh\n```\n\n```powershell\nirm https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.ps1 | iex\n```\n\n#### Official MCP Registry\n\nUse `rhizome-mcp` via the official MCP Registry, available in the [Model Context Protocol registry](https://registry.modelcontextprotocol.io) as `io.github.Odrin/rhizome-mcp` for clients that consume the registry.\n\n### Initialize and connect\n\nInitialize tracking inside your repository:\n\n```bash\nrhizome-mcp init\n```\n\nThen register the server with your MCP client. Automated setup for common clients:\n\n```bash\nrhizome-mcp connect claude # Claude Code\nrhizome-mcp connect codex # Codex\nrhizome-mcp connect vscode # VS Code (if using standalone binary instead of extension)\nrhizome-mcp connect json # Template for any other client\n```\n\nUse `--print` for a dry run. `connect` discovers your project's actual root\n(walking up from the current directory the same way `serve` does) and pins\nit with `--project-root`, so the written config works regardless of which\nsubdirectory an MCP client later launches the server from. All four targets\n(`claude`, `codex`, `vscode`, `json`) agree on this. The manual equivalent\nfor any MCP client, matching `connect`'s own server key:\n\n```json\n{\n \"mcpServers\": {\n \"rhizome-mcp\": {\n \"command\": \"/absolute/path/to/rhizome-mcp\",\n \"args\": [\"serve\", \"--project-root\", \"/absolute/path/to/your/repository\"]\n }\n }\n}\n```\n\nor, via `npx`, without installing a binary at all:\n\n```json\n{\n \"mcpServers\": {\n \"rhizome-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"rhizome-mcp\", \"serve\", \"--project-root\", \"/absolute/path/to/your/repository\"]\n }\n }\n}\n```\n\n`connect` detects when it is itself running through the `npx rhizome-mcp`\nwrapper and automatically emits this `npx` form instead of the wrapper's\nresolved binary path, which lives in the npx cache and goes stale on\neviction or a version bump. A config written with a resolved absolute path\n(the default otherwise) is machine-specific and not meant to be checked in\nand shared across machines; pass `connect TARGET --command` to instead emit\na bare `rhizome-mcp` command name that relies on `PATH`, for a portable\nconfig you do intend to share, provided every machine that uses it has\n`rhizome-mcp` on `PATH`.\n\nStdio is the default transport; protocol output goes to stdout, logs to\nstderr.\n\nThat's it — connected agents start with `open_project` using the absolute repository root, retain its `project_ref`, and pass that reference to later project-scoped calls. See [the agent workflow guide](.github/skills/rhizome-task-workflow/references/agent-workflow.md) for the complete workflow. The returned metadata links the `rhizome://guides/agent-workflow`, `rhizome://guides/issue-lifecycle`, and `rhizome://guides/multi-agent-handoff` resources, and repository agents can load the `rhizome-task-workflow` skill from `.github/skills/`.\n\n#### Install the agent workflow skill\n\nFor agents that support the open [Agent Skills](https://agentskills.io/) format, install `rhizome-task-workflow` with the npm-distributed [`skills`](https://skills.sh/) CLI:\n\n```bash\nnpx skills add Odrin/rhizome-mcp --skill rhizome-task-workflow\n```\n\nRun the command in a project for a project-scoped installation, or add `--global` to make the skill available across projects. The skill teaches compatible agents how to select, claim, checkpoint, hand off, and finish Rhizome work. It complements the MCP server; it does not install the `rhizome-mcp` binary or configure an MCP connection.\n\n### Monitor your project\n\n```bash\nrhizome-mcp board # status counts, active leases, blockers, review queue\nrhizome-mcp board --serve # interactive local board UI at a loopback URL\nrhizome-mcp board --output board.html # self-contained HTML snapshot with the planning graph\nrhizome-mcp issue list --status ready\nrhizome-mcp graph ISSUE-42 --format mermaid\nrhizome-mcp doctor --full\n```\n\n
\n \n
\n\nThe status board reports live lease counts, blocked issues and their reasons, open review requests, and the project-wide planning graph. The planning graph excludes finished work (done, cancelled) from the node budget, so the entry-point count always reflects claimable work. When the graph is truncated due to the 100-node budget, the board marks it as truncated and reports the retained node count in both table and JSON formats.\n\n### Optional: local HTTP transport\n\n```bash\nrhizome-mcp serve --http-address 127.0.0.1:0\n```\n\nThe bound endpoint is logged to stderr; the Streamable HTTP endpoint is `http://127.0.0.1:/mcp`. The transport is loopback-only, unauthenticated, and enforces strict Host/Origin validation plus a 1 MiB outer request body limit. Modern MCP `2026-07-28` clients call `server/discover` and then send direct requests with protocol metadata; legacy `2025-11-25` clients can still use `initialize` and `notifications/initialized` without relying on a persistent transport session. If you want durable audit attribution, create an explicit `agent_session_handle` with `create_agent_session`, pass it to the relevant mutating tools, and end it later with `end_agent_session`; transport closure never ends it.\n\n## How it works\n\n`init` writes exactly one file into the repository:\n\n```json\n{\n \"version\": 1,\n \"project_id\": \"01J...\"\n}\n```\n\nstored as `.agent-tracker.json`. The SQLite database lives outside the repository in the platform application-data directory, resolved through `project_id`:\n\n```text\n/rhizome-mcp/projects//tasks.db\n```\n\nUse `--data-root PATH` to select an explicit data root for any command. Nothing else touches your repository, and the database is never committed to Git.\n\n**Design principle:** an issue must never remain permanently stuck in `in_progress`. Effective status is computed from stored status plus the presence of an active leased attempt; if the agent disappears and the lease expires, the attempt becomes `expired` and the issue is available again when its stored state permits it.\n\n**Core constraints (by design):** Go, SQLite (`modernc.org/sqlite`, pure Go, CGO-free), stdio as the primary transport, one database per project, no hosted or authenticated web UI (a loopback-only local status board is included), no authentication, minimal CLI. Deferred features are listed in [docs/06](docs/06-deferred-and-open.md).\n\n## CLI reference\n\n| Command | Purpose |\n| --- | --- |\n| `init` | Create `.agent-tracker.json` and the project database |\n| `serve [--http-address ADDR] [--profile full\\|agent\\|read-only\\|migration] [--toolsets GROUP[,GROUP...]] [--project-root PATH]` | Run the MCP server (stdio; `--http-address` for local HTTP; `--profile` to narrow the advertised tool catalog to a named profile, or `--toolsets` to compose one from capability groups; `--project-root` to serve a project other than the working directory) |\n| `connect TARGET [--print] [--command]` | Register the server with an MCP client (`claude`, `codex`, `vscode`, `json`) |\n| `board [--output PATH] [--serve [--http-address ADDR]]` | Status board: counts, leases, blockers, review queue; optional HTML snapshot; `--serve` runs a temporary HTTP server |\n| `issue list` / `issue show ISSUE-ID` | Inspect issues with filters |\n| `search QUERY` | Full-text search across issues, comments, decisions, notes |\n| `graph ISSUE-ID` | Dependency graph as table, JSON, or Mermaid |\n| `project info` / `project export` / `project import` | Project metadata; logical JSON export; logical JSON import (`--input PATH|-` with `--dry-run` or `--apply`) |\n| `backup --output PATH` | WAL-safe online backup |\n| `doctor [--full]` | Integrity, schema, and invariant checks |\n| `maintenance release-attempt` / `rebuild-search-index` | Administrative recovery |\n\nRun `rhizome-mcp` without arguments for complete usage, `rhizome-mcp version` for build information.\n\n## MCP surface\n\nThe server exposes 43 tools covering the full lifecycle: project discovery, issue CRUD with labels and relations, planning and dependency graphs, batch plan validation/apply, comments and decisions, claim/renew/checkpoint/finish work attempts with optional atomic resource reservations, work-context assembly, review requests, full-text search, delta changes, logical project export/import, and workflow-policy administration with gate evidence and diagnostics. The complete contract, including the MCP tool annotation matrix and the `full`/`agent`/`read-only`/`migration` exposure profile matrix, is in [docs/03-mcp-tools.md](docs/03-mcp-tools.md).\n\nBy default `serve` advertises the complete `full` catalog. Pass `--profile agent|read-only|migration` (or set `RHIZOME_TOOL_PROFILE`) to narrow it — for example `serve --profile read-only` for a client that should never see a mutating tool. When no named profile fits, pass `--toolsets` (or set `RHIZOME_TOOLSETS`) with a comma-separated list of capability groups instead — for example `serve --toolsets issues,planning` — to advertise exactly those groups plus the always-on `core` pair (`open_project`, `get_project`); the two flags are mutually exclusive. Profiles and toolsets are an exposure and prompt-size control, not an authorization boundary: every tool still enforces its own server-side validation regardless of what a client can see in `tools/list`. See [docs/04-storage-runtime.md](docs/04-storage-runtime.md) §17.1 for the full environment-variable set and precedence, including the deprecated unprefixed fallback names.\n\n## Documentation\n\nThe modular files under `docs/` are the canonical specification; [SPEC.md](SPEC.md) is the index. Agents should load only the sections relevant to their current task ([AGENT_BRIEF.md](AGENT_BRIEF.md) explains how).\n\n1. [Product goals and scope](docs/01-product-scope.md)\n2. [Domain model](docs/02-domain-model.md)\n3. [MCP tools](docs/03-mcp-tools.md)\n4. [Storage and runtime](docs/04-storage-runtime.md)\n5. [Implementation requirements](docs/05-implementation-requirements.md)\n6. [Deferred features and non-goals](docs/06-deferred-and-open.md)\n7. [Logical interchange format](docs/07-logical-interchange.md)\n8. [Local HTTP transport contract](docs/08-local-http-transport.md)\n9. [Review workflow contract](docs/09-review-workflow.md)\n10. [VS Code extension](docs/10-vscode-extension.md)\n11. [Project routing contract](docs/11-project-routing.md)\n12. [Resource reservations](docs/12-resource-reservations.md)\n13. [Status board](docs/13-status-board.md)\n\nGuides for humans (quick start, workflow, CLI) live in [site/](site/) and are published via GitHub Pages. Release history is in the [CHANGELOG](CHANGELOG.md).\n\n## Development\n\nBuild and test (no CGO, no external services):\n\n```bash\nCGO_ENABLED=0 go build -o rhizome-mcp .\ngo test ./...\ngo test -tags=integration ./...\n```\n\nThe integration tag runs real-process MCP smoke and workflow tests: they build a temporary server binary, initialize a fresh repository and SQLite data root per test, and speak to `serve` over stdio or HTTP. Beyond single-process smoke coverage, the suite also exercises cross-process scenarios on one shared SQLite data root — concurrent claim and update-version races, an ungraceful process kill and restart, and a backup taken while a server is writing — to catch defects a single-process test structurally cannot see. Most live in the dedicated `integration` package; tests that need unexported package-main internals stay at the repository root.\n\nCI runs `go vet`, unit, and integration tests on Ubuntu, macOS, and Windows for every push and pull request targeting `main`. Releases (`.github/workflows/release.yml`) publish CGO-free binaries with SHA-256 checksums for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64; release binaries embed the version, commit, and build timestamp (local builds report git VCS info or `dev`, and the `VERSION` environment variable overrides both).\n\nRelease verification steps are documented in [CONTRIBUTING.md](CONTRIBUTING.md#release-verification).\n\nThis repository tracks its own backlog in rhizome-mcp: work is selected, claimed, and finished through the MCP server, and durable choices are recorded as decisions. Markdown holds specification only, not task status. See [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[Apache-2.0](LICENSE). Security policy: [SECURITY.md](SECURITY.md).\n",
"bytes": 21569,
"sha": "fb501dce06b6c8f46bd4683829f845b160dd7aa44d718f55479085152ed5415a",
"repo_slug": "odrin/rhizome-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_odrin_rhizome_mcp_d361cae4/readme"
}
![\"rhizome-mcp](\"site/assets/rhizome-mcp-logo.png\"){kind=logo}
\n![\"CI\"](\"https://github.com/Odrin/rhizome-mcp/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Unit](\"https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOdrin%2Frhizome-mcp%2Fmain%2F.badges%2Fmain%2Funit-coverage.json\")
![\"Integration](\"https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOdrin%2Frhizome-mcp%2Fmain%2F.badges%2Fmain%2Fintegration-coverage.json\")
![\"Latest](\"https://img.shields.io/github/v/release/Odrin/rhizome-mcp?sort=semver\")
![\"Go](\"https://img.shields.io/github/go-mod/go-version/Odrin/rhizome-mcp\")
![\"License\"](\"https://img.shields.io/github/license/Odrin/rhizome-mcp\")
![\"npm\"](\"https://img.shields.io/npm/v/rhizome-mcp\")
![\"npm](\"https://img.shields.io/npm/dm/rhizome-mcp\")
![\"MCP](\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dio.github.Odrin%252Frhizome-mcp%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&label=MCP%20Registry&prefix=v&color=8A2BE2\"){kind=icon}
![\"Two](\"site/assets/demo/lease-expiry.gif\")
\n![\"A](\"site/assets/demo/review-superseded.gif\")
![\"An](\"site/assets/demo/reservation-conflict.gif\")
![\"rhizome-mcp](\"site/assets/demo/board.png\")
\n