How do I use claude-ipc-broker?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-ipc-broker Tell the backend peer to run the database migrations" 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.

claude-ipc-broker

A message broker that lets multiple Claude Code terminals talk to each other. Includes a real-time web dashboard where you can watch and send commands to any connected session.

Works across terminals on the same machine or across different PCs on a network.

What it does

Peer registry -- each Claude session registers with a role (e.g. "backend", "linux-client") so everyone knows who's who
Command system -- send orders to specific sessions by role, they execute and report back
Channels -- named message streams for broadcasting data between sessions
Signals -- one-shot events with wait/notify for coordination timing
Web dashboard -- real-time UI showing all peers, messages, commands, and activity
Dual authority -- both a Claude orchestrator AND a human from the dashboard can give orders

Install

1. Clone and install dependencies

git clone <repo-url> claude-ipc-broker
cd claude-ipc-broker
npm install

2. Start the broker

node index.js

Runs on http://0.0.0.0:9100 by default. Change with flags:

node index.js --port 8080 --host 127.0.0.1

3. Open the dashboard

Go to http://localhost:9100/dashboard in your browser.

4. Configure Claude Code (MCP)

Add the broker as an MCP server so Claude gets native tools. Pick one of these options:

Option A: Project-level (just this project)

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "claude-ipc": {
      "type": "sse",
      "url": "http://localhost:9100/mcp/sse"
    }
  }
}

Option B: Global (all projects)

Add to ~/.claude/settings.json under mcpServers:

{
  "mcpServers": {
    "claude-ipc": {
      "type": "sse",
      "url": "http://localhost:9100/mcp/sse"
    }
  }
}

Option C: Cross-PC

Run the broker on one machine, point other machines to its IP:

{
  "mcpServers": {
    "claude-ipc": {
      "type": "sse",
      "url": "http://192.168.1.100:9100/mcp/sse"
    }
  }
}

5. Verify

Open a Claude Code terminal and say:

"Connect to the IPC broker"

Claude will automatically discover who's online and ask you what role this session should play.

Usage

Quick start -- just talk to Claude

Once the MCP is configured, you don't need to remember any tool names. Just tell Claude what you want in plain English:

You say	Claude does
"Connect to the IPC broker"	Calls `connect()`, shows who's online, asks your role
"Who else is online?"	Calls `list_peers()`
"Tell the backend to start the server"	Calls `send_command("backend", "start_server")`
"Wait for a command"	Calls `wait_for_command()`
"Signal that the server is ready"	Calls `signal("server_ready")`
"Wait until the server is ready"	Calls `wait_for_signal("server_ready")`

MCP tools reference

These tools are available to Claude when connected:

Tool	Purpose
`connect()`	Discover peers + register this session
`connect(role, capabilities)`	Register with a specific role
`my_info()`	Show this session's ID and role
`list_peers()`	See who's online
`send_command(target, action, params)`	Send an order to a peer by role
`wait_for_command(timeout)`	Block until a command arrives
`ack_command(id, result)`	Report command completion
`send_message(channel, message)`	Post to a message channel
`read_messages(channel, since_id)`	Read from a channel
`signal(name, data)`	Emit a named event
`wait_for_signal(name, timeout)`	Block until an event fires
`broker_status()`	Full broker state
`reset_broker()`	Clear everything

HTTP API reference

Everything Claude can do via MCP, you can also do with curl or any HTTP client.

Peers:

# Discover who's online
curl http://localhost:9100/peers/discover

# Register
curl -X POST http://localhost:9100/peers/connect \
  -H 'Content-Type: application/json' \
  -d '{"role":"backend","capabilities":["tcp","server"]}'

# List all
curl http://localhost:9100/peers

Commands:

# Send a command (as the human)
curl -X POST http://localhost:9100/commands/send \
  -H 'Content-Type: application/json' \
  -d '{"from":"human","target":"backend","action":"start_server","params":{"port":7400}}'

