agent-comm

agent-comm

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

浅色主题	深色主题

为什么需要

当你在同一代码库上运行多个 AI Agent 时——一个终端里做代码审查，另一个终端里做实现，第三个终端里做测试——它们彼此毫不知情。它们会重复工作、造成合并冲突，还会遗漏上下文。

	不使用 agent-comm	使用 agent-comm
发现	Agent 不知道其他 Agent 的存在	Agent 注册技能，并按能力发现彼此
协作	编辑同一文件，造成冲突	锁定文件/区域，分工协作
通信	没有——每个 Agent 都在盲目工作	消息、频道、广播
状态共享	重复工作，遗漏上下文	通过原子 CAS 共享 KV 存储
可见性	不知道发生了什么	实时仪表板 + 活动动态，展示所有情况

agent-comm 为它们提供了共享通信层：

• Agent 使用名称、能力和技能进行注册，以便其他 Agent 发现它们
• Agent 按技能或标签发现彼此，以便动态分配任务
• Agent 交换消息（直接、广播或基于频道）以协作，并可设置重要性级别（low/normal/high/urgent）和可选确认
• Agent 通过阻塞式等待（comm_poll）轮询收件箱，从而接收执行过程中的 Agent 信号，无需忙循环
• Agent 通过共享状态（支持原子 CAS 的键值存储）管理锁、标志和进度
• Agent 将活动事件（提交、测试结果、文件编辑）记录到共享动态中
• Agent 可检测停滞的 Agent——仍处于运行状态（心跳正常），但没有取得进展
• Agent 通过系统层的 file-coord hook 串行处理文件编辑（见下文），避免并行 Agent 修改共享文件时相互覆盖
• Web 仪表板实时显示所有信息，包括“活动动态”标签页

它适用于任何支持 MCP（stdio 传输）或能够发送 HTTP 请求（REST API）的 Agent。

为什么使用钩子，而不只是 MCP 工具

MCP 工具（comm_state 等）为 Agent 提供了协作所需的_基本操作_，但不会_强制_协作——Agent 必须记得调用它们。我们的 基准测试 测量了依赖模型自行判断会发生什么：即使使用严格的流程提示词，Claude 在第一个认领周期会遵循协议，随后就会回到“提供帮助、完成任务”的做法。 软性协作并不可靠。

解决办法是在 scripts/hooks/ 中提供一对 PreToolUse 钩子：file-coord 会拦截每一次 Edit/Write/MultiEdit，并通过 REST POST /api/state/file-locks/<path>/cas 认领文件（如果文件已被其他 Agent 锁定，就会阻止编辑）；bash-guard 会拦截 git commit、git push、npm install、npm test、构建、迁移和开发服务器启动操作，并在这些操作会与其他会话的 WIP 冲突时阻止或发出警告。协议由此成为基础设施，而不是 Agent 可能忽略的提示词。

基准测试的主要试点是 multi-term-commit——直接模拟同一项目中两个终端会话的日常问题。会话 A 编辑两个文件，但不提交。随后，会话 B 编辑另外两个文件并运行 git commit -am "my work"。如果没有钩子，B 的提交会悄悄包含 A 的 WIP。有了钩子，B 的提交会在 bash 层被阻止，并收到可执行的提示；B 随后会做出响应（选择性暂存、还原或协调）。基准测试结果：

	朴素方式（无钩子）	使用钩子
提交纯净度	混杂 — bar.js、baz.js、foo.js、qux.js	纯净 — baz.js、qux.js
实际耗时	91.0s	78.8s（-13%）
总成本	$0.774	$0.591（-24%）
结果	A 的 WIP 在不知情的情况下以 B 的名义提交	提交干净，无覆盖

钩子速度更快，成本也更低，而不仅仅是更安全。原因是：当 Agent 在共享工作区中缺乏协作时，它们会读取过时状态，在任务中途感到困惑，反复重试并重新思考。通过串行化访问并及早显现冲突，可以消除这些无谓思考。运行 npm run setup 自动安装这两个钩子；如需在 Claude Code、OpenCode 或任何自定义 MCP 客户端上手动安装，请参阅设置 → 文件协作。有关测量方法，请参阅 bench/README.md。

