SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-peers

claude-peers

智能体与模型

查看项目

更新于 10-16 06:00

技能介绍

claude-peers 是一个面向同一台机器上 AI 编程代理的发现与消息网络。它通过一个共享的 broker 守护进程在 Unix 域套接字（~/.claude/run/claude-peers.sock）上监听，并以 SQLite 作为后端，在 Claude Code 与 Codex CLI 会话之间路由消息。

客户端类型

不同客户端在推送通知与消息投递方式上存在差异：

  • claude-code：支持推送通知（claude/channel），消息即时推入会话，通过 settings.json 的 MCP 条目配置。
  • codex：不支持推送通知，需要轮询，必须在每一轮调用 check_messages，通过 ~/.codex/config.toml 的 MCP 条目配置。
  • cli：不支持推送通知，需手动通过 bun ~/tools/claude-peers-mcp/cli.ts send <id> <msg> 发送，无对应配置。

工作流模式

  • 任务委派：通过 send_message 向 Codex 或 Claude 对等端发送聚焦的任务描述，包含文件路径、验收标准以及应在哪个分支上工作。接收方代理会在其下一轮处理该任务。
  • 代码审查交接：完成工作后，向对等端发送 diff 摘要并请求审查。对等端可通过 send_message 回复发现的问题。
  • 并行探索：多个代理在同一仓库工作时，可用 set_summary 声明各自正在调查的内容，避免重复工作。使用带 scope repo 的 list_peers 查看同一代码库中还有谁。
  • 会话生命周期：使用 kill_peer 终止卡住、无响应或已完成的对等端代理会话。这会终止父进程（例如 Codex CLI），而不仅是 MCP 子进程，并清理对等端记录。

CLI 参考

  • bun ~/tools/claude-peers-mcp/cli.ts status：查看 broker 健康状况与所有对等端（含孤儿警告）。
  • bun ~/tools/claude-peers-mcp/cli.ts peers：快速列出对等端。
  • bun ~/tools/claude-peers-mcp/cli.ts orphans：列出孤儿的 server.ts 进程（PPID=1）。
  • bun ~/tools/claude-peers-mcp/cli.ts cleanup：终止孤儿进程并从 broker 中移除。
  • bun ~/tools/claude-peers-mcp/cli.ts send <id> <msg>：从终端发送（标记为未验证）。
  • bun ~/tools/claude-peers-mcp/cli.ts kill <id>：终止对等端的代理会话（向父进程发送 SIGTERM）。
  • bun ~/tools/claude-peers-mcp/cli.ts kill-broker：停止 broker 守护进程。

消息历史

check_messages 返回所有近期消息（已发送与已接收），并附带增强信息：

  • [claude-code] 或 [codex] 客户端类型标签
  • ISO 时间戳
  • [NEW] 标记，用于此前未见过的消息
  • 方向指示（From/To），附带对等端摘要或 CWD

消息在多次读取间持久保留——多次调用 check_messages 仍会显示历史。/message-history broker 端点是非破坏性的。

孤儿管理

MCP 服务器进程通过 stdin 关闭（即时）和 PPID 监控（30 秒兜底）检测父进程死亡。broker 的过期对等端清扫（每 30 秒）也会检测孤儿进程（PPID=1）并终止它们。

手动清理：bun cli.ts orphans 列出，bun cli.ts cleanup 终止孤儿进程。

注意事项

  • Codex 沙箱：Codex 的 macOS seatbelt 沙箱在 workspace-write 模式下会阻止 socket connect()。Codex 会话目前需要 --dangerously-bypass-approvals-and-sandbox 或 danger-full-access 沙箱才能访问 broker。这是 Codex 沙箱的限制，而非 peers 的问题——记录于 Codex issue #11095。
  • Codex 无推送：Codex 代理必须主动调用 check_messages——消息在被轮询前不可见。
  • 权限允许列表：mcp__claude-peers__send_message 可能不在自动允许列表中。用户可能需要在首次使用时批准，或将其加入 settings.json 的 permissions。
  • broker 必须运行：broker 由 launchd 管理（com.minoan.claude-peers-broker）。如果对等端无法连接，请检查：launchctl list | grep claude-peers。
  • 过期套接字：如果 broker 崩溃，套接字文件会残留。重启时，broker 会自动检测并移除它。
  • TCP 回退：在 broker 的环境变量中设置 CLAUDE_PEERS_TCP=1 可同时监听 TCP 端口 7899。当设置了 CLAUDE_PEERS_URL 时客户端使用 TCP（例如 CLAUDE_PEERS_URL=http://127.0.0.1:7899）。