Agent Comm

agent-comm

[License: MIT] [Node.js] [Tests] [MCP Tools] [REST Endpoints]

Agent-agnostic intercommunication system. Lets AI coding agents — Claude Code, Codex CLI, Gemini CLI, Aider, or any custom tool — talk to each other, share state, and coordinate work in real time.

Why

When you run multiple AI agents on the same codebase — code review in one terminal, implementation in another, testing in a third — they have no idea the others exist. They duplicate work, create merge conflicts, and miss context.

agent-comm gives them a shared communication layer:

• Agents register with a name, capabilities, and skills so others can discover them
• They discover each other by skill or tag for dynamic task routing
• They exchange messages (direct, broadcast, or channel-based) to coordinate, with importance levels (low/normal/high/urgent) and optional ack
• They poll their inbox with a blocking wait (comm_poll) so mid-flight peer signals are consumed without busy-looping
• They share state (a key-value store with atomic CAS) for locks, flags, and progress
• They log activity events (commits, test results, file edits) to a shared feed
• They detect stuck agents — alive (heartbeat OK) but not making progress
• They serialize file edits via the system-layer file-coord hook (see below) so parallel agents on shared files cannot clobber each other
• A web dashboard shows everything in real time, including an Activity Feed tab

It works with any agent that supports MCP (stdio transport) or can make HTTP requests (REST API).

Why hooks, not just MCP tools

The MCP tools (comm_state, etc.) give agents the primitives to coordinate, but they don't enforce coordination — the agent has to remember to call them. Our bench measured what happens when you rely on the model's discretion: even with strict procedural prompting, Claude follows the protocol on the first claim cycle then drifts back to "be helpful, finish the task." Soft coordination is unreliable.

The fix is a pair of PreToolUse hooks shipped in scripts/hooks/: file-coord intercepts every Edit/Write/MultiEdit and claims the file via REST POST /api/state/file-locks/<path>/cas (blocks the edit if another agent holds the lock); bash-guard intercepts git commit, git push, npm install, npm test, builds, migrations, and dev-server starts and blocks/warns when they would conflict with another session's WIP. The protocol becomes infrastructure, not a prompt the agent might ignore.

The bench's headline pilot is multi-term-commit — directly modeling the daily pain of two terminal sessions on the same project. Session A edits two files but doesn't commit. Session B then edits two other files and runs git commit -am "my work". Without the hook, B's commit silently includes A's WIP. With the hook, B's commit is blocked at the bash layer with an actionable message, and B reacts (selective staging, restore, or coordinate). Bench result:

The hook is faster AND cheaper, not just safer. Reason: when agents lack coordination on shared workspaces, they read stale state, get confused mid-task, retry, and re-think. Serializing access and surfacing the conflict early removes that wasted thinking. Run npm run setup to install both hooks automatically; see Setup → File Coordination for manual install on Claude Code, OpenCode, or any custom MCP client. See bench/README.md for the measurement methodology.

How agent-comm fits together

agent-comm is a single Node process that exposes three transports — MCP stdio (for AI hosts), REST + WebSocket (for hooks, dashboards, custom scripts) — backed by a SQLite database in WAL mode. Hooks installed in your Claude Code (or other host) settings call the REST endpoint at localhost:3421 to claim file locks, query who-edited-what, and broadcast presence. The dashboard UI at the same port is a live view of every agent, message, channel, and shared-state entry. Multiple AI hosts can connect simultaneously and see the same world.

graph TD    A["Agent A<br/>(Claude Code)"] -->|MCP stdio| COMM    B["Agent B<br/>(Codex CLI)"] -->|MCP stdio| COMM    C["Agent C<br/>(Custom script)"] -->|REST API| COMM    HK["PreToolUse hooks<br/>(file-coord, bash-guard)"] -->|REST cas| COMM
    subgraph COMM["agent-comm"]        D["Agents<br/>Register, discover, heartbeat"]        E["Messages<br/>Direct, broadcast, channels, threads"]        F["State<br/>Namespaced KV with CAS"]        G["Events<br/>Real-time pub/sub"]        D --> DB["SQLite DB<br/>WAL mode, FTS5 search"]        E --> DB        F --> DB        DB --> WS["WebSocket"]    end
    WS --> UI["Dashboard UI<br/>http://localhost:3421"]

Quick start

Install from npm

npm install -g agent-comm

Or clone from source

git clone https://github.com/keshrath/agent-comm.gitcd agent-commnpm installnpm run build

Option 1: MCP server (for any MCP-compatible AI host)

agent-comm runs as a stdio MCP server, so any MCP-compatible host can use it. Tested hosts include Claude Code, Cline, OpenCode, Cursor (read-only state), Windsurf, Codex CLI, Aider, and Continue.dev. Adapter recipes for each are in docs/SETUP.md.

Generic MCP config:

{  "mcpServers": {    "agent-comm": {      "command": "npx",      "args": ["agent-comm"]    }  }}

Add this to your host's MCP config file (the path varies by host — ~/.claude.json for Claude Code, ~/.config/opencode/config.json for OpenCode, ~/.cursor/config.json for Cursor, etc. — see the per-host sections in docs/SETUP.md).