agent-comm 如何协同工作

agent-comm 是一个 Node 进程，提供三种传输方式——MCP stdio（供 AI 宿主使用）、REST + WebSocket（供钩子、仪表板和自定义脚本使用）——后端由 WAL 模式的 SQLite 数据库支持。安装在 Claude Code（或其他宿主）设置中的钩子会调用 localhost:3421 上的 REST 端点，以认领文件锁、查询谁编辑了什么并广播在线状态。同一端口上的仪表板 UI 会实时显示每个 Agent、消息、频道和共享状态条目。多个 AI 宿主可以同时连接，并看到相同的世界。

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"]

快速开始

从 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 宿主）

agent-comm 以 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 Code 使用 ~/.claude.json，OpenCode 使用 ~/.config/opencode/config.json，Cursor 使用 ~/.cursor/config.json 等—— 请参阅 docs/SETUP.md 中各宿主对应的章节）。

无论连接的是哪个宿主，仪表板都会在首次 MCP 连接时自动启动于 http://localhost:3421。

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

node dist/server.js --port 3421

选项 3：自动设置（Claude Code）

npm run setup

在 ~/.claude.json 中注册 MCP 服务，安装钩子脚本（生命周期、文件协调和 bash 防护），并配置权限。其他宿主：请参阅 docs/SETUP.md，了解各宿主的集成方案——所有支持工具调用前钩子的宿主都可以直接使用同一份 file-coord.mjs 脚本，无需修改。

MCP 工具（7 个）

工具	说明
comm_register	注册名称、能力、元数据、技能，并自动加入频道
comm_agents	Agent 管理——操作：list、discover、whoami、heartbeat、status、unregister
comm_send	发送消息——直接发送（to）、发送到频道、广播、回复（reply_to）、转发（forward）
comm_inbox	读取收件箱（直接消息和频道消息、未读筛选、importance 筛选、通过 thread_id 查看会话）
comm_poll	阻塞等待收件箱收到新消息（支持 timeout_ms 和 importance 筛选）
comm_channel	频道管理——操作：create、list、join、leave、archive、update、members、history
comm_state	共享键值状态——操作：set、get、list、delete、cas

REST API

所有端点均返回 JSON。仅限环回访问：来自外部的 Host/Origin 标头会返回 403，请求正文必须为 application/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

Agent 可见性和状态

comm_agents 的 action: "heartbeat" 接受可选参数 status_text，让 Agent 在保持在线的同时更新其可见状态：

// 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，以及未来推出钩子 API 的 Cursor/Codex）可通过随附于 scripts/hooks/ 的生命周期钩子脚本自动执行心跳、注册和状态更新。由 Agent 工具启动的子 Agent 会通过 SubagentStart 继承相同的注册信息，因此会与主会话一起显示在仪表板上。不支持钩子的宿主（截至 2025 年的 Cursor、Windsurf、Aider）仍可使用 MCP 工具——Agent 必须按照宿主的指令文件调用 comm_register 和 comm_agents heartbeat。自定义 MCP 客户端或脚本可以调用 REST 端点或直接使用 comm_heartbeat 来显示实时进度。

REST 端点 GET /api/agents/:id/heartbeat 会返回 Agent 存活信息（状态、心跳间隔，单位为毫秒/秒，以及状态文本），供外部监控使用。

通信模式

直接消息

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 启动，并实时显示 Agent、消息、频道、共享状态和活动动态。所有视图和功能请参阅仪表板指南。

---

测试

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

环境变量

变量	默认值	说明
AGENT_COMM_PORT	3421	仪表板 HTTP/WebSocket 端口
AGENT_COMM_HOST	127.0.0.1	仪表板绑定地址（0.0.0.0 会将其暴露到网络）
AGENT_COMM_RETENTION_DAYS	7	旧数据自动清除前保留的天数（1-365）

文档

• 设置指南 — 安装、客户端设置（Claude Code、OpenCode、Cursor、Windsurf）、钩子
• 架构 — 源码结构、设计原则、数据库架构
• 仪表板 — Web UI 视图和功能
• 更新日志

许可证

MIT — 详见 LICENSE