relay

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