The dashboard auto-starts at http://localhost:3421 on the first MCP connection regardless of which host is connected.

Option 2: Standalone server (for REST/WebSocket clients)

node dist/server.js --port 3421

Option 3: Automated setup (Claude Code)

npm run setup

Registers the MCP server in ~/.claude.json, installs the hook scripts (lifecycle + file-coord + bash-guard), and configures permissions. Other hosts: see docs/SETUP.md for the per-host integration recipes — every host that supports pre-tool-call hooks can use the same file-coord.mjs script unchanged.

MCP tools (7)

REST API

All endpoints return JSON. Loopback only: foreign Host/Origin headers get 403, request bodies must be application/json, no wildcard CORS. See full API reference for details.

GET  /health                              Server status + uptimeGET  /api/agents                          List online agentsGET  /api/agents/:id                      Get agent by ID or nameGET  /api/agents/:id/heartbeat             Agent liveness (status + heartbeat age)GET  /api/channels                        List active channelsGET  /api/channels/:name                  Channel details + membersGET  /api/channels/:name/members          Channel member listGET  /api/channels/:name/messages         Channel messages (?limit=50)GET  /api/messages                        List messages (?limit=50&from=&to=&offset=)GET  /api/messages/:id/thread             Get threadGET  /api/search?q=keyword                Full-text search (?limit=20&channel=&from=)GET  /api/state                           List state entries (?namespace=&prefix=)GET  /api/state/:namespace/:key           Get state entryGET  /api/feed                              Activity feed events (?agent=&type=&since=&limit=50)GET  /api/overview                        Full snapshot (agents, channels, messages, state)GET  /api/export                          Full database export as JSON
POST   /api/messages                      Send a message (body: {from, to?, channel?, content})POST   /api/state/:namespace/:key         Set state (body: {value, updated_by})POST   /api/state/:namespace/:key/cas     Atomic compare-and-swap (file-coord hook uses this)DELETE /api/messages                       Purge all messagesDELETE /api/messages                       Delete messages by filterDELETE /api/messages/:id                   Delete a message (body: {agent_id})DELETE /api/state/:namespace/:key          Delete state entryDELETE /api/agents/offline                 Purge offline agentsPOST   /api/cleanup                       Trigger manual cleanupPOST   /api/cleanup/stale                 Clean up stale agents and old messagesPOST   /api/cleanup/full                  Full database cleanup

Agent visibility and status

comm_agents with action: "heartbeat" accepts an optional status_text parameter, letting agents update their visible status in the same call that keeps them online:

// MCP call — heartbeat + status update in onecomm_agents({ "action": "heartbeat", "status_text": "implementing auth module" })
// Clear status text (pass null)comm_agents({ "action": "heartbeat", "status_text": null })
// Plain heartbeat — status text unchangedcomm_agents({ "action": "heartbeat" })

Hosts that support lifecycle hooks (Claude Code, OpenCode, future Cursor/Codex when they ship hook APIs) get automatic heartbeats, registration, and status via the lifecycle hook scripts shipped in scripts/hooks/. Subagents spawned by the Agent tool inherit the same registration via SubagentStart, so they appear on the dashboard alongside the main session. Hosts without hook support (Cursor, Windsurf, Aider as of 2025) can still use the MCP tools — agents must call comm_register and comm_agents heartbeat from the host's instructions file. Custom MCP clients or scripts can call the REST endpoints or use comm_heartbeat directly to show live progress.

The REST endpoint GET /api/agents/:id/heartbeat returns agent liveness info (status, heartbeat age in ms/s, status text) for external monitoring.

Communication patterns

Direct messaging

sequenceDiagram    participant A as Agent A    participant S as agent-comm    participant B as Agent B
    A->>S: comm_send(to B, content review PR 42)    Note over S: Store in SQLite, emit event    B->>S: comm_inbox()    S-->>B: message from A    B->>S: comm_reply(message_id 1, LGTM merging)

Shared state with CAS (distributed locking)

sequenceDiagram    participant A as Agent A    participant S as agent-comm    participant B as Agent B
    A->>S: comm_state(action cas, key deploy-lock, new agent-a)    S-->>A: swapped true    B->>S: comm_state(action cas, key deploy-lock, new agent-b)    S-->>B: swapped false    Note over B: Lock held by agent-a, back off

Dashboard

[Messages View]

The web dashboard auto-starts at http://localhost:3421 and shows agents, messages, channels, shared state, and the activity feed in real time. See the Dashboard Guide for all views and features.

Testing

npm test              # 288 tests across 16 filesnpm run test:watch    # Watch modenpm run test:e2e      # E2E tests onlynpm run test:coverage # Coverage reportnpm run check         # Full CI: typecheck + lint + format + test

Environment variables

Documentation

• Setup Guide — installation, client setup (Claude Code, OpenCode, Cursor, Windsurf), hooks
• Architecture — source structure, design principles, database schema
• Dashboard — web UI views and features
• Changelog

License

MIT — see LICENSE