rhizome-mcp

<p align="center">
  <img src="site/assets/rhizome-mcp-logo.png" alt="rhizome-mcp logo" width="420">
</p>

<p align="center">
  <a href="https://github.com/Odrin/rhizome-mcp/actions/workflows/ci.yml"><img src="https://github.com/Odrin/rhizome-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Odrin/rhizome-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOdrin%2Frhizome-mcp%2Fmain%2F.badges%2Fmain%2Funit-coverage.json" alt="Unit test coverage"></a>
  <a href="https://github.com/Odrin/rhizome-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOdrin%2Frhizome-mcp%2Fmain%2F.badges%2Fmain%2Fintegration-coverage.json" alt="Integration test coverage"></a>
  <a href="https://github.com/Odrin/rhizome-mcp/releases"><img src="https://img.shields.io/github/v/release/Odrin/rhizome-mcp?sort=semver" alt="Latest release"></a>
  <a href="go.mod"><img src="https://img.shields.io/github/go-mod/go-version/Odrin/rhizome-mcp" alt="Go version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Odrin/rhizome-mcp" alt="License"></a>
  <a href="https://www.npmjs.com/package/rhizome-mcp"><img src="https://img.shields.io/npm/v/rhizome-mcp" alt="npm"></a>
  <a href="https://www.npmjs.com/package/rhizome-mcp"><img src="https://img.shields.io/npm/dm/rhizome-mcp" alt="npm downloads"></a>
  <a href="https://registry.modelcontextprotocol.io"><img src="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" alt="MCP Registry"></a>
</p>

**When a coding agent dies mid-task, the task frees itself.**

**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.

It 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.

<p align="center">
  <img src="site/assets/demo/lease-expiry.gif" alt="Two agent sessions on one issue: the second claim is denied with ACTIVE_ATTEMPT_EXISTS, the first agent dies, its lease expires, and the second session claims the issue and resumes from the checkpoint" width="820">
</p>
<p align="center"><em>Recorded from real server output by <a href="demo/README.md"><code>demo/record.sh</code></a> — nothing staged.</em></p>

**[Why](#why)** · **[How it compares](#how-it-compares)** · **[Quick start](#quick-start)** · **[Monitor your project](#monitor-your-project)** · **[MCP surface](#mcp-surface)** · **[Documentation](#documentation)**

## Why

AI 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:

- **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.
- **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.
- **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.
- **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).
- **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.

  <details>
  <summary>Watch a stale approval get refused</summary>
  <p align="center"><img src="site/assets/demo/review-superseded.gif" alt="A review request pinned to version 2 refuses approval after the issue moves to version 3; replace_review_request supersedes it into a successor pinned to the new version" width="820"></p>
  </details>
- **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.

  <details>
  <summary>Watch a reservation conflict fail a claim atomically</summary>
  <p align="center"><img src="site/assets/demo/reservation-conflict.gif" alt="An overlapping resource reservation fails the whole claim with RESOURCE_RESERVATION_CONFLICT, naming the holding attempt and its lease expiry" width="820"></p>
  </details>
- **Concurrency discipline throughout.** Optimistic versioning on mutations, replay-safe idempotency keys, stable machine-actionable error codes.
- **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.

This 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)).

**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.

**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.

## How it compares

Compare agent task trackers on guarantees under failure, not on feature lists — local-first SQLite storage and MCP support are table stakes in this category.

| When things go wrong | rhizome-mcp | beads | Kata | Guild |
| --- | --- | --- | --- | --- |
| Task frees itself after a crash | **Yes** — expiring lease | No | No | No |
| Double-claim prevented at the storage layer | **Yes** | Atomic claim | Atomic claim | Atomic claim |
| Stale review approval impossible | **Yes** — version-pinned | No | No | No |
| Response sizes bounded by a tested contract | **Yes** — ≤ 64 KiB / 100 issues | No | No | No |
| Interrupted attempt resumable by another session | **Yes** — checkpoints | No | No | Note only |

Full comparison with sources, pinned versions, and honest "choose X if" guidance: **[How rhizome-mcp compares](https://odrin.github.io/rhizome-mcp/#/compare)**.

## Quick start

### Install and run

Choose the approach that matches your workflow:

#### Zero-install trial via npm

Try `rhizome-mcp` immediately with no separate binary install, no Go toolchain:

```bash
npx rhizome-mcp serve
```

Works with any MCP client. See [packages/npm/README.md](packages/npm/README.md) for platform coverage. Great for quick evaluation.

#### Claude Code plugin

```
/plugin marketplace add Odrin/rhizome-mcp
/plugin install rhizome-mcp@rhizome
```

Registers 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.

#### VS Code

Install [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).

Prefer 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).

#### Native binary installer

Download and install a release binary for your platform. Verifies checksums, installs to `~/.local/bin` by default:

```bash
curl -fsSL https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.sh | sh
```

```powershell
irm https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.ps1 | iex
```

#### Official MCP Registry

Use `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.

### Initialize and connect

Initialize tracking inside your repository:

```bash
rhizome-mcp init
```

Then register the server with your MCP client. Automated setup for common clients:

```bash
rhizome-mcp connect claude    # Claude Code
rhizome-mcp connect codex     # Codex
rhizome-mcp connect vscode    # VS Code (if using standalone binary instead of extension)
rhizome-mcp connect json      # Template for any other client
```

Use `--print` for a dry run. `connect` discovers your project's actual root
(walking up from the current directory the same way `serve` does) and pins
it with `--project-root`, so the written config works regardless