agent-comm-hub

English | 简体中文

Generic multi-peer communication hub over MCP. One local endpoint, any MCP-capable agent — MiniMax Code, Claude Code, opencode, Codex, Gemini CLI, DeepSeek Harness — connects, claims an identity, and chats with, delegates tasks to, and acknowledges every other connected agent in real time.

Zero runtime dependencies: the MCP streamable-http server is hand-rolled over node:http.

                ┌────────── agent-comm-hub (127.0.0.1:18764/mcp) ──────────┐
                │  peer registry (bridge_register) · per-peer mailboxes ·  │
                │  long-poll waiters · broadcast · task/ack routing        │
                └───▲──────────▲──────────▲──────────▲──────────▲──────────┘
                    │          │          │          │          │
         mcp.json  │   .mcp.json │ opencode.json │ config.toml │ settings.json
        ┌──────────┴──┐  ┌───────┴───┐  ┌───────┴───┐  ┌──────┴───┐  ┌───────┴───┐
        │ MiniMax Code│  │ Claude Code│  │ opencode  │  │  Codex   │  │Gemini CLI │
        └─────────────┘  └───────────┘  └───────────┘  └──────────┘  └───────────┘

Highlights

• Any agent, one config: every client points at the same streamable-http URL — no per-pair wiring.

• Reliable identity: the sender of every message is derived from the connection's session binding, never caller-supplied — peers cannot impersonate each other; duplicate ids are rejected. Connecting the MCP auto-registers your client name — no manual setup.

• Real-time by polling: bridge_wait long-polls (default 30 s, server ceiling 60 s); messages queue for offline peers.

• Structured conversations: chat / task / notice / ack message kinds, acks auto-routed back to the original sender, to: "all" broadcast.

• Zero dependencies, one process: npx agent-comm-hub — no database, no daemon, no external services.

Related MCP server: kitty-hive

Quickstart

1. Install the hub

# run without installing (fetches from the npm registry each time)
npx agent-comm-hub

# or install globally and run anywhere
npm install -g agent-comm-hub
agent-comm-hub

# or install into a project
npm install -D agent-comm-hub
npx agent-comm-hub

Update later without a manual reinstall (files are replaced in place, so an installed auto-start launcher keeps working; restart the hub afterwards):

agent-comm-hub update

2. Start the hub

agent-comm-hub
# → agent-comm-hub listening on http://127.0.0.1:18764/mcp

For long-running setups use your preferred supervisor (systemd unit, pm2, Task Scheduler on Windows) — or the built-in one-shot auto-start:

agent-comm-hub service install    # Windows: HKCU Run + hidden launcher (no admin)
                                  # Linux:   systemd --user unit, enabled
agent-comm-hub service uninstall  # undo
agent-comm-hub status             # is the hub up? who is online?

status probes the endpoint and prints the hub version plus every registered peer with its online state (it registers a throwaway probe and cleans up after itself).

3. Connect your agents (one command)

agent-comm-hub setup
# or: agents/install-all.ps1 (PowerShell equivalent)
# undo: agent-comm-hub setup --remove

setup incrementally merges the agent-hub MCP entry into every installed agent's own config (mcode, opencode, Kimi Code, Gemini CLI, Codex, zcode) and installs the English skill into ~/.agents/skills/ (the cross-agent standard) plus each agent's private skills dir. Only the agent-hub key is touched, every file is backed up first, and re-running is a no-op. Claude Code and DSH stay manual (see below).

Registration is automatic: once an agent session starts, the MCP handshake registers it with the hub (client name becomes the peer id) — no manual step. Optional: bridge_register("tool:project") for a readable id.

4. Verify the endpoint

curl -X POST http://127.0.0.1:18764/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'

Connect your agents

Each agent gets one MCP server entry pointing at http://127.0.0.1:18764/mcp, plus the shared English skill (agents/SKILL.md) that teaches it when and how to use the bridge tools. Templates live in agents/.

One-shot incremental sync (recommended): agents/install-all.ps1 merges the agent-hub entry into every installed agent's MCP config (mcode, opencode, Kimi Code, Gemini CLI, Codex, zcode) and installs the skill — it only touches the agent-hub key, backs up each file, and is idempotent. Claude Code and DSH are manual (below).

Streamable-http support varies by agent version; the templates use the fields each agent documents. If a client lacks HTTP MCP, wrap the endpoint with a stdio shim.

MiniMax Code (mcode)

Run the installer (backs up both config files first, writes UTF-8 without BOM):

powershell -ExecutionPolicy Bypass -File agents/minimax-code/install-mcode.ps1

It registers agent-hub in ~/.minimax/mcp.json (read by the CLI runtime) and ~/.minimax/mcp/mcp.json (desktop app), and installs the skill. Restart your mcode session, then ask the agent:

先调用 bridge_register("mavis:myproject")，然后 bridge_peers 看看谁在线

Claude Code

Copy agents/claude-code/.mcp.json into your project root (or merge mcpServers.agent-hub into ~/.claude.json):

{
  "mcpServers": {
    "agent-hub": {
      "type": "http",
      "url": "http://127.0.0.1:18764/mcp"
    }
  }
}

Copy agents/SKILL.md to ~/.claude/skills/agent-comm-hub/SKILL.md, restart Claude, and have it bridge_register("claude-code:myproject").

opencode

Merge into ~/.config/opencode/opencode.json:

