tmux-agent-tools

Tmux Agent 工具

快捷路径（请先阅读）

不可妥协的规则：

1. 仅使用引擎——绝不要在工作进程中输入原始 tmux。 通过 agent-tmux <cli> 子命令（send-wait、status、result、capture、stop）驱动每个工作进程；只读清单使用 tmux-agent-sessions list，而不是原始 tmux ls。原始 tmux 会绕过命名、脱敏、结果约定和清理流程。在断定引擎缺少某条命令之前，请先查看下方的功能表；仅在确有缺口时才将普通 shell 作为最后手段——并说明原因。
2. 只有在确认提交成功后，send 才算完成。 单独使用 send 可能会让文本留在输入框中、并未发送。默认使用 send-wait：它会附加一个全新的 nonce 并等待该 nonce，以确认提示词已送达。
3. 每次阻塞等待都必须设置超时时间——绝不要手动编写 sleep/轮询循环。 多个工作进程：使用一个有界的 watch --any|--all|--count <n> --timeout <s> --json …。混合引擎的工作进程组：请相信 reason:result_updated，或通过 tmux-agent-sessions 进行处理。
4. 要复用工作进程执行后续任务？ 先运行 result init，再运行 send-wait，然后运行 result wait-required——绝不要不运行 result init 就复用，否则等待会返回之前的过期结果。详情：references/multi-agent.md#persistent-teammates-worker-reuse。

快速解答：

• 任务范围明确且无需跟进？ 默认使用交互式 start（带界面）：tmux 窗格就是调试界面——通过 capture、status 或附加到窗格，可以准确查看 CLI 正在做什么，包括运行期间和事后复盘。start --headless（claude -p / codex exec）仅可在明确选择时使用：用户明确提出，或者输出可轻易验证且没人需要检查运行过程。无头模式失败后只会留下退出代码和一个 stdout 文件——实践中屡次发现，这会导致长时间盲目调试（用户裁定，2026-08-03：默认使用带界面模式）。
• 包装器不在 PATH 中？ 从此软件包中运行：<skill-dir>/scripts/agent-tmux codex …。
• 工作器显示“失败”，但窗格显示 PASS？ 退出代码不等于判定结果——重新分派任务或报告失败之前，请参阅 references/core-workflow.md#5-read-the-agents-structured-result（“退出代码不等于判定结果”）。
• 需要自动委派较大任务？ 使用 using-tmux-agent-tools 技能中的内联执行与工作器分流规则（该规则已并入其中，不再是单独的子 Agent）；详情见 references/core-workflow.md。
• 长期运行的外部 CLI 工作器（Codex 或 Claude Code）？ 使用一次 agent-tmux <cli> assign <name> <dir> <prompt-file> 调用来分派——分步骤执行（start → 初始化结果 → 发送 → 确认处理中 → 阻塞式监督）本身就是监督过程，因此由代理承载这整个过程，不做其他事（旧的逐工作器轮询代理已退役，2026-08-08）。宿主是一个监督代理——使用 sonnet low 的 general-purpose 子 Agent，其任务是运行这一次 assign 调用并报告其退出代码（参见 model-dispatch.md §4，2026-08-17/18 裁定）。禁止以任何形式在父进程前台运行 assign，包括 --detach；tmux-assign-host-gate hook 会在工具调用时拒绝此类操作。只要代理报告的状态不是终态，就必须让父进程使用 run_in_background，这不是最后手段；测量结果表明，2026-08-30 时，运行框架会在约 600 秒后回收代理的前台调用，而子 Agent 没有 TaskOutput，因此被回收的代理只能报告仍在执行中，父进程必须自行等待（被终止的子 Agent 遗留的任务不会通知任何人；事故 c48c0d3a 因此损失了 2 小时 40 分钟）。在运行目录中记录原因，且绝不要通过管道传递监听器——末尾加上 | tail 会报告 tail 的状态，因此包装器的 exit 2 会被误判为成功。除非 assign 报告某个步骤失败或用户提出要求，否则父进程不得额外轮询 status/capture/probe；使用有界的 result wait-required --wait <s> 调用收集结果。pending 结果是一个终止流程，不是判定结果：在限定时间内继续等待 → 限时结束后仍为 pending，则使用 result --path <name> 给出的字面路径，仅再提示工作器一次，然后再进行一轮有界等待 → 只有在此之后，窗格捕获内容才可作为替代，并须标注为未确认，绝不可作为已验证答案交付。注意 assign 发出的 result-path delivery UNCONFIRMED 警告——未获知路径的工作器永远无法写入 result.json，因此该 pending 状态会永久持续。拆除顺序：先停止代理，再停止其监督的工作器，否则代理会卡在一个已不可能到达的信号上。绝不要要求代理逐字返回工作器的输出——代理不得读取该输出，因此这项任务无法完成；应让工作器写入指定的产物路径，然后自行读取该文件。
• 正在编写工作器提示词？ 使用 delegation-templates 技能来组织内容：GOAL / ACCEPTANCE / REPORT + 通用页脚，以及 tmux 补充内容（禁止级联 + 字面结果路径）。
• 有新的 CLI 或 CLI 更名？ 添加包含 bin=… 的配置，然后使用 doctor --json 和 start --dry-run 验证；参见 references/profiles.md。

