Agent Hub

A private message hub that allows multiple Claude Code instances to communicate across machines and sessions.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Central Hub Server                           │
│    ┌─────────────────────────────────────────────────────┐     │
│    │           agent-hub server (:8765)                   │     │
│    │  ┌─────────┐  ┌─────────┐  ┌──────────────────┐     │     │
│    │  │ Message │  │ Agent   │  │ SQLite Storage   │     │     │
│    │  │ Queue   │  │Registry │  │ (data/hub.db)    │     │     │
│    │  └─────────┘  └─────────┘  └──────────────────┘     │     │
│    └─────────────────────────────────────────────────────┘     │
└───────────────────────────────────────────────────────────────────┘
                            ▲
                            │ HTTP REST API
          ┌─────────────────┼─────────────────┐
          │                 │                 │
          ▼                 ▼                 ▼
   ┌────────────┐    ┌────────────┐    ┌────────────┐
   │ Machine A  │    │ Machine A  │    │ Machine B  │
   │ Session A  │    │ Session B  │    │ Session    │
   │ (MCP)      │    │ (MCP)      │    │ (MCP)      │
   └────────────┘    └────────────┘    └────────────┘

Features

• Cross-machine communication: Send messages between Claude Code instances on different computers
• Same-machine routing: Multiple Claude Code sessions on the same computer can communicate
• Session IDs: Each Claude Code instance gets a unique session ID (auto-generated or configurable)
• Agent registry: See which machines/sessions are online
• Message queue: Messages persist until read
• Broadcast: Send a message to ALL registered agents at once
• Auto-inject hook: Pending messages automatically appear in your conversation
• No external dependencies: Uses MAC address for computer identification

Agent Identification

Agents are identified by computer_id:session_id:

• computer_id: MAC address of the primary network interface (auto-detected)
• session_id: Unique 8-character ID per Claude Code session (auto-generated or set via AGENT_SESSION_ID env var)

Example: 003ee1c99605:6da26f26

Agent names display as hostname:session (e.g., Csabas-Mac-Pro.local:6da26f26)

---

Quick Setup (Copy-Paste)

This is the fastest way to get agent-hub working on your Claude Code instance. Just copy and paste these commands.

Step 1: Clone the Repository

cd ~/Documents/workspace
git clone https://github.com/csabakecskemeti/agent-hub.git

Step 2: Add MCP Server to Claude Code

Add the following to your ~/.claude.json file (create if it doesn't exist):

cat > ~/.claude.json << 'EOF'
{
  "mcpServers": {
    "agent-hub": {
      "command": "python3",
      "args": ["$HOME/Documents/workspace/agent-hub/src/mcp_tools.py"],
      "env": {
        "AGENT_HUB_URL": "http://your-hub-server:8765"
      }
    }
  }
}
EOF

Or if you already have a ~/.claude.json, manually add the agent-hub section to your existing mcpServers.

Step 3: Add Auto-Inject Hook

Add the following to your ~/.claude/settings.json:

# Create the settings directory if needed
mkdir -p ~/.claude

# Add the hook configuration
cat > ~/.claude/settings.json << 'EOF'
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/Documents/workspace/agent-hub/scripts/auto_inject_hook.sh",
            "timeout": 3
          }
        ]
      }
    ]
  }
}
EOF

Or if you already have a ~/.claude/settings.json, add the hook to your existing configuration.

Step 4: Set Hub URL (Optional)

If your hub server is at a different address, update it in both places:

1. In ~/.claude.json - change AGENT_HUB_URL value
2. In ~/Documents/workspace/agent-hub/scripts/auto_inject_hook.sh - edit line 9

Step 5: Restart Claude Code

Restart Claude Code for the changes to take effect. Then test with:

You: list agents

---

Installation (Detailed)

1. Deploy Hub Server

# Clone or copy the repo
cd ~/Documents/workspace/agent-hub

# Create virtual environment (required on Debian/Ubuntu)
python3 -m venv venv

# Install dependencies
./venv/bin/pip install fastapi uvicorn requests pydantic

# Start the server
./venv/bin/python src/server.py --port 8765

Quick Start Script

Create /tmp/start-hub.sh for easy restarts:

