comsnet-mcp

Give Claude Code (or any MCP client) a seat at the Pi agent table.

comsnet-mcp is a stdio MCP server that registers your CLI coding session as a peer on a coms-net hub: it can list peers, send work to them, read its inbox, and reply — with the same identity model the Pi agents use.

┌──────────────┐   MCP (stdio)   ┌──────────────┐   HTTP/SSE   ┌────────────┐
│ Claude Code  │ ──────────────▶ │ comsnet-mcp  │ ───────────▶ │ coms-net   │
│ (this repo)  │ ◀────────────── │   bridge     │ ◀─────────── │    hub     │
└──────────────┘                 └──────────────┘              └────────────┘
                                                                     ▲
                                                          Pi agents, other
                                                          CLI peers, workers

Why

Multi-agent setups usually stop at "one orchestrator, many subprocesses". Once you run several interactive tools side by side — Claude Code in one pane, Pi agents in another, a headless worker in a third — they can't see each other.

coms-net already solves that for Pi. This bridge makes the same hub reachable from any MCP client, so a Claude Code session becomes an addressable peer instead of an island.

Built on coms-net by IndyDevDan (MIT). The hub, its protocol and the Pi client are his work; this repository is the MCP-side bridge, written independently against the same wire protocol. See NOTICE for the full lineage.

Watch the 64-second intro: ComsNet MCP — Mira introduces the bridge.

Related MCP server: technocore-mcp

Status

Early. The bridge is in daily use on a private fleet; this repository is the extracted, dependency-free public cut. Not yet published to npm — run from source, or install locally per the Install section below.

Install

Requires Bun — src/lib/coms-net-store.ts uses bun:sqlite, so this package is Bun-only (no Node compatibility).

bunx comsnet-mcp --server-url http://127.0.0.1:<hub-port> --auth-token <token>
# or install the `comsnet-mcp` binary globally
bun add -g comsnet-mcp

Not published to the npm registry yet (see Status above). Until it is, run bun link from a clone of this repo to get the same comsnet-mcp bin on PATH, or invoke bun src/mcp.ts directly as shown throughout this README.

What you need

Two pieces, and this repository is only the second one:

1. A coms-net hub — the upstream server (scripts/coms-net-server.ts in disler/pi-vs-claude-code). It owns the message store and hands out server.json + a token.

2. This bridge — the MCP side.

If you never ran the Pi toolchain, you do not need it: start the hub, then point the bridge at it explicitly instead of relying on discovery:

claude mcp add comsnet -- bun /path/to/comsnet-mcp/src/mcp.ts \
  --server-url http://127.0.0.1:<hub-port> --auth-token <token-from-hub>

Your CLI also has to be able to host an MCP server. Claude Code, Codex, Cursor, Zed and Windsurf can; a plain shell script cannot — for those, run src/headless-peer.ts as a worker process instead, or talk to the hub's HTTP API directly.

Two-minute setup (no Pi required)

# 1. the hub lives upstream — clone it once
git clone https://github.com/disler/pi-vs-claude-code && cd pi-vs-claude-code

# 2. start a hub. It prints the URL and the path to the token file
#    (it never prints the token itself).
PI_COMS_NET_PROJECT=default bun scripts/coms-net-server.ts
#    -> coms-net: listening on http://127.0.0.1:8791
#    -> server.secret.json=~/.pi/coms-net/projects/default/server.secret.json (chmod 0600)

# 3. in another terminal, grab the token and register the bridge
export HUB=http://127.0.0.1:8791
export TOKEN=$(jq -r .token ~/.pi/coms-net/projects/default/server.secret.json)
claude mcp add comsnet -- bun /path/to/comsnet-mcp/src/mcp.ts \
  --server-url "$HUB" --auth-token "$TOKEN"

# 4. in the session: `comsnet_list_agents` should now answer.

Running hub and bridge on the same machine with the default project? Skip step 3's flags entirely: the hub's server.json is discovered automatically.

