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/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://marketplace.visualstudio.com/items?itemName=odrin.rhizome-mcp"><img src="https://img.shields.io/visual-studio-marketplace/v/odrin.rhizome-mcp?label=VS%20Code%20Marketplace" alt="VS Code Marketplace"></a>
  <a href="https://www.npmjs.com/package/rhizome-mcp"><img src="https://img.shields.io/npm/v/rhizome-mcp" alt="npm"></a>
</p>

**rhizome-mcp** is a local-first MCP server for task tracking and coordination of autonomous AI coding agents. It gives agents from different products — Claude Code, Codex, GitHub Copilot, VS Code, and any other MCP-compatible client — a shared, durable view of project work: one static Go binary, one SQLite database per project, no accounts, no Docker, no network dependency.

## 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.
- **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.
- **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.
- **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; stale targets are superseded automatically, so approving changed code is impossible.
- **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, Markdown, or Mermaid.

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

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

#### 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. The manual equivalent for any MCP client:

```json
{
  "mcpServers": {
    "rhizome": {
      "command": "/absolute/path/to/rhizome-mcp",
      "args": ["serve"]
    }
  }
}
```

or, via `npx`, without installing a binary at all:

```json
{
  "mcpServers": {
    "rhizome": {
      "command": "npx",
      "args": ["-y", "rhizome-mcp", "serve"]
    }
  }
}
```

Run `serve` with the repository as its working directory. Stdio is the default transport; protocol output goes to stdout, logs to stderr.

That's it — connected agents discover the workflow through the server itself: `get_project` 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/`.

#### Install the agent workflow skill

For agents that support the open [Agent Skills](https://agentskills.io/) format, install `rhizome-task-workflow` with the npm-distributed [`skills`](https://skills.sh/) CLI:

```bash
npx skills add Odrin/rhizome-mcp --skill rhizome-task-workflow
```

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

### Monitor your project

```bash
rhizome-mcp board                        # status counts, active leases, blockers, review queue
rhizome-mcp board --output board.html    # self-contained HTML snapshot with the planning graph
rhizome-mcp issue list --status ready
rhizome-mcp graph ISSUE-42 --format mermaid
rhizome-mcp doctor --full
```

### Optional: local HTTP transport

```bash
rhizome-mcp serve --http-address 127.0.0.1:0
```

The bound endpoint is logged to stderr; the Streamable HTTP endpoint is `http://127.0.0.1:<port>/mcp`. Loopback-only, no authentication, strict Host/Origin validation — use literal loopback IPs (`127.0.0.1`, `[::1]`), not hostname binds. Not safe to expose beyond the local machine.

## How it works

`init` writes exactly one file into the repository:

```json
{
  "version": 1,
  "project_id": "01J..."
}
```

stored as `.agent-tracker.json`. The SQLite database lives outside the repository in the platform application-data directory, resolved through `project_id`:

```text
<application-data>/rhizome-mcp/projects/<project-id>/tasks.db
```

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

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

**Core constraints (by design):** Go, SQLite (`modernc.org/sqlite`, pure Go, CGO-free), stdio as the primary transport, one database per project, no web UI, no authentication, minimal CLI. Deferred features are listed in [docs/06](docs/06-deferred-and-open.md).

## CLI reference

| Command | Purpose |
| --- | --- |
| `init` | Create `.agent-tracker.json` and the project database |
| `serve` | Run the MCP server (stdio; `--http-address` for local HTTP; `--profile` to narrow the advertised tool catalog) |
| `connect TARGET [--print]` | Register the server with an MCP client (`claude`, `codex`, `vscode`, `json`) |
| `board [--output PATH]` | Status board: counts, leases, blockers, review queue; optional HTML snapshot |
| `issue list` / `issue show ISSUE-ID` | Inspect issues with filters |
| `search QUERY` | Full-text search across issues, comments, decisions, notes |
| `graph ISSUE-ID` | Dependency graph as table, JSON, or Mermaid |
| `project info` / `project export` | Project metadata; logical JSON export |
| `backup --output PATH` | WAL-safe online backup |
| `doctor [--full]` | Integrity, schema, and invariant checks |
| `maintenance release-attempt` / `rebuild-search-inde