Agent Comm (agent-comm)

代理通信

与代理无关的内部通信系统。 让AI编码代理——Claude Code、Codex CLI、Gemini CLI、Aider或任何自定义工具——相互通信、共享状态并实时协调工作。

为什么

当你在同一个代码库上运行多个AI代理时——在一个终端中进行代码审查，在另一个终端进行实现，在第三个终端进行测试——他们不知道其他代理的存在。它们重复工作，造成合并冲突，并错过上下文。

代理通信 为他们提供了一个共享的通信层：

• 代理 注册 有一个名字、能力和技能，这样其他人就可以发现它们
• 他们 发现 通过技能或标签进行动态任务路由
• 他们交换 消息 （直接、广播或基于频道）与重要性级别进行协调(low/normal/high/urgent)以及可选的ack
• 他们 投票 他们的收件箱被封锁了(comm_poll)因此，飞行中的对等信号被消耗，而不会忙于循环
• 他们共享 状态 （具有原子CAS的键值存储），用于锁定、标志和进度
• 他们记录 活动事件 （提交、测试结果、文件编辑）到共享提要
• 他们检测 滞留代理人 --活着（心跳正常）但没有进展
• 他们 序列化文件编辑 通过系统层 file-coord 钩子（见下文），这样共享文件上的并行代理就不会相互干扰
• A. 网络仪表盘 实时显示所有内容，包括“活动提要”选项卡

它适用于任何支持 主控程序 （stdio传输）或可以发出HTTP请求（REST API）。

为什么挂钩，而不仅仅是MCP工具