概述

agent-tmux <cli> <command> 可将任意 AI 编码 CLI 作为受管理的 tmux 工作器运行；claude/codex/agy 是内置预设，其他 CLI 可使用可选配置。每个 CLI 都没有单独的二进制文件——始终写作 agent-tmux <cli> <command>。

必需的预检与安全调用

在执行首条 worker 命令前：

1. 解析 wrapper bundle，不要假定它位于 PATH 中。按顺序检查： <repo-dir>/skills/tmux-agent-tools/scripts、 ~/.agents/skills/tmux-agent-tools/scripts、 ~/.claude/skills/tmux-agent-tools/scripts 和 ~/.codex/skills/tmux-agent-tools/scripts；只有在不存在 bundle 且 PATH 查找成功时，才使用不带路径的 wrapper 名称。
2. 运行解析出的 agent-tmux <cli> setup；若预检失败，则停止。
3. 将原始任务作为单独加引号的参数或提示词文件内容传递。 切勿将任务文本插入 eval、sh -c 或构造出的 shell 命令中。
4. 任务专用凭据只能通过 --secret KEY=URI 传递。切勿将凭据值嵌入任务文本或构造出的 shell 命令中。

适用场景

• 需要后续监督的长时间运行 Claude/Codex/agy/自定义 CLI 工作。
• worker 必须为父 Agent 或 wrapper 写入结构化的 result.json。
• 需要经过验证的后续发送、存活状态/状态检查、有界等待或清理。
• 多个 worker 需要通过一次 wrapper watch 调用完成第一个、全部或指定数量的任务。

命令选择

需求	使用
将 Claude Code / Codex / agy 作为 worker 运行	agent-tmux claude / agent-tmux codex / agent-tmux agy
其他任意 CLI（gemini、cursor、grok、自定义 CLI）	agent-tmux <cli>（可选 profile）
任何 worker，包括有界的一次性任务	交互式 start（带终端）——窗格 = 调试界面；默认选项
易于验证的即发即收任务，且用户已选择此方式	start --headless——以进程退出作为完成标志；失败时只留下退出代码和 stdout 文件
本地工作目录	start
仓库位于另一台主机，tmux 保持在本地	start-ssh
为一次运行指定模型	start --model <m> <name> <dir> '<prompt>'
继续现有 CLI 会话 UUID	resume（需选择启用，默认关闭）
不知道哪个 wrapper 管理某个会话	先运行 tmux-agent-sessions resolve --name <n> --json
双方交流 / 一对多工作	tmux-agent-dialogue / tmux-agent-fanout
只读清单或证据轮询	tmux-agent-sessions / tmux-agent-monitor

