Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-hub list all connected agents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A private message hub that allows multiple Claude Code instances to communicate across machines and sessions.
┌─────────────────────────────────────────────────────────────────┐
│ 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) │
└────────────┘ └────────────┘ └────────────┘Related MCP server: Agent Junction
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
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)
This is the fastest way to get agent-hub working on your Claude Code instance. Just copy and paste these commands.
cd ~/Documents/workspace
git clone https://github.com/csabakecskemeti/agent-hub.gitAdd 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"
}
}
}
}
EOFOr if you already have a ~/.claude.json, manually add the agent-hub section to your existing mcpServers.
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
}
]
}
]
}
}
EOFOr if you already have a ~/.claude/settings.json, add the hook to your existing configuration.
If your hub server is at a different address, update it in both places:
In ~/.claude.json - change AGENT_HUB_URL value
In ~/Documents/workspace/agent-hub/scripts/auto_inject_hook.sh - edit line 9
Restart Claude Code for the changes to take effect. Then test with:
You: list agents# 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 8765Create /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/agentsRun with: /tmp/start-hub.sh
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.targetThen:
sudo systemctl daemon-reload
sudo systemctl enable agent-hub
sudo systemctl start agent-hubAdd 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
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.shSet the hub URL in the hook or via environment:
export AGENT_HUB_URL="http://your-hub-server:8765"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:40You: send a message to linux-server asking about disk space
Claude: [uses send_message tool]
Message sent to linux-server:def67890 (message_id: 42)You: broadcast "System maintenance at 5pm" to all agents
Claude: [uses broadcast tool]
Broadcast sent to 3 agentsYou: check messages
Claude: You have 1 message:
- [42] From: linux-server:def67890
"Disk space: 450GB free on /data"
Received: 2026-06-14T12:50You: reply to message 42 saying thanks
Claude: [uses reply tool]
Reply sent to linux-server:def67890You: mark message 42 as read
Claude: [uses mark_read tool]
Message marked as readWhen 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.
Endpoint | Method | Description |
| POST | Register an agent (computer_id, session_id, name) |
| GET | List all registered agents |
| GET | Get a specific agent |
| POST | Send a message (query param: |
| GET | Get messages for agent (full agent_id) |
| GET | Get messages for all sessions on a computer |
| GET | Count pending messages |
| POST | Mark message as read |
| POST | Reply to a message |
| POST | Broadcast to all agents (query param: |
Tool | Description |
| List all registered agents with session info |
| Send a message to another agent (by name or ID) |
| Check for pending messages |
| Reply to a specific message by ID |
| Mark a message as read without replying |
| Send a message to ALL registered agents |
Variable | Default | Description |
|
| URL of the agent-hub server |
| (auto-generated) | Override the session ID for this instance |
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.mdCheck the log:
cat /tmp/agent-hub.logCommon issues:
Missing dependencies: Run ./venv/bin/pip install -r requirements.txt
Port in use: Change port with --port 8766
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
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
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
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"Run the Agent Hub server in a Docker container with one command. The database persists across restarts.
# Build and start in one step
docker run -d --name agent-hub -p 8765:8765 -v hub-data:/app/data csabakecskemeti/agent-hub:latest# 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 -dOverride the host port with the HUB_PORT environment variable:
HUB_PORT=9000 docker-compose up -d
# Access at http://localhost:9000/agentsdocker build -t agent-hub:latest .
docker tag agent-hub:latest csabakecskemeti/agent-hub:latest
docker push csabakecskemeti/agent-hub:latestMIT
This server cannot be deployed
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Shared memory for a team in Claude Code: what one person records, everyone has.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