# Check commands for a peer
curl http://localhost:9100/commands/<peer-id>

# Wait for a command (long-poll)
curl http://localhost:9100/commands/<peer-id>/wait?timeout=30000

# Acknowledge
curl -X POST http://localhost:9100/commands/<command-id>/ack \
  -H 'Content-Type: application/json' \
  -d '{"result":{"status":"ok"}}'

Channels:

# Send message
curl -X POST http://localhost:9100/channels/results/send \
  -H 'Content-Type: application/json' \
  -d '{"test":"handshake","status":"pass"}'

# Read messages
curl http://localhost:9100/channels/results/messages

# Read only new messages
curl http://localhost:9100/channels/results/messages?since=5

Signals:

# Emit
curl -X POST http://localhost:9100/signals/server_ready \
  -H 'Content-Type: application/json' \
  -d '{"data":{"port":7400}}'

# Wait (long-poll)
curl http://localhost:9100/signals/server_ready/wait?timeout=30000

# Check without waiting
curl http://localhost:9100/signals/server_ready

System:

curl http://localhost:9100/status    # Full state
curl -X POST http://localhost:9100/reset  # Clear everything

Dashboard

The web dashboard at http://localhost:9100/dashboard shows:

Peers -- who's connected, their roles and capabilities
Channels -- message streams (click to inspect)
Signals -- emitted events with data
Live Activity -- real-time feed of everything happening
Command Center -- send commands to any peer, see pending/acked status

The dashboard updates in real-time via Server-Sent Events. No polling, no refresh needed.

Example: 4-session cross-platform test

Terminal 1 (start broker):
  $ node index.js

Terminal 2 (orchestrator):
  $ claude
  > "Connect to the IPC broker as the orchestrator"

Terminal 3 (linux client):
  $ claude
  > "Connect to the IPC broker"
  Claude asks: "What role?" -> "linux-client"

Terminal 4 (backend server):
  $ claude
  > "Connect to the IPC broker"
  Claude asks: "What role?" -> "backend"

Dashboard (browser):
  Open http://localhost:9100/dashboard
  Select target: "backend"
  Action: "start_server"
  Params: {"port": 7400}
  Click Send

  -> Backend Claude receives the command, starts the server, acks.

  Select target: "linux-client"
  Action: "connect_and_test"
  Params: {"ip": "localhost", "port": 7400}
  Click Send

  -> Linux client Claude connects, runs test, acks with results.

  All activity visible in real-time on the dashboard.

Architecture

                    +---------------------------+
                    |      BROKER (Node.js)     |
                    |                           |
                    |  Peers    - registry      |
                    |  Commands - per-peer inbox |
                    |  Channels - msg streams   |
                    |  Signals  - one-shot      |
                    +----------+----------------+
                               |
          +--------------------+--------------------+
          |                    |                     |
   +------+------+     +------+------+      +-------+------+
   | Claude A    |     | Claude B    |      |  Dashboard   |
   | MCP (SSE)   |     | MCP (SSE)   |      |  Browser     |
   | orchestrator|     | linux-client|      |  human ctrl  |
   +-------------+     +-------------+      +--------------+

The broker runs as a standalone HTTP server. Claude Code connects via MCP (SSE transport). The dashboard connects via Server-Sent Events. Commands, messages, and signals all flow through the broker.

Tests

npm test

Runs 46 tests covering peers, discovery, commands, channels, signals, and reset.

License

MIT

claude-ipc-broker

claude-ipc-broker

What it does

Install

1. Clone and install dependencies

2. Start the broker

3. Open the dashboard

4. Configure Claude Code (MCP)

Option A: Project-level (just this project)

Option B: Global (all projects)

Option C: Cross-PC

5. Verify

Usage

Quick start -- just talk to Claude

MCP tools reference

HTTP API reference

Dashboard

Example: 4-session cross-platform test

Architecture

Tests

License

Resources

Related MCP Connectors