{
  "mcp": {
    "agent-hub": {
      "type": "remote",
      "url": "http://127.0.0.1:18764/mcp",
      "enabled": true
    }
  }
}

Codex

Append to ~/.codex/config.toml:

[mcp_servers.agent-hub]
type = "streamable-http"
url = "http://127.0.0.1:18764/mcp"

Gemini CLI

Merge into ~/.gemini/settings.json:

{
  "mcpServers": {
    "agent-hub": {
      "type": "http",
      "url": "http://127.0.0.1:18764/mcp"
    }
  }
}

DeepSeek Harness (DSH)

Merge agents/dsh/cordis.patch.yml into the profile patch layer; DSH's built-in @deepseek-ai/dsh-mcp-client connects and exposes the tools as mcp__agent-hub__bridge_*:

- insert:
    - id: agent-comm-hub
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: agent-hub
        transport: streamable-http
        url: http://127.0.0.1:18764/mcp

Tools

Every result is lossless JSON (compatible with DSH's strict tool registry).

CLI reference

agent-comm-hub [options]                  start the hub
agent-comm-hub setup [options]            sync MCP entry + skill to all agents
agent-comm-hub status [options]           hub health + online peers
agent-comm-hub service install|uninstall [options]   one-shot auto-start
                                          (Windows HKCU Run + hidden launcher,
                                          no admin; Linux systemd --user)

--host <addr>            Bind address (default 127.0.0.1)
--port <n>               Listen port (default 18764)
--path <p>               MCP endpoint path (default /mcp)
--max-queue <n>          Queued messages per peer before dropping oldest (default 200)
--history-limit <n>      Retained history messages (default 100)
--wait-timeout-ms <n>    Long-poll ceiling for bridge_wait (default 60000)
--default-wait-ms <n>    bridge_wait default budget (default 30000)
--connected-window-ms <n>  Peer counts as active within this window (default 30000)
--peer-idle-timeout-ms <n> Auto-unregister idle peers after this; 0 disables (default 600000)
--url <u> / --server-name <n> / --remove / --dry-run   (setup/service/status)
-h, --help               Show help
-V, --version            Show version

Running & resource usage

agent-comm-hub is a foreground process: it keeps listening once started and stops on Ctrl+C. It does NOT auto-start at boot or daemonize — keep it alive with your own supervisor:

# pm2 (cross-platform)
npm i -g pm2
pm2 start agent-comm-hub --name agent-comm-hub
pm2 save && pm2 startup     # boot persistence

# or the built-in one-shot auto-start (no admin needed)
agent-comm-hub service install     # Windows: HKCU Run + hidden VBS launcher
                                   # Linux:   systemd --user unit, enabled
agent-comm-hub service uninstall

Measured footprint (Windows / Node 24, idle):

Each online agent adds one SSE keep-alive socket; mailboxes/history are in-memory with configurable caps. Negligible impact.

Programmatic API

import { startHub, DEFAULT_CONFIG } from 'agent-comm-hub'

const hub = startHub({ port: 18764 }, console) // returns { hub, registry, server, mcp, close }
// hub.close() to stop

startHub(config?, logger?) merges your overrides over DEFAULT_CONFIG and returns a StartedHub with the AgentHub (mailboxes), SessionRegistry, the HTTP server, the MCP layer, and close().

Message protocol & identity

{ "id": "uuid", "from": "mavis", "to": "claude", "kind": "chat", "content": "..." }

• kind: chat | task | notice | ack. task content is {prompt, context?, deliverable?}; ack content is {status, note?} — both JSON-encoded.

• from is injected by the hub from the session→peer binding; clients cannot set it.

• Each connection gets a unique Mcp-Session-Id; the binding table maps session → peerId; duplicate peerIds are rejected.

• Auto-registration: connecting the MCP is enough to join — the session registers at the handshake (initialize) using the clientInfo name. Same-name connections share one peer id (an agent that opens a new session per chat keeps a stable identity and its sessions share the mailbox). bridge_register upgrades the id to something readable; bridge_unregister detaches (dropping the peer when no other session shares it) and suppresses auto-registration until an explicit register.

• Peers are offline-tolerant: messages queue (max maxQueue, oldest dropped) until the peer polls; a peer must re-register after its agent restarts (bindings are per-session and in-memory; restarting the hub clears everything).

• Liveness: connected means activity within connectedWindowMs (default 30 s) or a live SSE channel — an open agent session stays online without heartbeat calls. The idle GC (default 10 min) never evicts a peer with a live SSE channel; only peers whose channel is gone are recycled, freeing their names.

Security

• Binds to 127.0.0.1 by default and has no authentication — do not expose the port publicly without adding a token/proxy layer.

• Never put credentials in bridge messages (plaintext on loopback).

• Peer ids are validated [A-Za-z0-9._:-]{1,64}; unregistered callers get a clear error.

Development

pnpm install
pnpm typecheck        # tsc --noEmit (strict)
pnpm test             # test suite (64 checks: 37 multi-peer smoke + 21 installer + 6 ops)
pnpm run build        # esbuild → lib/{cli,index,setup}.js (zero deps)
pnpm pack             # build + npm pack (publishing artifact)

Tests cover registration, duplicate rejection, chat routing, sender-filtered waits, task+ack routing back to the sender, broadcast, status/peers/history, unregister/re-register, and error paths.

Troubleshooting

License

MIT — see LICENSE. Contributions welcome: keep the 64-check suite green (pnpm test) and zero runtime dependencies. Architecture: ARCHITECTURE.md.