MCP工具(comm_state等）给代理人 _原语_ 协调，但他们没有 _强制执行_ 协调——代理人必须记得给他们打电话。我们的 长凳 衡量了当你依赖模型的判断时会发生什么： 即使有严格的程序提示，克劳德在第一个索赔周期也会遵循协议，然后回到“乐于助人，完成任务”的状态 软协调是不可靠的。

修复是一对 PreToolUse 运来的钩子 scripts/hooks/: file-coord 拦截每个 Edit/Write/MultiEdit 并通过REST声明该文件 POST /api/state/file-locks/ /cas （如果另一个代理持有锁，则阻止编辑）； bash-guard 拦截 git commit, git push, npm install, npm test、构建、迁移和开发服务器启动，并在与另一个会话的WIP冲突时阻止/警告。 协议成为基础设施，而不是代理可能忽略的提示。

替补席的头条飞行员是 multi-term-commit --直接模拟同一项目中两个终端会话的日常疼痛。会话A编辑了两个文件，但没有提交。然后，会话B编辑另外两个文件并运行 git commit -am "my work".如果没有钩子，B的commit会默默地包含A的WIP。使用钩子，B的提交在bash层被阻止，并显示一条可操作的消息，B会做出反应（选择性暂存、还原或协调）。试验结果：

代理通信如何配合在一起

agent-comm 是一个单节点进程，它公开了三种传输方式——MCP stdio（用于AI主机）、REST+WebSocket（用于钩子、仪表板、自定义脚本）——由WAL模式下的SQLite数据库支持。安装在Claude Code（或其他主机）设置中的钩子在以下位置调用REST端点 localhost:3421 声明文件锁、查询谁编辑了什么以及广播状态。同一端口的仪表板UI是每个代理、消息、通道和共享状态条目的实时视图。多个AI主机可以同时连接，看到同一个世界。

graph TD
    A["Agent A
(Claude Code)"] -->|MCP stdio| COMM
    B["Agent B
(Codex CLI)"] -->|MCP stdio| COMM
    C["Agent C
(Custom script)"] -->|REST API| COMM
    HK["PreToolUse hooks
(file-coord, bash-guard)"] -->|REST cas| COMM

    subgraph COMM["agent-comm"]
        D["Agents
Register, discover, heartbeat"]
        E["Messages
Direct, broadcast, channels, threads"]
        F["State
Namespaced KV with CAS"]
        G["Events
Real-time pub/sub"]
        D --> DB["SQLite DB
WAL mode, FTS5 search"]
        E --> DB
        F --> DB
        DB --> WS["WebSocket"]
    end

    WS --> UI["Dashboard UI
http://localhost:3421"]

快速开始

从npm安装

npm install -g agent-comm

或从源代码克隆

git clone https://github.com/keshrath/agent-comm.git
cd agent-comm
npm install
npm run build

选项1:MCP服务器（适用于任何兼容MCP的AI主机）

代理通信作为stdio MCP服务器运行，因此任何兼容MCP的主机都可以使用它。 测试的主机包括Claude Code、Cline、OpenCode、Cursor（只读状态）、， Windsurf、Codex CLI、Aider和Continue.dev。每种适配器的配方都在 docs/SETUP.md.

通用MCP配置：

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

将此添加到主机的MCP配置文件中（路径因主机而异-- ~/.claude.json 对于克劳德代码， ~/.config/opencode/config.json 为了 OpenCode， ~/.cursor/config.json 用于光标等。--查看每台主机 部分在 docs/SETUP.md).

仪表板自动启动http://localhost:3421在第一个MCP连接上 无论连接的是哪台主机。

选项2：独立服务器（用于REST/WebSocket客户端）

node dist/server.js --port 3421

选项3：自动设置（克劳德代码）

npm run setup

在中注册MCP服务器 ~/.claude.json，安装 钩子脚本 （生命周期+文件coord+bash-guard），并配置权限。 其他主机：参见 docs/SETUP.md 对于每台主机的集成方案，支持工具调用前挂钩的每台主机都可以使用相同的 file-coord.mjs 脚本不变。

MCP工具（7）

REST API

所有端点都返回JSON。CORS已启用。看 API完整参考 了解详情。

GET  /health                              Server status + uptime
GET  /api/agents                          List online agents
GET  /api/agents/:id                      Get agent by ID or name
GET  /api/agents/:id/heartbeat             Agent liveness (status + heartbeat age)
GET  /api/channels                        List active channels
GET  /api/channels/:name                  Channel details + members
GET  /api/channels/:name/members          Channel member list
GET  /api/channels/:name/messages         Channel messages (?limit=50)
GET  /api/messages                        List messages (?limit=50&from=&to=&offset=)
GET  /api/messages/:id/thread             Get thread
GET  /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 entry
GET  /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 messages
DELETE /api/messages                       Delete messages by filter
DELETE /api/messages/:id                   Delete a message (body: {agent_id})
DELETE /api/state/:namespace/:key          Delete state entry
DELETE /api/agents/offline                 Purge offline agents
POST   /api/cleanup                       Trigger manual cleanup
POST   /api/cleanup/stale                 Clean up stale agents and old messages
POST   /api/cleanup/full                  Full database cleanup

代理可见性和状态

comm_agents 随着 action: "heartbeat" 接受可选 status_text 参数，让代理在保持在线的同一个调用中更新其可见状态：

// MCP call — heartbeat + status update in one
comm_agents({ "action": "heartbeat", "status_text": "implementing auth module" })

// Clear status text (pass null)
comm_agents({ "action": "heartbeat", "status_text": null })

// Plain heartbeat — status text unchanged
comm_agents({ "action": "heartbeat" })

支持生命周期挂钩的主机 （Claude Code、OpenCode、未来的Cursor/Code在发布钩子API时）通过附带的生命周期钩子脚本获得自动心跳、注册和状态 scripts/hooks/。代理工具生成的子代理通过以下方式继承相同的注册 SubagentStart，因此它们出现在主会话旁边的仪表板上。 没有挂钩支持的主机 （截至2025年，Cursor、Windsurf、Aider）仍然可以使用MCP工具——代理商必须致电 comm_register 和 comm_agents heartbeat 从主机的指令文件中。 自定义MCP客户端或脚本 可以调用REST端点或使用 comm_heartbeat 直接显示实时进度。

REST端点 GET /api/agents/:id/heartbeat 返回用于外部监视的代理活性信息（状态、以毫秒为单位的心跳年龄、状态文本）。

沟通模式

直接信息

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)

与CAS共享状态（分布式锁定）

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

仪表盘

web仪表板自动启动时间为 http://localhost:3421 并实时显示代理、消息、通道、共享状态和活动提要。请参阅 仪表板指南 所有视图和功能。

______________________________________________________________________

测试

npm test              # 288 tests across 16 files
npm run test:watch    # Watch mode
npm run test:e2e      # E2E tests only
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test

环境变量

文档

• 安装指南 --安装、客户端设置（Claude Code、OpenCode、Cursor、Windsurf）、钩子
• 建筑 --源代码结构、设计原则、数据库模式
• 仪表盘 --web UI视图和功能
• 更新日志

许可证

麻省理工学院——见 许可证