agent-peer Skill 技能

技能简介

agent-peer 是一个本地进程间通信（IPC）网格，让同一台机器上所有 AI 编程 Agent（Claude Code、Codex CLI、Antigravity、pi/oh-my-pi、opencode、muse 以及自研脚本）能够相互发现、互发消息并响应式唤醒彼此。它不依赖任何中心化的"Hub"——每个 Agent 既是客户端也是服务端，整个网格使用 Unix Domain Socket（macOS/Linux）或命名管道（Windows）完成通信，无需 Docker、无需轮询，端到端延迟通常低于 200ms。Claude Code 与 Codex CLI 内置了原生跨会话传输（前者为 /peer，后者为 codex queue），agent-peer 直接复用这些通道，从而实现零等待接收；其他无原生通道的 Agent 则通过 agent-peer 自带的共享 socket 传输 + 阻塞式 wait 接入。所有传输的消息统一落到一个收件箱日志中，任何 Agent 都可通过 agent-peer watch 或 logs 回看全网格交互历史。

核心能力

• 亚 200ms 响应式投递：消息到达瞬间 wait 命令立刻返回，Agent 主循环被工具调用自然唤醒，无需轮询线程
• 零配置身份识别：自动从 Agent 运行环境中识别稳定的会话名与引擎类型，无需 --name 等手动参数
• 存量消息合并：Agent 忙碌期间累积的消息在下次 wait 调用时一次性按序返回，绝不丢失任何 backlog
• 多端原生支持：macOS/Linux 通过 Unix Domain Socket、Windows 原生命名管道（非 WSL），平台差异封装在 compat.py 之后
• 多 Agent 共享线程（聊天室）：多个会话同时读写同一个房间流，活跃成员零推送，@mention/@all/[stop] 才触发门铃唤醒
• 配额与用量仪表盘：agent-peer status 支持 Antigravity / Claude Code / Codex CLI，--live 实时刷新显示谁可达、谁的预算将尽
• 零重型依赖：纯 Python 3.10+，仅使用标准库（curses / msvcrt / ANSI），不引入 TUI 框架
• 托管网格纪律注入：agent-peer setup --rules 可向 ~/.claude/CLAUDE.md 等全局指令文件注入网格使用规范，让每个工作区在 Turn 1 就知道核心约定

安装配置

1. 一键脚本安装：curl -fsSL https://raw.githubusercontent.com/mkhuda/agent-peer/main/install.sh | sh（macOS/Linux）
2. Windows 原生安装（PowerShell，无需 WSL）：irm https://raw.githubusercontent.com/mkhuda/agent-peer/main/install.ps1 | iex
3. 手动安装（uv）：uv tool install agent-peer，然后 agent-peer setup 选择要接入的 Agent
4. 手动安装（pipx 或 pip）：pipx install agent-peer 或 python3 -m pip install --user agent-peer，同样跑 agent-peer setup
5. 运行 agent-peer setup：交互式选择已检测到的 Agent（agy、Codex、muse、pi/oh-my-pi、opencode、Claude Code），自动在每个 Agent 已知路径写入 SKILL.md；可加 --all、--harness、--remove、--list 等参数非交互化

使用步骤

1. 发现可达 Agent：agent-peer list 列出当前所有活跃会话（PID / 会话名 / 引擎 / 状态 / 套接字 / CWD），可用 --cwd 过滤到单个项目
2. 发送消息：通过 agent-peer send my-app-fe "review the auth middleware diff when you're free" 按会话名发，或 agent-peer send agy-33402 "[stop] hold off on that migration" --priority now 按 PID 发
3. 同步等待回复：在 send 命令后加 --await-reply [seconds]，整个调用阻塞直到目标返回答复，避免先 send 再 wait 的竞态
4. 被动接收：agent-peer wait 阻塞式等待任意来源消息，到达立即返回
5. 订阅共享线程：agent-peer room join my-project 加入多 Agent 房间，agent-peer room post my-project "..." --mention claude-1 发消息并点对点唤醒
6. 回看历史与状态：agent-peer watch 实时滚动显示网格事件，agent-peer status --live 刷新配额，agent-peer logs 检索收件箱

适用场景

• 多 Agent 并行协作：一个会话专注前端、另一个专注后端，需要互相同步进度
• Claude Code + Codex 跨引擎调度：用 Claude Code 做架构审查，把具体实现派给 Codex CLI，会话之间自动衔接
• 长任务跨会话接力：让 Codex 跑一晚上 CI 修复，第二天 Claude Code 接管继续处理
• 人类↔ Agent 桥接：通过 Telegram 桥（已内置）让手机消息直接唤醒本地 Agent
• 研究项目的 Agent 群控：论文/调研场景下同时管理 5-10 个 Agent 实例，让它们互相配合而非各自孤立

适用人群

• 同时使用 Claude Code + Codex CLI + 其他 AI 编程 Agent 的资深开发者
• 维护大型 monorepo、需要把任务拆给多个 Agent 并行处理的工程团队
• 关注"AI Agent 之间如何通信"这一新基础设施领域的早期采用者
• 自研 Agent Harness、想给自家 Agent 接入通用 IPC 通道的工程师

工作原理

agent-peer 把每台机器上启动的 Agent 抽象为带稳定身份（PID + 会话名 + 引擎 + CWD）的 peer。每个 peer 启动时通过 agent-peer setup 在自己 harness 的 SKILL.md 路径中注册一套 CLI 协议，然后绑定一个本地 socket 端点。发送消息时，发送方根据目标引擎选择最优通道：Claude Code 走 /peer 命令、Codex CLI 走 codex queue、Antigravity 走语言服务器、其它 Agent 走 agent-peer 自管的共享 socket。当目标 Agent 在忙时，消息进入对应 peer 的 in-memory 队列；目标下次调用 wait（或 send 加 --await-reply）时，agent-peer 把累积消息合并按序返回。整个网格的会话注册、消息事件、inbox 状态统一写入 SQLite-backed 日志，任何 peer 通过 watch/logs 都能看到全网视图。平台差异（Windows 命名管道 vs Unix Socket、跨平台文件锁、进程检测）一律封装在 agent_peer/compat.py 之后，Windows 真机经过端到端验证。

官方链接

• PyPI：https://pypi.org/project/agent-peer/
• GitHub：https://github.com/mkhuda/agent-peer
• 安装脚本：https://raw.githubusercontent.com/mkhuda/agent-peer/main/install.sh
• 安装指南：https://github.com/mkhuda/agent-peer/blob/main/install.sh