start 标志必须放在位置参数之前：start --exact --model <m> <name> <dir>；标志位置错误时会以状态码 2 退出。

完整功能表（所有子命令及其适用场景）：references/cheatsheets.md。

不适用场景

• 一次性 shell 命令，或简单的文件读取、搜索、测试或构建——直接运行，不要启动 worker。
• 外部可见、具有破坏性或涉及隐私敏感的工作，除非用户已明确授权。

最常用的 6 条命令

# Dispatch a prompt-file task: ONE command runs the whole verified sequence
# (start -> result init -> send --from-file -> confirm the pane is processing
# -> blocking supervise). Prefer this over hand-chaining the steps; it cannot
# be misordered and it catches "task never reached the CLI" before waiting.
agent-tmux codex assign job ~/repo /abs/path/prompt.txt

# Bounded one-shot (headed by default; add --headless only when the user opted in):
agent-tmux codex start --exact job ~/repo 'Task. Write final JSON to the wrapper-provided result path when done.'
agent-tmux codex result wait-required job --fields status,summary --wait 600 --json   # returns at process exit
agent-tmux codex supervise --result-required --silent-while-unchanged --json job       # one silent call until terminal event
agent-tmux codex stop job

# Interactive one-worker flow (only when follow-ups are needed): start -> send-wait -> supervise -> stop.
agent-tmux codex start --exact worker ~/repo 'Task. Write final JSON to the wrapper-provided result path when done.'
agent-tmux codex send-wait worker 'Follow-up instruction.' 180
agent-tmux codex status --json worker
agent-tmux codex result --json --wait 30 worker
agent-tmux codex stop worker

# Multiple workers: block on first/all/N completion with one bounded call.
agent-tmux codex watch --any --timeout 600 --json w1 w2 w3

完整操作指南：references/core-workflow.md。

v5 ledger（非 Claude 主机）

Codex、Cursor 和 agy 不会加载 Claude function-hook mod。它们使用同一 v5 ledger，即状态根目录下的 .v3/ 树。此 bundle 中的 Node 入口：scripts/lib/collector.node.ts（每个主机会话一个 collector）和 scripts/lib/workers.cli.node.ts（cancel、unlock）。workers TUI 为 scripts/tmux-agent-tui [--session <id>] [--cwd <dir>]：指定会话 ID 时，它是该会话 worker 的所有者，并对这些 worker 执行操作；不指定时，它是只读查看器。它需要 Node >= 22.18 和 TTY（否则以状态码 2 退出；--help 无需这些条件）。技能更新后，请重新运行 scripts/install-bin：它只会链接上次运行时已存在的脚本，agent-tmux <cli> doctor 会指出缺失的链接。目录结构、所有权和交付方式见仓库文档 mods/tmux-agent/README.md（收集端）；此技能不再重复说明该目录结构。Bash guard（tool.call）仅适用于 Claude。在同一 tailnet 的多台主机之间：使用 scripts/tmux-agent-relay（ensure、send <host> <worker> <text>、roster）和 start-ssh --sentinel … --notify（远程退出状态会以 exit_source: "relay" 的形式出现在 status --json 中）；信任模型和拒绝规则见 README 中的 “Relay (tailnet)” 一节。

result.json 完成契约

Agent 将 $TMUX_AGENT_DIR/<name>/result.json 写入文件，包含 schema_version: 1、规范的 status（success|failed|blocked|needs-input）、summary、artifacts 和 errors（可选的 verdict/decision，以及 commit——当成功交付提交时，填写完整的 40 位十六进制 sha；tmux-agent mod 会检查它是否为从派发基准（episode 开始时的 HEAD）派生的提交，并交付 commit <sha12> verified (…) 或 success claimed, commit <sha> NOT verified: <reason>；未提交时省略）。会话首次发送提示词时会注入结果文件的字面路径（默认适用于每个系列）；工作器不能依赖工具沙箱中的 $TMUX_AGENT_RESULT。按此顺序分支——存在有效结果时，绝不要抓取窗格内容：.present -> .valid -> .body。

