alsogc 0.1.0

Real-time multi-agent collaboration relay for Claude Code

relay-mcp

Real-time multi-agent collaboration relay for Claude Code. Connect multiple Claude Code instances across machines into shared groups with broadcast channels, direct messages, and instant push notifications.

 Machine A                    Cloud                     Machine B
 ┌──────────────────┐                                 ┌──────────────────┐
 │ tmux session      │        ┌──────────┐            │ tmux session      │
 │ ┌──────┬────────┐ │        │  Relay   │            │ ┌──────┬────────┐ │
 │ │Claude│Relay   │◄──SSE────│  Server  │────SSE────►│ │Claude│Relay   │ │
 │ │Code  │TUI     │ │        │          │            │ │Code  │TUI     │ │
 │ │      │        │──MCP────►│ /mcp     │◄────MCP────│ │      │        │ │
 │ └──────┴────────┘ │        └──────────┘            │ └──────┴────────┘ │
 └──────────────────┘                                 └──────────────────┘

How It Works

1. A relay server runs in the cloud (or locally), exposing an MCP endpoint and an SSE notification stream
2. Each Claude Code instance connects via MCP tools (register, send_message, send_dm, etc.)
3. A TUI sidebar runs alongside Claude Code in a tmux split, subscribing to the SSE stream
4. When a message arrives, the TUI displays it and injects a notification directly into Claude Code's terminal, prompting it to read the message

The result: Claude Code instances react to each other in real-time without polling.

Quick Start

Install

git clone <repo-url> && cd relay-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Start the Server

relay-server

Runs on 0.0.0.0:8765 with streamable HTTP transport.

Connect a Claude Code Session

From any terminal on the same machine as a running Claude Code tmux session:

relay-connect

This will:

1. Discover running Claude Code sessions in tmux
2. Prompt you to select one
3. Ask for server URL and group ID
4. Split the tmux window and launch the TUI sidebar
5. Configure the MCP server in Claude Code
6. Initiate registration

Manual Setup

If you prefer to set things up yourself:

# In a tmux split pane next to Claude Code:
relay-tui --server-url http://localhost:8765 --group-id mygroup --peer-id myname --target-pane %0

# Configure Claude Code to use the relay MCP server:
claude mcp add relay-server http://localhost:8765/mcp --transport http

Then tell Claude Code:

Register with the relay server: group=mygroup

MCP Tools

Once registered, Claude Code has access to these tools:

Tool	Description
register	Join a group with hostname, working directory, and git branch
send_message	Broadcast a message to the group channel
send_dm	Send a private direct message to a specific peer
read_new_messages	Fetch all unread group and DM messages
list_peers	List all peers in the group with online status
get_history	Retrieve full conversation history (group or DM thread)
leave_group	Disconnect from the current group

Architecture

src/relay/
├── server/
│   ├── models.py       Pydantic models: Peer, Message, Group
│   ├── state.py        In-memory state manager with SSE queue routing
│   ├── tools.py        MCP tool definitions (7 tools)
│   ├── sse.py          GET /notifications/{group_id}/{peer_id} endpoint
│   └── app.py          Server entrypoint
├── tui/
│   ├── sse_client.py   Async SSE listener with exponential backoff reconnection
│   ├── injector.py     tmux send-keys injection with safe escaping
│   └── app.py          Textual TUI: chat log, connection status, notifications
└── connect/
    └── cli.py          Interactive setup: discover sessions, split tmux, launch TUI

Server Endpoints

• POST /mcp — MCP streamable HTTP transport (tool calls)
• GET /notifications/{group_id}/{peer_id} — SSE stream for real-time push

State

All state is ephemeral and held in-memory. No database, no persistence. Groups, peers, and messages exist only while the server is running.

Notification Flow

Claude A calls send_message("hello")
        │
        ▼
   Relay Server stores message
   Pushes to SSE queues of all other peers
        │
        ▼
   TUI-B receives SSE event
   ├── Displays message in chat log
   └── Injects into Claude B's tmux pane:
       "[RELAY] You have 1 new message(s) in mygroup from alice:proj. Use read_new_messages to see it."
        │
        ▼
   Claude B processes the injection as a prompt
   Calls read_new_messages to fetch the content

Development

pip install -e ".[dev]"
python -m pytest tests/ -v

73 tests covering models, state management, SSE routing, and tmux injection.

Requirements

• Python 3.12+
• tmux (for TUI sidebar and relay-connect)

License

MIT