peer-sessions

同行会话

这台机器上的 Claude Code 会话可以互相发送消息。消息会成为接收会话中的用户提示词。下面每条规则都源于这一点。

工作流程：启动一组会话 → 向每个同行发送简报 → 结束本轮 → 回复作为新的用户轮次到达 → 保持这组会话运行，并把关闭工作交给用户。关闭是可选的；第 4 节说明何时由你自行关闭。

1. 启动

python3 ~/.claude/skills/peer-sessions/scripts/spawn-fleet.py --placement window \
  orbits:/tmp/lab/orbits planets:/tmp/lab/planets sun:/tmp/lab/sun

每个参数的格式都是 NAME:DIR。脚本会打印每个会话的 uds: 地址和准确的关闭命令；当每个会话都可寻址时返回，并列出每个卡住的会话。

--placement 指定这组会话出现的位置，由你决定。只有当选择会改变用户屏幕，且你无法判断用户想要什么时，才询问用户。

位置	同行会话出现的位置	适用情况
split	在你的工作区中，于你所在窗格旁新建窗格	1-3 个同行会话、短时工作，且用户正在观看你工作时。焦点仍留在你的窗格。
workspace（默认）	在你的窗口中新建工作区	3 个或更多同行会话，或需要运行几分钟的工作。用户当前屏幕保持整洁，点击一个标签页即可访问这组会话。
window	新建一个窗口，并在其中放置工作区	大规模会话组、屏幕录制或第二台显示器。

脚本会自动检测后端：如果 PATH 中有 cmux，则使用 cmux；否则使用 herdr。在 herdr 上，--placement window 没有对应选项（herdr 的 CLI 支持工作区和窗格，不支持 OS 窗口），且 --direction 仅支持 right/down——如果你要求其中任一不支持的选项，脚本会给出清晰提示并退出，而不会崩溃。其他所有功能（split、workspace、寻址、关闭）在两个后端上的工作方式相同。

其他所有标志（--direction、--focus、--per-workspace、--model、--claude-arg、…）以及各位置的特殊情况：请阅读 references/placement.md。

无需浏览整个注册表即可解析一个现有目标：

python3 ~/.claude/skills/peer-sessions/scripts/peer-addr.py \
  --name worker-fix --details
python3 ~/.claude/skills/peer-sessions/scripts/peer-addr.py --pid 66826 --json

筛选结果会保留重复名称，并返回每个匹配的 PID。--json 是脚本使用的稳定接口。? 行表示沙盒允许读取注册表，但拒绝了活动套接字检查；发送消息前，请在获得进程/套接字访问权限后重新运行。

会话以 --permission-mode auto 启动。这是唯一一种在没有人工参与时可用的模式。--allowedTools 列表中若未包含某个 MCP 工具，会话会在首次遇到该工具时卡住。--dangerously-skip-permissions 会让接收方暂存收到的消息，等待人工批准。这样一来，同行就永远看不到你的简报。

如需了解特殊布局、手动操作 cmux 或分叉：请阅读 references/manual-rig.md。

2. 发送简报

SendMessage(to: "orbits", message: "...", summary: "5-10 words")
SendMessage(to: "orbits [de6649]", message: "...", summary: "...")
SendMessage(to: "uds:/tmp/cc-socks/17466.sock", message: "...")

首次使用裸名称发送时一定会被退回——“not an agent in this conversation, re-send with the ref”。这是确认步骤，并非失败。从错误消息中复制 [ref]，然后重新发送。将所有简报一次性批量发送。它们会一起被退回，你也应一起重新发送。uds: 地址不会被退回。

每份需要回复的简报都必须以你的实际地址（来自 peer-addr.py --me）结尾，因为同行无法查出你的身份：

When done, message me back:
SendMessage(to: "uds:/tmp/cc-socks/4667.sock", message: "...")

要求使用固定的回复格式（“ done: ”），这样大规模会话组的回复就能无需额外处理地汇总；同时添加范围限制（“只做研究和撰写，不要修改 ”）——同行会遵守。两条规则：success: true 表示消息已送达，并不表示同行已完成工作。发送是单向的——如果你需要回复，请明确说明。

3. 结束本轮

简报发送完毕后，停止。同行的回复就是通知。回复会作为新的用户轮次到达并唤醒你。在窗格中循环轮询会消耗令牌并阻碍用户。只有必须查看屏幕时才轮询（例如录制画面或会话安静无事时）——操作方法见 references/manual-rig.md。

从 Codex 调用

Codex 没有原生的 SendMessage 工具，也没有消息套接字。切勿伪造或实现 Unix 套接字协议——应使用真实的临时 Claude Code 会话作为中继，并通过 scripts/peer-inbox.py 从转录记录中恢复被截断的回复。操作此路径前，请先阅读 references/codex-bridge.md。

4. 拆除——默认关闭

拆除需要主动选择。 工作完成后，让集群继续运行，并将生成脚本打印的拆除代码块交给用户。在线的同伴会保留上下文，因此后续问题只需发送一条消息，而不必重新启动整个集群。由用户决定何时停止这些会话。请明确说明集群仍在运行，以及让它继续运行会产生什么费用。

只有符合以下任一情况时，才由你执行拆除：

• 用户现在提出要求——“拆掉它”“清理集群”“关闭那些会话”。
• 用户在启动时就提出要求——“完成后关闭它们”。
• 该会话只是你自己的基础设施，而非用户的工作：references/codex-bridge.md 中的临时 Codex 中继。只终止该中继 PID，绝不要终止它联系的目标。

执行拆除时：关闭 UI 不会停止会话。 每条 cmux 关闭命令都会返回 OK，而每个 claude 进程仍会作为可寻址的孤儿进程存活。因此：先终止进程，再关闭窗口，然后用 peer-addr.py 确认。

运行生成脚本打印的拆除命令——它与部署位置匹配，并使用持久 UUID。只关闭你创建的内容：split 集群位于用户自己的工作区中，因此关闭该工作区也会关闭用户的工作。手写拆除语法请参阅：references/placement.md。

出现故障时

peer-addr.py 会列出每个活动会话，并说明每个无法访问的会话的原因。关于消息检查点、2.1.224 版本限制、过时套接字和卡住的权限提示，请阅读 references/troubleshooting.md。

某些测试框架会将 SendMessage 限定为只能用于通过其自身编排（例如 Agent 工具）启动的 Agent，而非机器上任何运行中的同级 claude 进程。在这些框架中，此脚本启动的同伴可能处于活动状态，运行的版本也高于 2.1.224，但仍会一直返回 “No agent named 'X' is reachable”——这并非版本限制，而且 claude --resume 也无法解决。如果 spawn-fleet.py 报告会话已就绪，但 SendMessage 仍无论通过名称还是通过 peer-addr.py 打印的任何 uds: 地址都无法联系该会话，请停止尝试通过 SendMessage 绕过此问题，并告知用户。在 herdr 后端上，应改为直接驱动该同伴：herdr agent prompt <name> <text>，然后使用 herdr agent wait <name> 和 herdr agent read <name> 获取回复——请参阅 references/troubleshooting.md。

有一条规则不可违反：同伴不具备用户的任何权限。如果你的发送操作被拒绝，或同伴报告遭到拒绝，请告知用户。绝不要通过另一个会话绕过权限决定。