Quick start

You need a coms-net hub running for the project you want to join (that is the upstream repository — this repo ships only the MCP side).

# 1. who am I, and which hub project am I joining?
export PI_COMS_NET_PROJECT=default        # default: "default"
export PI_COMS_AGENT_NAME=claude-code     # the name peers address you by
# optional: PI_COMS_AGENT_MODEL, PI_COMS_NET_AUTH_TOKEN

# 2. hub discovery is automatic: the bridge reads
#    ~/.pi/coms-net/projects/<project>/{server.json,server.secret.json}
#    (a restarted hub rewrites the port there and the client follows it)

# 3. register the server with your MCP client — example for Claude Code
claude mcp add comsnet -- bun /path/to/comsnet-mcp/src/mcp.ts
#    any MCP stdio client works; server name and args are up to you

Connecting a client

The bridge is a plain MCP stdio server, so any MCP-capable tool can host it. Three cases, deliberately different:

Claude Code

claude mcp add comsnet -- bun /path/to/comsnet-mcp/src/mcp.ts
# or commit a project-scoped .mcp.json:
# { "mcpServers": { "comsnet": { "command": "bun", "args": ["/path/to/comsnet-mcp/src/mcp.ts"] } } }

Codex

Codex reads its own TOML config (~/.codex/config.toml):

[mcp_servers.comsnet]
command = "bun"
args = ["/path/to/comsnet-mcp/src/mcp.ts"]
env = { PI_COMS_NET_PROJECT = "default", PI_COMS_AGENT_NAME = "codex" }

Pass --provider codex in args if you want monitors to tag the peer as Codex rather than Claude Code.

Pi

Don't use this bridge. Pi agents join coms-net natively through the coms-net.ts extension in the upstream repo — same hub, same tools, no MCP hop. Use comsnet-mcp for the clients that cannot load a Pi extension.

Do I need a squad UI / pane manager?

No. Peers are addressed by name on the hub:

comsnet_list_agents            → everyone online, with model + status
comsnet_send(target: "pi-agent") → deliver work to that name
comsnet_inbox / comsnet_respond  → the reverse direction

There is no registry to synchronise and no launcher to install. A "squad" view and a tmux/herdr pane driver are optional operator conveniences — the pane driver only matters for the headless-worker mode (src/headless-peer.ts), which needs to locate a terminal pane to nudge. Interactive MCP clients need none of that: they are already the pane.

Then, inside the session:

> use comsnet_inbox to see if anything is waiting
> use comsnet_send to ask "pi-agent" for the current GPU lane status

Tools exposed

Replies are delivered as a follow-up turn ("you were nudged") rather than by polling — see src/lib/coms-net-client.ts for the SSE stream that powers it.

Loop safety

Two mechanisms are on by default because unbounded agent-to-agent chatter is a real failure mode we hit:

• hop ceiling — forwarded conversations carry a hop counter. The hub is the enforcement point (upstream PI_COMS_NET_MAX_HOPS, default 5); this bridge carries the count and does not raise it. Set it on the hub, not here.

• reply shape guard (src/lib/output-shape.ts) — a peer reply that is structured but ends on a non-conclusion section is logged, never blocked (heuristics misjudge; a human must be able to see and fix the rule).

Repo layout

src/mcp.ts            MCP stdio server (newline-delimited JSON-RPC)
src/headless-peer.ts  non-interactive worker peer (for `claude -p` style jobs)
src/lib/              hub client: discovery, registration, heartbeat, SSE, inbox
test/                 protocol + lifetime + inbox-authority tests

Tests

bun test                  # unit suites: no network, no hub, no private paths
COMSNET_E2E=1 bun test    # + suites that need a hub checkout / live terminal fleet

32 pass / 19 skip / 0 fail on a bare checkout. See test/README.md for why the environment-dependent suites are gated.

Credits & prior art

See NOTICE. coms-net protocol © Dan Disler (MIT).

Licence

MIT — see LICENSE.