alsogc 0.1.0__tar.gz

alsogc-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__relay-server__read_new_messages",
+      "mcp__relay-server__list_peers",
+      "mcp__relay-server__send_message"
+    ]
+  }
+}

alsogc-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

alsogc-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+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

alsogc-0.1.0/README.md

@@ -0,0 +1,152 @@
+# 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

alsogc-0.1.0/modal_app.py

@@ -0,0 +1,31 @@
+import modal
+
+image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .pip_install(
+        "fastmcp>=2.14.5",
+        "sse-starlette>=3.2.0",
+        "httpx>=0.28.0",
+        "uvicorn>=0.34.0",
+        "pydantic>=2.10.0",
+        "clickhouse-connect>=0.8.0",
+        "bcrypt>=4.0.0",
+    )
+    .env({"PYTHONPATH": "/root/src"})
+    .add_local_dir("src", remote_path="/root/src")
+)
+
+app = modal.App("relay-server", image=image)
+
+
+@app.function(
+    timeout=86400,
+    scaledown_window=300,
+    secrets=[modal.Secret.from_name("clickhouse-creds")],
+)
+@modal.concurrent(max_inputs=1000)
+@modal.asgi_app(custom_domains=["alsoml.com"])
+def web():
+    from relay.server.app import create_app
+
+    return create_app()

alsogc-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "alsogc"
+version = "0.1.0"
+description = "Real-time multi-agent collaboration relay for Claude Code"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+keywords = ["mcp", "claude", "relay", "multi-agent", "collaboration"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "fastmcp>=2.14.5",
+    "sse-starlette>=3.2.0",
+    "textual>=7.5.0",
+    "httpx>=0.28.0",
+    "httpx-sse>=0.4.3",
+    "uvicorn>=0.34.0",
+    "pydantic>=2.10.0",
+    "pip>=26.0.1",
+    "clickhouse-connect>=0.8.0",
+    "bcrypt>=4.0.0",
+    "InquirerPy>=0.3.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+]
+
+[project.scripts]
+relay-server = "relay.server.app:main"
+relay-tui = "relay.tui.app:main"
+alsogc = "relay.connect.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/relay"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100