Claude Relay

Let local Claude Code sessions talk to each other in natural language.

Running two Claude sessions on different projects? In one, say "ask the backend session if the auth token shape changed" and the other answers. Or "ask everyone what they're working on" and replies stream back.

Install

Claude Relay ships as a Claude Code plugin. Three steps.

1. Add the marketplace

From any Claude Code session:

/plugin marketplace add innestic/claude-relay

2. Install the plugin

/plugin install relay@claude-relay

This registers the MCP server and slash commands.

3. Launch sessions with the channel capability

Relay delivers inbound messages via notifications/claude/channel — a Claude Code capability still in research preview. Every session that should send or receive messages must be launched with:

claude --dangerously-load-development-channels plugin:relay@claude-relay

The dangerously- prefix is required until Anthropic promotes the channels capability to general availability and adds this plugin to the trusted allowlist. We will submit for review and drop the flag as soon as it's approved.

Open two sessions in different project dirs and try the examples below.

Usage

Try:

"what sessions are active?"
"ask backend-api what they're working on"
"ask everyone to report status"

Rename your session: /relay-rename backend-api. Natural language works too ("call yourself backend-api"), but the slash command is faster. Claude Code's built-in /rename also auto-syncs.

Tools

Tool	What it does
`relay_peers`	List active sessions on this machine
`relay_ask`	Ask one peer; returns immediately, reply arrives as a notification
`relay_reply`	Answer an incoming ask by `ask_id`
`relay_broadcast`	Ask every other peer; replies stream back as notifications
`relay_rename`	Rename this session

Claude routes to these automatically. You rarely call them by name.

If two sessions share a slugged basename (both ~/Code/backend/api), Relay suffixes -2, -3. Use relay_peers to disambiguate by cwd.

Error codes

Code	Meaning
`peer_not_found`	No peer registered under that name
`peer_gone`	Target peer disconnected before replying
`timeout`	Ask timed out waiting for a reply
`name_taken`	Rename or register name already in use
`not_registered`	Caller tried to use a tool before registering
`already_registered`	Same socket tried to register twice
`unknown_ask`	Reply references an `ask_id` the hub has no record of
`bad_msg`	Malformed JSON or schema-invalid payload
`hub_unreachable`	Hub socket died or never replied
`bad_args`	Tool called with missing or wrong-typed arguments
`protocol_mismatch`	Client version != hub version; kill the hub and retry

Debugging

Runtime data lives under $CLAUDE_PLUGIN_DATA (~/.claude/plugins/data/relay-claude-relay/).

DATA=~/.claude/plugins/data/relay-claude-relay
tail -f "$DATA/logs/relay-$(date +%Y-%m-%d).log" | jq   # today's log
pgrep -f hub-daemon.ts                                  # hub alive?
pkill -f hub-daemon.ts && rm -f "$DATA/hub.sock"        # force reset

Per-session MCP stderr lives under ~/Library/Caches/claude-cli-nodejs/<project-slug>/mcp-logs-*/. Start there when a channel fails to register.

How it works

Three pieces:

Session — a Claude Code process you launched.
Channel — per-session MCP server (this plugin). Exposes the relay_* tools to Claude and listens for incoming messages.
Hub — single detached daemon per machine. Routes messages between channels over a Unix socket at $CLAUDE_PLUGIN_DATA/hub.sock.

The first session to launch spawns the hub; later sessions connect to it. The hub survives session restarts and self-exits five minutes after the last peer disconnects. Incoming peer messages arrive as notifications/claude/channel so Claude sees them between turns.

Details: docs/architecture.md.

Out of scope

No persistence — peer state lives in the hub process only
Single user per machine; no auth or access control
Same-host only; no cross-machine relaying

Development

Requires Bun and Claude Code 2.1.80+.

git clone https://github.com/innestic/claude-relay
cd claude-relay && bun install
bun run check   # typecheck + lint + format + test

For a live-reload loop (edits hit Claude Code on restart), bypass the plugin with a project-scope .mcp.json:

cp .mcp.json.example .mcp.json
/plugin uninstall relay@claude-relay

Launch Claude Code with --dangerously-load-development-channels server:relay (note server:, since the MCP is now manually registered). Reinstall the plugin when you're done. .mcp.json is gitignored.

Open an issue before a PR so we can align on scope.

License

MIT