Claude Relay

Name: Claude Relay
Author: gvorwaller

Real-time communication between Claude Code instances across multiple machines via WebSocket + MCP.

What This Does

Enables Claude Code sessions on different machines to send messages to each other in real-time. Useful for:

Context sharing - Share findings, file contents, or investigation results between sessions
Task handoffs - Start a task on one machine, continue on another
Coordination - Let one Claude Code instance know what another is doing

Architecture

Machine A Machine B (Server Host) ┌─────────────────┐ ┌─────────────────┐ │ Claude Code │ │ Claude Code │ │ ↓ │ │ ↓ │ │ MCP Server │ │ MCP Server │ │ ↓ │ │ ↓ │ │ WebSocket ────┼── SSH Tunnel ─────┼─→ Relay Server │ │ (localhost) │ or direct │ (port 9999) │ └─────────────────┘ └─────────────────┘

Installation

git clone https://github.com/gvorwaller/claude-relay.git cd claude-relay npm install

Quick Start

1. Start the Relay Server (on one machine)

node server.js # [Claude Relay] Ready! Listening on ws://localhost:9999

2. Configure Claude Code (on each machine)

Add to your Claude Code MCP configuration:

{ "mcpServers": { "claude-relay": { "command": "node", "args": ["/path/to/claude-relay/mcp-server.js"], "env": { "RELAY_CLIENT_ID": "MACHINE_A", "RELAY_URL": "ws://localhost:9999" } } } }

Set a unique RELAY_CLIENT_ID for each machine (e.g., "LAPTOP", "DESKTOP", "M1", "M2").

3. Connect Remote Machines via SSH Tunnel

If machines aren't on the same network, use SSH port forwarding:

# On the remote machine, tunnel to the server host ssh -N -L 9999:localhost:9999 server-host & # Or use autossh for auto-reconnecting autossh -M 0 -N -L 9999:localhost:9999 server-host &

MCP Tools

Once configured, Claude Code will have these tools:

Tool	Description
`relay_send`	Send a message to peer Claude Code instance(s)
`relay_receive`	Get recent messages from peers
`relay_peers`	List currently connected instances
`relay_status`	Check connection health

Example Usage

Send a message:

Use relay_send to tell MACHINE_B: "Found the bug - it's in auth.js line 42"

Check for messages:

Use relay_receive to see if there are any messages from peers

See who's online:

Use relay_peers to list connected instances

macOS Auto-Start (LaunchAgent)

Relay Server (on server host)

# Copy the LaunchAgent cp com.claude-relay.plist ~/Library/LaunchAgents/ # Edit the plist to fix paths for your system: # - Update /usr/local/bin/node to your node path (use `which node`) # - Update /Users/yourname/claude-relay to your install path # Load it launchctl load ~/Library/LaunchAgents/com.claude-relay.plist

SSH Tunnel (on remote machines)

# Install autossh brew install autossh # Copy and edit the tunnel LaunchAgent cp com.claude-relay-tunnel.plist ~/Library/LaunchAgents/ # Edit to set your server hostname and paths # Load it launchctl load ~/Library/LaunchAgents/com.claude-relay-tunnel.plist

Testing

Use the interactive test client:

# Terminal 1: Start server node server.js # Terminal 2: Connect as client A node test-client.js MACHINE_A # Terminal 3: Connect as client B node test-client.js MACHINE_B # In either client: send Hello from here! peers history

Configuration

Environment Variables

Variable	Default	Description
`RELAY_PORT`	`9999`	Port for relay server
`RELAY_CLIENT_ID`	hostname	Identifier for this instance
`RELAY_URL`	`ws://localhost:9999`	Relay server WebSocket URL

Command Line Arguments

# Server node server.js [port] node server.js 8888 # MCP Server node mcp-server.js --client-id=LAPTOP --relay-url=ws://192.168.1.100:9999

Files

File	Description
`server.js`	WebSocket relay server
`mcp-server.js`	MCP protocol server for Claude Code
`test-client.js`	Interactive test client
`com.claude-relay.plist`	macOS LaunchAgent for relay server
`com.claude-relay-tunnel.plist`	macOS LaunchAgent for SSH tunnel

Troubleshooting

Connection refused:

Ensure relay server is running: lsof -i :9999
If using SSH tunnel, verify it's active: ps aux | grep ssh

MCP tools not appearing:

Restart Claude Code after adding MCP config
Check MCP server is connecting: look for "Connected!" in logs

Messages not arriving:

Use relay_peers to verify both instances are connected
Check message history with relay_receive

Security Notes

The relay server has no authentication by default
Designed for trusted local networks or SSH tunnels
All traffic over SSH tunnel is encrypted
Don't expose port 9999 to the internet without adding authentication

License

MIT

Claude Relay

Claude Relay

What This Does

Architecture

Installation

Quick Start

1. Start the Relay Server (on one machine)

2. Configure Claude Code (on each machine)

3. Connect Remote Machines via SSH Tunnel

MCP Tools

Example Usage

macOS Auto-Start (LaunchAgent)

Relay Server (on server host)

SSH Tunnel (on remote machines)

Testing

Configuration

Environment Variables

Command Line Arguments

Files

Troubleshooting

Security Notes

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API