Rhizome

Connect coding agents across terminals, worktrees, and colleagues' machines.

Rhizome lets Claude Code, Codex, and OpenCode sessions discover each
other, follow selected work, and exchange messages through MCP. Use it to
coordinate parallel tasks on your laptop or connect your agents with a
colleague's agents over a LAN or Tailscale network.

Your agents keep working in their own projects and tools. Rhizome supplies the
communication infrastructure: verified session identities, peer discovery,
activity delivery, and explicit trust between machines.

Quickstart · Collaborate with colleagues ·
How it works · Documentation

What Rhizome enables

For example, you can work on an API in Codex while a colleague builds its client
in Claude Code. After pairing your machines, ask the client session to follow
the API session. It can receive updates as the API work progresses and send a
question back to that exact session. You still choose task ownership, repository
access, branches, and how changes are reviewed and merged.

Quickstart

1. Install

Download a build from GitHub Releases.
macOS has a signed and notarized installer that places rhizome in
/usr/local/bin. Archives are also available for macOS, Linux, and Windows;
Linux and Windows artifacts are unsigned. See the
installation and checksum guide.

Or build from source with Go 1.27.3+ and Task v3:

git clone https://github.com/aliengiraffe/rhizome.git
cd rhizome
task build
./rhizome --version

The commands below assume rhizome is on your PATH. For a source build, use
./rhizome from the checkout and keep the binary there: setup registers its
absolute path.

2. Connect your agents

rhizome setup

Select your agents and review the setup changes. For a first local trial, keep
MCP networking local and gateway pairing off. Setup installs the
collaboration skill and, for Claude Code and Codex, their MCP registration
and binding hooks at user scope. OpenCode gets the skill and plugins; add its
MCP entry manually.

Restart your agent and complete its integration steps:

3. Try two sessions

Open two supported agent sessions and submit a prompt in each so they bind to
Rhizome. In one, invoke the installed skill with a task description:

/rhizome-collab I'm implementing the API. Show me the other sessions and
help me identify which one is working on the client.

Then ask it to follow the relevant session or send a specific message:

Subscribe to the client session we identified and send it this update:
"The response will include a next_cursor field; please account for pagination."

The agent uses list_sessions, subscribe, and send with exact session IDs.
Names help you recognize sessions; they never decide where a message goes.
Two sessions in the same directory remain separate.

Collaborate with colleagues

Host pairing connects two machines without sharing their local cluster tokens.
Each person runs a Rhizome service, then explicitly pairs with the other host.
Both machines need compatible builds and network access to each other over a
LAN or an existing Tailscale network.

1. Enable pairing on both machines

For Tailscale, run on each machine:

rhizome setup --network local --gateway-mode tailscale --replace-config
rhizome service install
rhizome service stop
rhizome service start

setup saves the configuration and backs up an existing file. Installation
starts the service; stopping and starting applies changed settings to an existing service.
Restart your agents' MCP processes too. For a LAN, use --gateway-mode lan;
see the pairing guide for explicit addresses
and connectivity requirements. Tailscale must already be running on both hosts.

2. Invite your colleague

On your machine:

rhizome invite --expires 10m

Share the printed rhizome join rhz1_... command privately. Your colleague runs
it on their machine. Then check the connection:

rhizome peers list

3. Coordinate the work

Ask your agent to list sessions on the paired host, identify the relevant task,
and subscribe or send a message to its exact session ID. For example:

My colleague is working on the client on the paired host. List its sessions
and help me find the client task, then follow that session's updates.

Pairing authenticates a host, not a person's identity. The same mechanism
also connects two machines you own. Remote origin is established by authenticated
host metadata, never inferred from a session name or project path.

Sharing scope: paired hosts currently see all eligible bound local sessions;
per-session privacy is not implemented. History sharing is off by default and
requires a separate owner-controlled policy.
Pairing is direct: pairing A with B and B with C does not connect A with C.
Use rhizome peers revoke <host-id> to revoke a host.

How it works

Rhizome is a Go executable with two main roles: an MCP bridge for agent sessions,
and an optional per-user background service for observation, history, and host
pairing. Local messaging works without the background service. Cross-host pairing
requires the service on both machines.

flowchart LR
    subgraph A[Your machine]
        A1[Claude Code / Codex / OpenCode] <-->|MCP + agent integration| AM[Rhizome session nodes]
        AM <-->|Authenticated loopback gRPC| AS[Rhizome service]
        AL[Local Claude / Codex logs and OpenCode database] -->|Read-only observation / indexing| AS
        AS --> AH[Local history catalog]
    end
    subgraph B[Colleague's machine]
        BS[Rhizome service] <-->|Authenticated loopback gRPC| BM[Rhizome session nodes]
        BM <-->|MCP + agent integration| B1[Colleague's agents]
    end
    AS <-->|Explicit pairing · pinned TLS| BS

Rhizome needs no central broker or hosted coordination service. For paired hosts,
MCP networking stays local and the services handle cross-machine transport.
An alternative shared-token LAN/Tailscale mode
connects MCP nodes directly; it is a separate trust model and cannot be combined
with host pairing in the same configuration.

What gets shared

Subscriptions carry selected assistant text, tool names/status, and turn markers.
Automatic collection excludes user prompts, reasoning, full tool bodies,
subagent transcripts, and received peer traffic. Explicit send and publish
calls carry the text the sender chooses. Collected assistant text can still
contain project-sensitive information.

Delivery uses bounded queues, short replay windows, deduplication, and feedback
controls. A successful send means the receiver accepted it into a queue,
not that the agent read or acted on it. Restarts lose live replay state and
subscription intent; the history catalog is a separate read-only facility.
See delivery guarantees.

Documentation

Development

Build and run the required checks from the repository root:

task build
task check
python3 scripts/smoke_stdio.py
python3 scripts/smoke_stdio.py --lan
python3 scripts/smoke_service.py
git diff --check

See AGENTS.md for engineering requirements and additional checks
for specific integrations. Automated smokes use isolated state and synthetic
transcripts. Live agent and cross-device validation are documented separately
in the verification guide.