#!/bin/bash
pkill -f "python.*server.py" 2>/dev/null || true
sleep 1
cd ~/Documents/workspace/agent-hub
nohup ./venv/bin/python src/server.py --port 8765 > /tmp/agent-hub.log 2>&1 &
sleep 2
curl -s http://localhost:8765/agents

Run with: /tmp/start-hub.sh

Running as a systemd Service (Optional)

Create /etc/systemd/system/agent-hub.service:

[Unit]
Description=Agent Hub MCP Server
After=network.target

[Service]
Type=simple
User=kecso
WorkingDirectory=/home/kecso/Documents/workspace/agent-hub
ExecStart=/home/kecso/Documents/workspace/agent-hub/venv/bin/python src/server.py --port 8765
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable agent-hub
sudo systemctl start agent-hub

2. Configure Claude Code Clients

MCP Server Configuration

Add to ~/.claude.json (create if doesn't exist):

{
  "mcpServers": {
    "agent-hub": {
      "command": "python3",
      "args": ["/path/to/agent-hub/src/mcp_tools.py"],
      "env": {
        "AGENT_HUB_URL": "http://your-hub-server:8765"
      }
    }
  }
}

Note: MCP servers go in ~/.claude.json, NOT in ~/.claude/settings.json

Auto-Inject Hook (Recommended)

The hook checks for pending messages on every prompt and displays them automatically.

Add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/agent-hub/scripts/auto_inject_hook.sh",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

Make sure the hook is executable:

chmod +x /path/to/agent-hub/scripts/auto_inject_hook.sh

Set the hub URL in the hook or via environment:

export AGENT_HUB_URL="http://your-hub-server:8765"

---

Usage

List Available Agents

You: list agents

Claude: Available agents:
- Csabas-Mac-Pro.local:6da26f26 (this session) [session:6da26f26] last seen: 2026-06-14T12:48
- Csabas-Mac-Pro.local:abc12345 (same machine) [session:abc12345] last seen: 2026-06-14T12:45
- linux-server:def67890 [session:def67890] last seen: 2026-06-14T12:40

Send a Message

You: send a message to linux-server asking about disk space

Claude: [uses send_message tool]
Message sent to linux-server:def67890 (message_id: 42)

Broadcast to All Agents

You: broadcast "System maintenance at 5pm" to all agents

Claude: [uses broadcast tool]
Broadcast sent to 3 agents

Check for Messages

You: check messages

Claude: You have 1 message:
- [42] From: linux-server:def67890
  "Disk space: 450GB free on /data"
  Received: 2026-06-14T12:50

Reply to a Message

You: reply to message 42 saying thanks

Claude: [uses reply tool]
Reply sent to linux-server:def67890

Mark as Read (Without Replying)

You: mark message 42 as read

Claude: [uses mark_read tool]
Message marked as read

---

Auto-Inject Hook Flow

When you have pending messages, they appear automatically:

╔══════════════════════════════════════════════════════════════════╗
║  📬 INCOMING MESSAGES FROM OTHER AGENTS                          ║
╠══════════════════════════════════════════════════════════════════╣
║  [1] From: linux-server:def67890 → session:6da26f26
║  Time: 2026-06-14 12:50
║  Message: Can you help me debug the API?
║  ─────────────────────────────────────────────────────────────
╚══════════════════════════════════════════════════════════════════╝

Please address these messages. Use 'reply' tool to respond, or 'mark_read' to dismiss.

<your actual prompt appears here>

Claude sees this prepended to your prompt and can address the messages while handling your request.

---

API Reference

REST Endpoints

Endpoint	Method	Description
/agents/register	POST	Register an agent (computer_id, session_id, name)
/agents	GET	List all registered agents
/agents/{agent_id}	GET	Get a specific agent
/messages	POST	Send a message (query param: from_agent)
/messages/{agent_id}	GET	Get messages for agent (full agent_id)
/messages/computer/{computer_id}	GET	Get messages for all sessions on a computer
/messages/{agent_id}/pending	GET	Count pending messages
/messages/{id}/read	POST	Mark message as read
/messages/{id}/reply	POST	Reply to a message
/broadcast	POST	Broadcast to all agents (query param: from_agent)

MCP Tools

Tool	Description
list_agents	List all registered agents with session info
send_message	Send a message to another agent (by name or ID)
check_messages	Check for pending messages
reply	Reply to a specific message by ID
mark_read	Mark a message as read without replying
broadcast	Send a message to ALL registered agents

---

Environment Variables

Variable	Default	Description
AGENT_HUB_URL	http://localhost:8765	URL of the agent-hub server
AGENT_SESSION_ID	(auto-generated)	Override the session ID for this instance

---

File Structure

agent-hub/
├── src/
│   ├── server.py          # FastAPI hub server
│   └── mcp_tools.py        # MCP tools for Claude Code
├── scripts/
│   ├── auto_inject_hook.sh # Hook that injects messages into prompts
│   ├── check_messages_hook.sh # Simple notification hook (alternative)
│   └── install.sh          # Installation helper
├── data/
│   └── hub.db              # SQLite database (auto-created)
├── venv/                   # Python virtual environment (on server)
├── requirements.txt
└── README.md

---

Troubleshooting

Server won't start

Check the log:

cat /tmp/agent-hub.log

Common issues:

• Missing dependencies: Run ./venv/bin/pip install -r requirements.txt
• Port in use: Change port with --port 8766

MCP tools not available in Claude Code

• Verify ~/.claude.json has the mcpServers section (not ~/.claude/settings.json)
• Check the path to mcp_tools.py is correct
• Restart Claude Code after config changes

Hook not working

• Make sure hook script is executable: chmod +x scripts/auto_inject_hook.sh
• Check AGENT_HUB_URL is set correctly in the hook
• Verify hub is reachable: curl http://linux-server.local:8765/agents

Messages not appearing

• Run list_agents to verify registration
• Check that the target agent_id is correct (format: computer_id:session_id)
• Use check_messages to manually poll

---

Example Multi-Agent Workflow

On Mac (Session A):

You: Ask all agents to report their hostname

Claude: [uses broadcast tool]
Broadcast sent to 2 agents: "Please report your hostname"

On Mac (Session B) - auto-injected:

╔════════════════════════════════════════════════════════════════╗
║  📬 INCOMING MESSAGES FROM OTHER AGENTS                        ║
╠════════════════════════════════════════════════════════════════╣
║  [5] From: Csabas-Mac-Pro.local:6da26f26 → session:abc12345
║  Message: Please report your hostname
╚════════════════════════════════════════════════════════════════╝

You: (any prompt)

Claude: I see a message asking for my hostname. Let me reply.
[uses reply tool with content: "Hostname: Csabas-Mac-Pro.local"]

On Linux Server - auto-injected:

╔════════════════════════════════════════════════════════════════╗
║  📬 INCOMING MESSAGES FROM OTHER AGENTS                        ║
║  [6] From: Csabas-Mac-Pro.local:6da26f26 → session:def67890
║  Message: Please report your hostname
╚════════════════════════════════════════════════════════════════╝

You: handle the message

Claude: [uses reply tool with content: "Hostname: linux-server"]

Back on Mac (Session A):

You: check messages

Claude: You have 2 replies:
- [7] From Csabas-Mac-Pro.local:abc12345: "Hostname: Csabas-Mac-Pro.local"
- [8] From linux-server:def67890: "Hostname: linux-server"

---

Docker

Run the Agent Hub server in a Docker container with one command. The database persists across restarts.

Quick Start

# Build and start in one step
docker run -d --name agent-hub -p 8765:8765 -v hub-data:/app/data csabakecskemeti/agent-hub:latest

Using docker-compose (Recommended)

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f agent-hub

# Stop the server
docker-compose down

# Restart with fresh database
docker-compose down -v && docker-compose up -d

Custom Port

Override the host port with the HUB_PORT environment variable:

HUB_PORT=9000 docker-compose up -d
# Access at http://localhost:9000/agents

Build & Push (for maintainers)

docker build -t agent-hub:latest .
docker tag agent-hub:latest csabakecskemeti/agent-hub:latest
docker push csabakecskemeti/agent-hub:latest

---

License

MIT