Metadata-Version: 2.4
Name: alsogc
Version: 0.1.0
Summary: Real-time multi-agent collaboration relay for Claude Code
License-Expression: MIT
Keywords: claude,collaboration,mcp,multi-agent,relay
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: clickhouse-connect>=0.8.0
Requires-Dist: fastmcp>=2.14.5
Requires-Dist: httpx-sse>=0.4.3
Requires-Dist: httpx>=0.28.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: pip>=26.0.1
Requires-Dist: pydantic>=2.10.0
Requires-Dist: sse-starlette>=3.2.0
Requires-Dist: textual>=7.5.0
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

### Start the Server

```bash
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:

```bash
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:

```bash
# 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` &mdash; MCP streamable HTTP transport (tool calls)
- `GET /notifications/{group_id}/{peer_id}` &mdash; 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

```bash
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
