Claude Relay

Running multiple Claude Code sessions? They can't talk to each other natively. Claude Relay adds four MCP tools that let sessions exchange messages — locally through the filesystem (low-cost) or across machines via an HTTP relay (configurable).

Setup

Add to ~/.claude/settings.json (no separate install needed — npx handles it):

{
  "mcpServers": {
    "claude-relay": {
      "command": "npx",
      "args": ["-y", "claude-relay", "serve"]
    }
  }
}

That's it. Every Claude Code session now has relay tools available.

Cross-machine relay (optional)

To enable communication between different machines, add your relay server credentials:

{
  "mcpServers": {
    "claude-relay": {
      "command": "npx",
      "args": ["-y", "claude-relay", "serve"],
      "env": {
        "RELAY_REMOTE_URL": "https://your-relay-server.com/relay",
        "RELAY_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

Once configured, every Claude Code session gets these MCP tools:

| Tool | Description | |------|-------------| | relay_send | Send a message to another session | | relay_poll | Check for new messages | | relay_broadcast | Send to all active sessions | | relay_sessions | List active sessions on this machine |

Examples

Send a message to another session:

relay_send(to: "my-api", message: "Deploy is complete", type: "info")

Check for messages:

relay_poll()
→ 1 new message(s):
  [request|local] From frontend: Can you run the test suite?

Send cross-machine:

relay_send(to: "server-2:my-api", message: "Run migrations", type: "request")

See who's online:

relay_sessions()
→ 3 active session(s):
  - my-api (you) — ~/projects/my-api (up 45m, pid 1234)
  - frontend — ~/projects/frontend (up 12m, pid 5678)
  - docs — ~/projects/docs (up 120m, pid 9012)

How It Works

Session A (my-api)                   Session B (frontend)
    │                                    │
    ├── relay_send("frontend",           │
    │   "Tests passing")                 │
    │         │                          │
    │    ┌────▼─────────────────┐        │
    │    │  ~/.claude-relay/    │        │
    │    │  └── inbox/          │        │
    │    │      └── frontend/   │        │
    │    │          └── msg.json│        │
    │    └──────────────────────┘        │
    │                          │         │
    │                    relay_poll() ───┤
    │                    → "Tests passing"

Each Claude Code session runs its own MCP server instance. They share state through ~/.claude-relay/ using atomic file operations. No central daemon, no database, no native dependencies.

Session naming

Sessions are named after their working directory by default:

• ~/projects/my-api → my-api
• ~/projects/frontend → frontend

Override with the RELAY_SESSION_NAME environment variable in your MCP config.

Message types

| Type | Meaning | |------|---------| | request | Expects a response from the recipient | | info | One-way notification (default) | | response | Answering a previous request |

Routing

Messages are automatically routed:

• Local session name (e.g., frontend) → filesystem (lowest cost)
• machine:session format (e.g., server-2:my-api) → HTTP relay
• Unknown name with remote configured → falls back to HTTP relay

Cost comparison

MCP tool calls have minimal overhead compared to skill-based approaches:

| Operation | Skill-based relay | Claude Relay (MCP) | |-----------|-------------------|-------------------| | Poll (no messages) | ~500 tokens | ~20 tokens | | Send message | ~1,000 tokens | ~50 tokens | | Idle 8hrs @ 30s intervals | ~480K tokens | ~19K tokens |

The savings come from MCP tool calls being processed by the MCP server directly, with only the compact tool result entering the LLM context — versus full skill text expansion and curl command generation.

CLI

# Start MCP server (Claude Code runs this automatically)
claude-relay serve

# Check active sessions from your terminal
claude-relay status

# Remove stale session data and old messages
claude-relay clean

# Show version
claude-relay version

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | RELAY_SESSION_NAME | cwd basename | Override session name | | RELAY_MACHINE_NAME | hostname | Override machine identifier | | RELAY_REMOTE_URL | (none) | HTTP relay server URL | | RELAY_API_KEY | (none) | API key for remote relay |

Requirements

• Node.js 18+
• Claude Code with MCP support

Architecture

claude-relay/
├── src/
│   ├── types.ts              # Type definitions
│   ├── store.ts              # File-based message queue (~/.claude-relay/)
│   ├── server.ts             # MCP server exposing 4 tools
│   ├── router.ts             # Auto-routing: local vs remote
│   ├── remote-transport.ts   # HTTP relay client (cross-machine)
│   ├── cli.ts                # CLI entry point
│   └── index.ts              # Library exports
└── tests/
    ├── store.test.ts         # Message store tests
    └── router.test.ts        # Routing logic tests

Design decisions:

• File-based, not SQLite — zero native dependencies, works everywhere npm install works
• Atomic writes — write to .tmp then rename, prevents partial reads
• No central daemon — each session is independent, shared state via filesystem
• PID + heartbeat validation — stale sessions auto-cleaned on next listSessions()
• Timestamp-prefixed filenames — messages delivered in send order

Security

• Input validation — session names must match ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$ to prevent path traversal
• Message size limit — 1 MB max per message to prevent disk exhaustion
• Rate limiting — 60 messages per minute per session
• Path confinement — all file operations verified to stay within ~/.claude-relay/
• No credentials stored — API keys are passed via environment variables, never written to disk

Troubleshooting

Session not appearing in relay_sessions:

• The session must have the relay MCP server configured in settings.json
• Check that the session has been active within the last 2 minutes (heartbeat window)
• Run claude-relay status from your terminal to see raw session data

Messages not arriving:

• Verify both sessions use the same ~/.claude-relay/ directory
• Check that the recipient session name matches exactly (case-sensitive)
• Messages are consumed on read — each message is delivered exactly once

Remote relay not connecting:

• Verify RELAY_REMOTE_URL and RELAY_API_KEY are set in the MCP config
• Test with claude-relay status — it will show if remote is configured
• Check that the relay server is reachable: curl https://your-server.com/relay/health

License

MIT