tmux-agents · diff
git:20260922.5fcde05 to git:20260930.4f0106a
8 added, 4 removed. Audit A to A.
---
name: tmux-agents
description: "通过 tmux pane 与已运行的 CLI Agent 通信。用于 pane discovery、session clear、CLI skill 语法选择，以及 tmux-cli send/wait_idle/capture。"
---
# Tmux Agents
目标 Agent 必须已经在 pane 中运行；本 skill 不分配角色。
+ 本 skill 要求安装支持延迟创建托管 session 的 `tmux-cli`：在 tmux 外，`status`、列表和针对显式 full pane id 的
+ `send` / `wait_idle` / `capture` 不创建 `remote-cli-session`；只有明确 `launch` 新托管 window 才按需创建。
+ 旧版不满足这一前提时先升级工具，不用环境变量伪装 tmux，也不在本 skill 中保留旧版兼容分支。
+
## Preflight Checklist
每次发送前逐项过；任何一项不满足就先报告，不得盲发：
- - [ ] socket 可用：`tmux-cli status` 能返回；报 `Operation not permitted` 说明 socket 被沙箱拦，改在沙箱外重试；
+ - [ ] 先用原生 `tmux list-panes -a` 只读确认 socket 和目标，再运行无隐式建 session 副作用的 `tmux-cli status`；报 `Operation not permitted` 说明 socket 被沙箱拦，改在沙箱外重试；
- [ ] 目标 pane 每次重新 discovery，发送只用跨 window 的 full pane id（如 `ai-2:1.3`），不靠记忆或上次的 id；
- [ ] CLI 类型来自 pane title + `pane_current_command`（`ClaudeAgent-*` / `CodexAgent-*`），不得凭任务角色猜；
- [ ] 目标状态已确认：空闲可输入，或仍在完成同一任务（此时只发补充指令，不 clear）；
- [ ] 仅新任务 / 新 gate / 新 slice 才先发 `/clear`，并等它完成 clear 回到可输入状态；
- [ ] 发送文本不含裸 `#数字`（改用 `PR 45` / `PR-45` / 完整 URL）；
- [ ] 发送后执行 `wait_idle` → `capture`；单次 wait_idle、暂时无输出、主观耗时都不构成完成证据；
- [ ] 完成判定按 Completion Check 的证据规则；并发发送仅限相互独立且写入范围不重叠的任务。
## Agent CLI Types
根据 pane title 和 `pane_current_command` 确认 CLI 类型：
| Pane title pattern | CLI type | Skill trigger |
| --- | --- | --- |
| `ClaudeAgent-*` | Claude Code Agent | slash command，例如 `/planreview` |
| `CodexAgent-*` | Codex Agent | dollar skill，例如 `$planreview` |
不得仅凭任务角色猜 CLI 类型。
## Pane Discovery
tmux 命令报 `error connecting to ... (Operation not permitted)` 说明 socket 被沙箱拦，在沙箱外重试。
每次发送前都重新确认目标 full pane id：
```bash
- tmux-cli status
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{window_name} #{pane_current_command} #{pane_title}'
+ tmux-cli status
```
后续 `send`、`wait_idle`、`capture` 都使用跨 window 的 full pane id，例如 `ai-2:1.3`。目标 Agent
- 不在线、pane id 不明确、名称冲突或命令不可用时，先报告，不得盲发。
+ 不在线、pane id 不明确、名称冲突、命令不可用或安装版本不满足上述延迟创建前提时，先报告，不得盲发。
## Session Clear
新 assigned task 或新的 gate/slice，先单独发送 `/clear`，确认目标完成 clear 并回到可输入状态后，再发送正式任务。
如果目标 Agent 仍在完成同一任务、等待补充信息、返回 artifact、修正输出或回答 follow-up，不要 clear，直接发送补充指令。
Agent 仍在工作时不得因耗时长而 clear、覆盖任务或擅自中断。
## Send Safety
通过 `tmux-cli send` 发送文本时避免裸 `#数字`，使用 `PR 45`、`PR-45`、`issue 123` 或完整 URL。
若内容被截断，不要 clear；重新 discovery 后发送不含裸 `#数字` 的完整文本。
## Chat Workflow
新任务：
```bash
- tmux-cli status
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{window_name} #{pane_current_command} #{pane_title}'
+ tmux-cli status
tmux-cli send "/clear" --pane=<full-pane-id>
tmux-cli wait_idle --pane=<full-pane-id> --idle-time=3 --timeout=60
tmux-cli capture --pane=<full-pane-id>
tmux-cli send "<task text>" --pane=<full-pane-id>
tmux-cli wait_idle --pane=<full-pane-id> --idle-time=3 --timeout=<task-timeout-seconds>
tmux-cli capture --pane=<full-pane-id>
```
同一任务的 follow-up 省略 clear，重新 discovery 后执行 `send -> wait_idle -> capture`。
`tmux-cli execute` 只用于需要 exit code 的 shell command，不用于 Agent chat。相互独立且 file ownership 不重叠的
任务可以并行发送；有依赖或写入范围重叠时必须串行。
## Completion Check
只有明确的完成、阻塞或失败证据才表示 Agent 返回。单次 `wait_idle`、暂时无输出或主观耗时判断都不构成结束证据。
capture 后检查：
- completion / blocked / failed 状态；
- expected artifact 是否存在；
- validation 和 finding 结论；
- 是否仍请求工具执行或补充输入。
总控必须 review Agent 输出并自行裁决，不能直接照搬。