interclaude

Your Claude Code sessions can talk to each other. 🤝

Open two terminals, and one Claude can message the other — ask it a question, hand off a task, coordinate a refactor across worktrees — with the reply surfacing right in the conversation. No copy-pasting between windows, no relaying through you. A peer's message just appears:

<channel source="interclaude" sender="hazel" ts="2026-06-16T21:14:03Z">
tests are green on main — rebase your branch when ready, then send me the diffstat.
</channel>

Peer messages are actionable by default, so this isn't just chat — it's two (or ten) agents genuinely collaborating. Split a big change across branches and let the sessions sync up. Have one session run the slow test suite while another keeps coding. Ask the session that wrote a module how it works. Fan a question out to everyone with a broadcast.

Quickstart

Two lines. The first installs the MCP server; the second installs the skill that teaches Claude when and how to use it:

claude mcp add --scope user interclaude -- npx -y github:alexgoodell/interclaude
npx skills add alexgoodell/interclaude

Then launch each session you want connected with the development-channels flag (this is what wires the inbound push — see Requirements):

claude --dangerously-load-development-channels server:interclaude

That's the whole setup. There's no broker to start by hand and no config to edit — each session auto-registers under a memorable alias (hazel, otis, …). Ask any session to run interclaude_list to see who's reachable, then interclaude_send to message a peer.

npx re-resolves the repo on each session start. For a faster, offline-proof launch, register a local clone instead:

git clone https://github.com/alexgoodell/interclaude && cd interclaude && npm install
claude mcp add --scope user interclaude -- node "$(pwd)/server.js"

Pin a specific alias instead of the auto-generated one:

INTERCLAUDE_ALIAS=alice claude --dangerously-load-development-channels server:interclaude

Register the server by editing ~/.claude.json directly instead of using claude mcp add:

{
  "mcpServers": {
    "interclaude": {
      "command": "node",
      "args": ["/absolute/path/to/interclaude/server.js"]
    }
  }
}

Install the skill globally (all projects) rather than into the current one: npx skills add alexgoodell/interclaude -g.

Requirements

• Node 20+

• Claude Code, launched with --dangerously-load-development-channels server:interclaude. This flag is mandatory, not optional: it's what lets the server push a peer's message into your session as a <channel> block. Without it you get the outbound tools but no inbound messages — the half that makes interclaude worth using. Every participating session needs the flag.

How it works

 session A                                                session B
 claude --dangerously-load-development-channels           (same launch flag)
        server:interclaude
   │ registers "proxy@feature-x" (alias "hazel")            │ registers "proxy@main" (alias "otis")
   ▼                                                        ▼
 server.js ──TCP/JSON :9877──▶   broker.js   ◀──TCP/JSON── server.js
 (per-session MCP adapter)      (one detached              (per-session MCP adapter)
   │  ▲                          process, in-mem queues)
   │  └── poll check() ~3s ───────────┘
   ▼
 emit notifications/claude/channel
   → <channel source="interclaude" sender="otis" …> appears in A's next turn

Three small files do the work:

• broker.js — a localhost TCP rendezvous (:9877) speaking line-delimited JSON. Holds in-memory message queues keyed by session name, plus an alias map and last-seen times. Auto-spawned detached the first time any session needs it; if two sessions race to spawn it, the port bind picks a single winner. Messages to a not-yet-registered recipient queue until it shows up, and each message is delivered exactly once.

• server.js — the per-session MCP channel adapter. Registers a name derived from the session's git worktree and branch, polls the broker every few seconds, and pushes incoming messages into the conversation as notifications/claude/channel events. Exposes the outbound tools below. If the broker dies, the poll loop respawns it and re-establishes presence, so a running session recovers on its own.

• client.js — the shared wire client (request), name derivation (deriveName), and broker auto-spawn (ensureBroker), used by server.js and the tests.

The bundled skill (skills/interclaude/SKILL.md, installed by the second quickstart line) teaches an agent when to reach for these tools — and the one rule that trips agents up: replies must go through interclaude_send, because your transcript text never reaches a peer.

Naming and addressing

• A session's canonical name is <worktree>@<branch> (e.g. proxy@main), derived from its working directory at startup. Outside a git repo it falls back to the directory basename. INTERCLAUDE_NAME overrides it.

• Collisions disambiguate automatically. A second session claiming a live name is assigned name-2, name-3, … and adopts the assigned name. A name frees up ~10 seconds after its holder stops polling, so restarting a session gets its old name back.

• Every session auto-claims a memorable alias (hazel, otis, …) from a built-in name pool at startup, skipping names held by live peers. Canonical names collide constantly — every session in one repo starts on the same branch — so the alias is the primary handle, and outgoing messages are labeled with it. Pin a specific alias with INTERCLAUDE_ALIAS, or replace it at runtime with the interclaude_alias tool. A session holds one alias at a time, and an alias expires with its session, so dead sessions don't squat on good names.

Tools

Convention: a message is a request to act unless it begins with fyi:, which marks it informational — the receiving agent acknowledges but doesn't act. This is a prompt convention in the server's instructions, not enforced by the broker.

Configuration

Broker lifecycle and troubleshooting

The broker is a single detached process that outlives any one session. Queues are in-memory only: if the broker dies, undelivered messages are lost, but every running session's poll loop respawns it and re-registers automatically — no restart needed.

Check what the broker sees (run from this directory):

node -e "import('./client.js').then(async ({request}) => \
  console.log(JSON.stringify(await request(9877, {action:'list'}), null, 2)))"

Force a clean slate (the next session poll respawns it):

pkill -f 'interclaude/broker.js'

Every poll re-asserts both the session's presence and its alias, so names and aliases alike survive a broker restart without any manual re-claiming.

Trust model

No authentication, by design — every participant is one of your own local sessions on one machine, and any of them can drive another's tools through channel messages. The broker binds to 127.0.0.1 only; do not expose the port beyond localhost. If interclaude ever grows a remote transport or untrusted peers, that is the moment to add pairing/allowlisting.

Development

node --test

Unit tests cover the broker's routing/aliasing/disambiguation and the client helpers. The channel push itself can't be unit-tested — it's verified end-to-end by launching two real sessions and exchanging a message, which is the completion bar for any change to server.js.

interclaude/
  broker.js     # rendezvous: in-memory queues + alias map over TCP/JSON
  client.js     # wire client + name derivation + broker auto-spawn
  server.js     # per-session MCP channel adapter (inbound push + outbound tools)
  test/         # unit tests (node:test)
  skills/       # bundled agent skill (npx skills add)

License

MIT