--fields 指定的是该契约中的键，而不是提示词占位符：使用 artifact_path（没有工作器会写入此字段）收集结果，导致两名已完成的工作器在 2026-09-08 时约有 24 分钟未被收集。请求 status,summary，读取 .body，并通过 .body.artifacts 请求生成的文件。现在，终止结果缺少所请求字段时会退出 3（event:"contract-mismatch"，附带工作器 body），而不再等待——请修正字段列表，不要重新派发。无法启动 CLI 时，会在 assign 步骤 0 退出 4，并附带 blocked_reason（keychain_locked、login_required、quota_exhausted、cli_not_found），且不会启动任何任务：报告阻塞原因，不要等待。对于每次换行都会提交的 TUI，请使用 assign --prompt-delivery file-ref 派发（配置文件 prompt_delivery；agy 已提供此功能）——agy 将一条粘贴的提示词接收成 12 条单独输入，GOAL 和 CONTEXT 始终未送达，却仍报告 assigned:true。

agent-tmux codex result --json --wait 30 worker
agent-tmux codex supervise --result-required --silent-while-unchanged --json worker

如果 .present:false，说明 Agent 从未写入该文件——使用 result --path <name> 获取字面路径并重新发送提示词。完整架构、完整示例、status --json 字段、审批门退出代码、并发模型：references/contracts.md。

安全

• 包装器默认使用宽松的 CLI 标志（Claude 使用 --dangerously-skip-permissions，Codex 使用 --yolo）。未经用户明确授权，切勿将其用于破坏性、隐私敏感、对外可见、涉及付款或不可逆的工作。
• 如果窗格似乎正在等待确认，status --json 会报告 confirmation_detected:true 和 blocked_reason。它不会自动接受；只有在你信任该操作后才予以确认。
• 启动多个工作器之前：询问用户为每个工作器指定的工具、模型和工作强度，设置工作器数量上限，并在每条提示词中禁止级联启动。详情：references/multi-agent.md。
• 密钥注入（--secret KEY=URI，失败时关闭）和审计日志（TMUX_AGENT_TOOLS_AUDIT_LOG）：references/security.md。

参考资料

仅在遇到相关场景时加载这些资料——日常使用不需要：

• references/core-workflow.md — 完整的单工作器工作流、会话命名、远程会话、同行评审、审批门、内联与工作器之间的选择门。
• references/profiles.md — 自定义 CLI 配置键、优先级、示例、检测覆盖项。
• references/cheatsheets.md — 完整功能表、场景命令、标记陷阱、故障排查。
• references/multi-agent.md — 对话/扇出规则、桥接模式、SSH 参与者、github-comment 行为。
• references/contracts.md — status --json/result.json 架构、审批退出代码、并发、清单/清理。
• references/security.md — 密钥注入、审计日志、环境覆盖项、预检。
• references/troubleshooting.md — 卡住、未发送、标记过期等场景的故障模式与修复方法。
• references/recipes.md — 可直接复制粘贴的工作流（审批门、扇出、DAG）。

随附的架构

schemas/ 附带 result-status-summary.schema.json 和 fanout-summary.schema.json——当磁盘上找不到其他副本时，脚本已会将其用作验证 result.json 的离线回退方案。

agents/ 子 Agent 包（tmux-delegate.md、claude-oneshot.md、codex-oneshot.md）已弃用——请参阅 CHANGELOG。它们采用的内联与工作进程判定规则以及一次性转发模式，如今已纳入 using-tmux-agent-tools 技能的决策树；现在无需再向 ~/.claude/agents/ 安装任何内容。