Ai Connect

🚀 AI-Connect

AI-Connect is an MCP-based communication bridge that enables AI coding assistants to communicate across different machines. It fills the gap in allowing AI models to directly exchange messages and coordinate autonomously.

🚀 Quick Start

Bridge Server Setup

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

MCP Client Setup (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.

✨ 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)".

⚠️ Important Note

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

📚 Documentation

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       │                    │
│  └─────────────────┘                    │
└─────────────────────────────────────────┘

Usage

Available MCP Tools

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

Workflow

1. AIfred works on task, encounters important decision.
2. Shares context via peer_context + question via peer_send.
3. Sokrates analyzes critically, shows alternatives.
4. 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

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

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

Star History