AI-Connect

MCP-based communication bridge between AI coding assistants across different machines.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Mini-PC (192.168.0.252)                      │
│                    Bridge Server (24/7)                         │
│                                                                 │
│  ┌───────────────────┐          ┌───────────────────┐           │
│  │  MCP HTTP Server  │◄────────►│  Bridge Server    │           │
│  │  Peer: "mini"     │ WebSocket│  Port 9999        │           │
│  │  (localhost:9998) │          │                   │           │
│  └───────────────────┘          └───────────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                                         ▲
                                         │ WebSocket (remote)
                                         │
                                 ┌───────┴───────┐
                                 │ Main Machine  │
                                 │ (WSL)         │
                                 │               │
                                 │ MCP HTTP      │
                                 │ Server        │
                                 │ Peer: "Aragon"│
                                 └───────────────┘

Features

Multi-Agent Communication: AI assistants can exchange messages across machines
Salomo Principle: Multi-agent consensus for better decisions (AIfred/Sokrates/Salomo)
SSE Transport: Stable HTTP/SSE connection instead of STDIO
Offline Messages: Messages are stored until the recipient comes online
Project-based Peer Names: e.g., "Aragon (myproject)" or "mini (AI-Connect)"

Note: This is an early/rough implementation. It works, but has limitations - see Current Limitations below.

Why This Exists

After extensive research, we found no existing solution that allows AI models to directly send messages to each other and coordinate autonomously - in a simple, network-capable way where the AIs themselves decide when to communicate.

There are multi-agent frameworks (where you programmatically define agents in code) and orchestration tools (where a human or central controller assigns tasks). But nothing that lets multiple interactive Claude Code sessions talk to each other peer-to-peer across different machines, with the AIs deciding themselves when to ask for help or offer advice.

AI-Connect fills this gap. It's simple, network-capable, and works. But it comes with limitations due to Claude Code's architecture.

Use Cases

Code review: One Claude works on implementation, another reviews critically
Getting unstuck: When one Claude hits a wall, ask another for a fresh perspective
Client-Server setups: Configuring distributed systems where server runs on one machine, client on another - the Claude instances can coordinate configs, check what software needs to be installed where, and keep everything in sync without manual copy-paste between sessions
Multi-machine deployments: Any scenario where you're working on related tasks across different computers

Concept

Bridge Server: Runs 24/7 on a dedicated machine, routes messages between peers (WebSocket, port 9999)
MCP HTTP Server: Runs on every machine where Claude Code should communicate (SSE, port 9998)
Persistent Connection: Each MCP HTTP Server maintains a permanent WebSocket connection to the Bridge Server

Important: The Bridge Server machine also needs the MCP HTTP Server if you want to run Claude Code there!

┌─────────────────────────────────────────┐
│  Bridge Machine (e.g., Mini-PC)         │
│                                         │
│  ┌─────────────────┐  ┌──────────────┐  │
│  │ Bridge Server   │  │ MCP HTTP     │  │
│  │ Port 9999       │◄─┤ Server       │  │
│  │ (routes msgs)   │  │ Port 9998    │  │
│  └────────▲────────┘  └──────▲───────┘  │
│           │                  │          │
│           │                  └── Claude Code (local)
│           │                             │
└───────────┼─────────────────────────────┘
            │ WebSocket
            │
┌───────────┼─────────────────────────────┐
│  Other Machine (e.g., Workstation)      │
│           │                             │
│  ┌────────┴────────┐                    │
│  │ MCP HTTP Server │◄── Claude Code     │
│  │ Port 9998       │                    │
│  └─────────────────┘                    │
└─────────────────────────────────────────┘

Quick Setup: Bridge Server

The Bridge Server runs on a dedicated machine (e.g., Mini-PC, Raspberry Pi, home server) and accepts connections from all clients.

# 1. Clone the project
cd ~/projects
git clone git@github.com:Peuqui/AI-Connect.git
cd AI-Connect

# 2. Create virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install fastmcp websockets aiosqlite pyyaml

# 3. Set up Bridge Server as systemd service
sudo tee /etc/systemd/system/ai-connect.service << 'EOF'
[Unit]
Description=AI-Connect Bridge Server
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/AI-Connect
ExecStart=/path/to/AI-Connect/venv/bin/python -m server.main
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 4. Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable ai-connect
sudo systemctl start ai-connect

