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

| Workflow | What you can do | | --- | --- | | Parallel development | Run implementation, tests, and review in separate sessions or worktrees. Follow relevant sessions so discoveries and blockers reach the agents that need them. | | Collaboration with colleagues | Pair two machines, discover each other's agent sessions, and exchange context while each person keeps their own development environment. | | Cross-agent work | Let a Codex session follow a Claude Code session or send a question to an OpenCode session. Supported integrations share the same session addressing and collaboration tools. | | Continuity across sessions | Search past Claude Code, Codex, and OpenCode work and read selected activity through the optional local history service. A colleague can separately opt in to sharing history. | | Explicit file handoffs | Offer a selected file to a session on a paired host. The recipient chooses whether to accept it into a temporary inbox. |

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. To take Rhizome out again, rhizome uninstall reverses these installs for the agents you pick (--all also stops the background service) with the same backups, and leaves ~/.rhizome in place (details).

Restart your agent and complete its integration steps:

| Agent | Before the first conversation | | --- | --- | | Claude Code | Launch with claude --dangerously-load-development-channels server:rhizome and accept the channel/hook prompts. Setup details. | | Codex | Start a fresh session, review and trust the Rhizome hooks in /hooks. Setup details. | | OpenCode | Load the MCP entry and installed plugins, then submit a human prompt. Setup details. |

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.

| Layer | What it provides | | --- | --- | | Session identity | Agent-specific hooks or verified transport metadata bind each session. Exact IDs keep worktrees, concurrent chats, and agent types distinct. | | Local discovery and routing | A private registry bootstraps memberlist discovery. Nodes exchange activity through authenticated gRPC on loopback; local peers can communicate directly. | | Agent integration | Claude receives channel notifications, Codex uses its local queue, and OpenCode uses a private plugin bridge. | | Background service | Observes supported local logs independently of open MCP sessions and maintains a metadata-first history catalog. Observation-only sessions cannot receive messages. | | Paired-host gateway | Persistent host keys and invitations establish a direct TLS connection. Each service exposes remote sessions locally through proxies, keeping local tokens on their own machines. |

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

| Guide | Contents | | --- | --- | | Setup and protocol reference | Configuration, installation behavior, MCP tools, session names, discovery, networking, and delivery limits. | | Host pairing | LAN/Tailscale setup, invitations, trust, revocation, and connectivity checks. | | Background service | Installation, lifecycle, observation, and terminal management. | | Session history | Local search, paginated reads, optional peer access, and content policy. | | File transfers | Explicit offers and acceptance, temporary storage, and limits. | | Agent integrations | Claude Code setup; dedicated guides for Codex and OpenCode. | | Verification | Tested client versions, automated coverage, and manual checks. | | Releases | Downloads, checksums, signing, upgrades, and platform limits. |

Contributing and reporting

See CONTRIBUTING.md for the contributor workflow. Use the issue chooser for bugs and feature requests, and SECURITY.md to report vulnerabilities privately.

Development

Build and run the required checks from the repository root, using the disposable-state wrapper to protect your agent configuration:

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.

Session status

Every row of list_sessions carries a status and delivery_capable; neither visibility nor a label implies that a person will read a message.

| status | Meaning | delivery_capable | | --- | --- | --- | | live | One or more direct integrations currently report the session. Several processes sharing one session_id (for example a reloaded instance or a duplicate MCP process) collapse into a single row. | true only when exactly one