# 5. Check status
sudo systemctl status ai-connect

Quick Setup: MCP Client (each machine)

Every machine that should communicate via the bridge needs the MCP Client.

1. Clone project and install dependencies

cd ~/projects
git clone git@github.com:Peuqui/AI-Connect.git
cd AI-Connect

python3 -m venv venv
source venv/bin/activate
pip install fastmcp websockets aiosqlite pyyaml

2. Create config

IMPORTANT: host must be the IP of the Bridge Server, NOT 0.0.0.0!

mkdir -p ~/.config/ai-connect
cat > ~/.config/ai-connect/config.yaml << 'EOF'
bridge:
  host: "192.168.0.252"  # IP of the Bridge Server
  port: 9999

peer:
  name: "YOUR_PEER_NAME"  # e.g., "dev", "mini", "laptop"
  auto_connect: true
EOF

3. Set up MCP HTTP Server as service

# Create systemd user service
mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/ai-connect-mcp.service << 'EOF'
[Unit]
Description=AI-Connect MCP HTTP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/AI-Connect
ExecStart=/path/to/AI-Connect/venv/bin/python -m client.http_server
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target
EOF

# Enable and start the service
systemctl --user daemon-reload
systemctl --user enable ai-connect-mcp.service
systemctl --user start ai-connect-mcp.service

4. Register MCP Server in VSCode/Claude Code

Create/edit ~/.vscode-server/data/User/mcp.json (or ~/.config/Code/User/mcp.json):

{
  "servers": {
    "ai-connect": {
      "type": "sse",
      "url": "http://127.0.0.1:9998/sse"
    }
  }
}

5. Claude Code Permissions (optional)

To skip tool confirmation dialogs, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__ai-connect__peer_list",
      "mcp__ai-connect__peer_send",
      "mcp__ai-connect__peer_read",
      "mcp__ai-connect__peer_history",
      "mcp__ai-connect__peer_context",
      "mcp__ai-connect__peer_status",
      "mcp__ai-connect__peer_wait"
    ]
  }
}

6. Restart Claude Code

After configuration, restart VS Code / Claude Code to load the MCP Client.

Usage

Available MCP Tools

Tool	Description
`peer_list`	Shows all online peers
`peer_send`	Sends message to peer (or `*` for broadcast)
`peer_read`	Reads received messages
`peer_wait`	Waits for new message (with timeout)
`peer_history`	Shows chat history with peer
`peer_context`	Shares file context with other peers
`peer_status`	Shows connection status to Bridge Server

Examples

Check status:

"Show me the AI-Connect status"

Show peers:

"Who is currently online?"

Send message:

"Ask mini what they think about this approach"

With context:

"Send mini the code from api.py lines 42-58"

Read messages:

"Did anyone write to me?"

Broadcast:

"Ask everyone if someone has time for a review"

Architecture

AI-Connect/
├── server/                 # Bridge Server (runs on dedicated machine)
│   ├── main.py             # Entry point
│   ├── websocket_server.py # WebSocket handler
│   ├── peer_registry.py    # Peer management (online/offline)
│   └── message_store.py    # SQLite history + offline delivery
│
├── client/                 # MCP Client (runs on each machine)
│   ├── http_server.py      # FastMCP HTTP/SSE Server
│   ├── server.py           # FastMCP STDIO Server (alternative)
│   ├── bridge_client.py    # Persistent WebSocket connection
│   └── tools.py            # MCP Tools implementation
│
├── skills/                 # Claude Code Skills
│   └── advisor/            # Advisor mode skill
│       └── SKILL.md
│
└── config.yaml             # Example configuration

Key Details

SSE Transport: The MCP HTTP Server uses Server-Sent Events (SSE) for stable connections to VSCode/Claude Code.
Project-based Peer Names: Peers are registered as Name (Project), e.g., "Aragon (myproject)" or "mini (AI-Connect)".
Unique Client IDs: With multiple instances, the PID is appended, e.g., "Aragon#12345 (myproject)".
Offline Messages: When a peer is offline, the Bridge Server stores messages in SQLite and delivers them when the peer comes back online.
Heartbeat: Client sends ping every 25 seconds, server removes inactive peers after 60 seconds.

Salomo Principle (Multi-Agent Consensus)

AI-Connect enables the Salomo Principle for better decisions through multi-agent consensus.

Roles

Role	Description
AIfred	The one with the user's task (main worker, thesis)
Sokrates	Idle Claude being consulted (critic, antithesis)
Salomo	Third Claude in case of disagreement (judge, synthesis)

Workflow

AIfred works on task, encounters important decision
Shares context via peer_context + question via peer_send
Sokrates analyzes critically, shows alternatives
On consensus: Continue. On disagreement: Salomo decides

Voting

Majority (2/3) for normal decisions
Unanimous (3/3) for critical architecture changes
Tags: [LGTM] = approval, [CONTINUE] = not finished yet

`/advisor` Skill

The skill skills/advisor/SKILL.md activates advisor mode:

# Install skill in Claude Code
mkdir -p ~/.claude/skills/advisor
cp skills/advisor/SKILL.md ~/.claude/skills/advisor/

Then activate advisor mode with /advisor. The Claude instance enters a polling loop, checking for incoming messages every 2 seconds. Important: All sent and received messages are displayed to the user - you can read the full conversation between the AI instances.

Troubleshooting

Check Bridge Server

# Service status
sudo systemctl status ai-connect

# Live logs
journalctl -u ai-connect -f

# Check port
ss -tlnp | grep 9999

Test connection

# From any machine
nc -zv 192.168.0.252 9999

Check MCP Client

# List MCP servers
claude mcp list

# Client logs
tail -f ~/.config/ai-connect/mcp.log

Common Problems

Problem	Cause	Solution
"Not connected"	Wrong host config	`host` must be Bridge Server IP, not `0.0.0.0`
Peers don't see each other	MCP Client not persistent	Update code (`git pull`), restart VS Code
Connection refused	Bridge Server not running	`sudo systemctl start ai-connect`
Timeout	Firewall blocking	Open port 9999 in firewall

Config Reference

~/.config/ai-connect/config.yaml

bridge:
  host: "192.168.0.252"  # IP of Bridge Server (NOT 0.0.0.0!)
  port: 9999             # Port of Bridge Server

peer:
  name: "dev"            # Unique name of this peer
  auto_connect: true     # Auto-connect on start

Environment Variables

Variable	Description
`AI_CONNECT_PEER_NAME`	Overrides `peer.name` from config

Current Limitations

This is an early/rough implementation. It works, but is far from elegant:

Polling required: Claude Code has no external trigger mechanism. To receive messages, an instance must actively poll via peer_read. The /advisor skill does this with a 2-second loop - like a car burning fuel while idling. It works, but wastes tokens doing nothing useful.
No external triggers possible: We thoroughly investigated Claude Code's hooks system. The UserPromptSubmit hook can inject context, but only when the user sends a message - so you'd still need to type something for messages to arrive. There is simply no way to externally interrupt or signal a running Claude Code session. This is a fundamental limitation of the current Claude Code architecture.
No push notifications: When a message arrives, there's no way to notify a working Claude instance. The receiving instance must be idle and polling.
Manual context sharing: You need to explicitly use peer_context to share code. There's no automatic awareness of what other instances are working on.

The Core Problem

Until Claude Code (or Anthropic) implements external trigger/interrupt capabilities, true real-time multi-agent collaboration remains a workaround at best. The polling approach works, but it's not elegant - and it costs tokens for nothing.

Pull requests welcome if you find a better approach!

License

MIT

AI-Connect

AI-Connect

Overview

Features

Why This Exists

Use Cases

Concept

Quick Setup: Bridge Server

Quick Setup: MCP Client (each machine)

1. Clone project and install dependencies

2. Create config

3. Set up MCP HTTP Server as service

4. Register MCP Server in VSCode/Claude Code

5. Claude Code Permissions (optional)

6. Restart Claude Code

Usage

Available MCP Tools

Examples

Architecture

Key Details

Salomo Principle (Multi-Agent Consensus)

Roles

Workflow

Voting

/advisor Skill

Troubleshooting

Check Bridge Server

Test connection

Check MCP Client

Common Problems

Config Reference

~/.config/ai-connect/config.yaml

Environment Variables

Current Limitations

The Core Problem

License

Reviews

`/advisor` Skill