tmux-agent-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tmux Agent Tools

Fast paths (read this first)

快速路径（请先阅读此部分）

Non-negotiable rules:

Engine-only — never type raw
tmux
at a worker. Drive every worker through
```
agent-tmux <cli>
```
subcommands (
```
send-wait
```
,
```
status
```
,
```
result
```
,
```
capture
```
,
```
stop
```
); read-only inventory is
```
tmux-agent-sessions list
```
, not raw
```
tmux ls
```
. Raw
```
tmux
```
bypasses naming, redaction, result contracts, and cleanup. Before concluding the engine lacks a command, check the capability table below; plain shell is a last resort for genuine gaps — say why.
A
send
is not done until submission is verified. Bare
```
send
```
can leave text unsent in the input box. Default to
```
send-wait
```
: it appends a fresh nonce and waits for it, confirming the prompt landed.
Every blocking wait takes a timeout — never hand-roll
sleep
/polling loops. Multiple workers: one bounded
```
watch --any|--all|--count <n> --timeout <s> --json …
```
. Mixed-engine fleets: trust
```
reason:result_updated
```
or resolve with
```
tmux-agent-sessions
```
.
Reusing a worker for a follow-up task?
```
result init
```
first, then
```
send-wait
```
, then
```
result wait-required
```
— never reuse without
```
result init
```
, or the wait returns the stale prior result. Details:
```
references/multi-agent.md#persistent-teammates-worker-reuse
```
.

Fast answers:

Bounded task with no follow-ups? Default to interactive
```
start
```
(headed): the tmux pane is the debug surface —
```
capture
```
,
```
status
```
, or attaching shows exactly what the CLI is doing, mid-run and post-mortem.
```
start --headless
```
(
```
claude -p
```
/
```
codex exec
```
) is OPT-IN only: user explicitly asks for it, or the output is trivially verifiable and nobody will need to inspect the run. A headless failure leaves only an exit code and a stdout file — repeatedly observed to cost long blind-debugging sessions (user ruling 2026-08-03: headed by default).
Wrapper not on PATH? Run it from this bundle:
```
<skill-dir>/scripts/agent-tmux codex …
```
.
Worker "failed" but the pane says PASS? Exit code is not the verdict — see
```
references/core-workflow.md#5-read-the-agents-structured-result
```
("Exit code is not the verdict") before re-dispatching or reporting failure.
Auto-delegate substantial work? Use the inline-vs-worker gate in the
```
using-tmux-agent-tools
```
skill (absorbed there, no longer a separate subagent); details live in
```
references/core-workflow.md
```
.
Long-running external CLI worker (Codex or Claude Code)? Dispatch it with ONE
```
agent-tmux <cli> assign <name> <dir> <prompt-file>
```
call — the stepwise sequence (start → result init → send → confirm-processing → blocking supervise) IS the supervision, so no separate per-worker supervision proxy is spawned (proxy pattern retired 2026-08-08, replaced by
```
assign
```
). Run the single blocking call where a long wait is appropriate (a background task, or one cheap sub-agent when the runtime caps foreground timeouts); the parent MUST NOT additionally poll
```
status
```
/
```
capture
```
/
```
probe
```
unless
```
assign
```
reports a failed step or the user asks. If the harness reaps long background tasks (killing a tmux server spawned inside the task's process tree with them), use
```
assign --detach
```
in a short foreground call instead — dispatch stays fully verified, then harvest with bounded
```
result wait-required --wait <s>
```
calls.
Writing the worker prompt? Shape it with the
```
delegation-templates
```
skill: GOAL / ACCEPTANCE / REPORT + common footer, plus its tmux addendum (no-cascade ban + literal result path).
New or renamed CLI? Add a profile with
```
bin=…
```
, then prove it with
```
doctor --json
```
and
```
start --dry-run
```
; see
```
references/profiles.md
```
.

不可违背的规则：

仅通过引擎操作——绝不要在工作者中直接输入
tmux
命令。所有工作者都必须通过
```
agent-tmux <cli>
```
子命令（
```
send-wait
```
、
```
status
```
、
```
result
```
、
```
capture
```
、
```
stop
```
）进行操作；只读清单使用
```
tmux-agent-sessions list
```
，而非原生
```
tmux ls
```
。直接使用
```
tmux
```
会绕过命名、脱敏、结果约定和清理流程。在判定引擎缺少某条命令前，请先查看下方的功能表；只有在确实存在功能缺口时才使用纯shell命令——并说明原因。
只有在提交验证完成后，
send
操作才算完成。单纯的
```
send
```
可能会导致文本留在输入框中未发送。默认使用
```
send-wait
```
：它会附加一个新的随机数并等待确认，确保提示已成功送达。
所有阻塞等待都必须设置超时——绝不要手动编写
sleep
/轮询循环。多工作者场景：使用一个带限制的
```
watch --any|--all|--count <n> --timeout <s> --json …
```
命令。混合引擎集群：信任
```
reason:result_updated
```
或通过
```
tmux-agent-sessions
```
解决。
要为后续任务复用工作者？ 先执行
```
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
```
skill中的内联vs工作者网关（已整合到该skill中，不再是独立子代理）；详情见
```
references/core-workflow.md
```
。
长时间运行的外部CLI工作者（Codex或Claude Code）？ 通过一次
```
agent-tmux <cli> assign <name> <dir> <prompt-file>
```
调用进行调度——分步流程（启动→result初始化→发送→确认处理→阻塞监控）即为监控流程，因此无需生成单独的每个工作者监控代理（代理模式已于2026-08-08停用，替换为
```
assign
```
）。在适合长时间等待的位置运行单个阻塞调用（后台任务，或在运行时限制前台超时的轻量子代理）；除非
```
assign
```
报告步骤失败或用户要求，否则父进程不得额外轮询
```
status
```
/
```
capture
```
/
```
probe
```
。如果工具收割长后台任务（杀死与任务进程树一起生成的tmux服务器），则在短前台调用中使用
```
assign --detach
```
——调度仍会完全验证，然后通过带限制的
```
result wait-required --wait <s>
```
调用获取结果。
编写工作者提示？ 使用
```
delegation-templates
```
skill进行构建：目标/验收标准/报告 + 通用页脚，加上tmux补充说明（禁止级联 + 字面结果路径）。
新增或重命名CLI？ 使用
```
bin=…
```
添加配置文件，然后通过
```
doctor --json
```
和
```
start --dry-run
```
验证；见
```
references/profiles.md
```
。

Overview

概述

agent-tmux <cli> <command>

runs any AI coding CLI as a managed tmux worker; claude/codex/agy are built-in presets, other CLIs use an optional profile. The old

claude-tmux

codex-tmux

agy-tmux

shims are DEPRECATED (removal: v0.39) — always spell

agent-tmux <cli> <command>

agent-tmux <cli> <command>

可将任意AI编码CLI作为托管tmux工作者运行；claude/codex/agy为内置预设，其他CLI可使用可选配置文件。旧版

claude-tmux

codex-tmux

agy-tmux

垫片已废弃（移除版本：v0.39）——请始终使用完整命令

agent-tmux <cli> <command>

。

Required preflight and safe invocation

必要的预检查与安全调用

Before the first worker command:

Resolve the wrapper bundle instead of assuming PATH. Probe, in order,

<repo-dir>/skills/tmux-agent-tools/scripts

~/.agents/skills/tmux-agent-tools/scripts

~/.claude/skills/tmux-agent-tools/scripts

, and

~/.codex/skills/tmux-agent-tools/scripts

; use bare wrapper names only when no bundle exists and PATH lookup succeeds.

Run the resolved
```
agent-tmux <cli> setup
```
and stop if preflight fails.
Pass the raw task as a separately quoted argument or prompt-file content. Never interpolate task text into
```
eval
```
,
```
sh -c
```
, or a constructed shell command.
Pass task-specific credentials only through
```
--secret KEY=URI
```
. Never embed credential values in task text or a constructed shell command.

首次运行工作者命令前：

先定位包装器包，而非假设它在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

；仅当不存在包且PATH查找成功时，才使用裸包装器名称。

运行已定位的
```
agent-tmux <cli> setup
```
，如果预检查失败则停止操作。
将原始任务作为单独引用的参数或提示文件内容传递。绝不要将任务文本插入
```
eval
```
、
```
sh -c
```
或构造的shell命令中。
仅通过
```
--secret KEY=URI
```
传递任务特定凭据。绝不要将凭据值嵌入任务文本或构造的shell命令中。

When to use

使用场景

Long-running Claude/Codex/agy/custom CLI work that needs later supervision.
A worker must write structured
```
result.json
```
for a parent agent or wrapper.
You need verified follow-up sends, liveness/status checks, bounded waits, or cleanup.
Multiple workers need first/all/N completion via one wrapper
```
watch
```
call.

需要后续监控的长时间运行的Claude/Codex/agy/自定义CLI工作。
工作者必须为父代理或包装器编写结构化
```
result.json
```
。
需要验证后续发送、存活状态检查、有限等待或清理操作。
多个工作者需要通过一个包装器
```
watch
```
调用实现首个/全部/N个完成。

Command choice

命令选择

Need	Use
Run Claude Code / Codex / agy as a worker	`agent-tmux claude` / `agent-tmux codex` / `agent-tmux agy`
Any other CLI (gemini, cursor, grok, custom)	`agent-tmux <cli>` (+ optional profile)
Any worker, including bounded one-shots	interactive `start` (headed) — pane = debug surface; DEFAULT
Trivially verifiable fire-and-collect, user opted in	`start --headless` — completion = process exit; failures leave only exit code + stdout file
Local working directory	`start`
Repo on another host, tmux stays local	`start-ssh`
Pin a model for one run	`start --model <m> <name> <dir> '<prompt>'`
Continue an existing CLI session UUID	`resume` (opt-in, off by default)
Don't know which wrapper owns a session	`tmux-agent-sessions resolve --name <n> --json` first
Two-party exchange / one-to-many work	`tmux-agent-dialogue` / `tmux-agent-fanout`
Read-only inventory or evidence polling	`tmux-agent-sessions` / `tmux-agent-monitor`

Start flags precede positionals:

start --exact --model <m> <name> <dir>

; a misplaced flag exits 2.

Full capability table (every subcommand + when to use it):

references/cheatsheets.md

需求	使用命令
将Claude Code / Codex / agy作为工作者运行	`agent-tmux claude` / `agent-tmux codex` / `agent-tmux agy`
其他任意CLI（gemini、cursor、grok、自定义）	`agent-tmux <cli>` （+ 可选配置文件）
任意工作者，包括有限一次性任务	交互式 `start` （带界面）——面板=调试界面；默认选项
可轻松验证的即发即收任务，且用户已选择使用	`start --headless` ——完成=进程退出；失败仅留下退出码 + stdout文件
本地工作目录	`start`
仓库在另一主机，tmux保留在本地	`start-ssh`
为单次运行固定模型	`start --model <m> <name> <dir> '<prompt>'`
继续现有CLI会话UUID	`resume` （可选启用，默认关闭）
不知道哪个包装器拥有会话	先运行 `tmux-agent-sessions resolve --name <n> --json`
双向交互 / 一对多工作	`tmux-agent-dialogue` / `tmux-agent-fanout`
只读清单或证据轮询	`tmux-agent-sessions` / `tmux-agent-monitor`

启动标志需位于位置参数之前：

start --exact --model <m> <name> <dir>

；标志位置错误会导致退出码为2。

完整功能表（所有子命令+使用场景）：

references/cheatsheets.md

。

When not to use

不适用场景

A one-off shell command or a simple file read, search, test, or build — run it directly instead of spawning a worker.
Externally visible, destructive, or privacy-sensitive work unless the user has already authorized it.

一次性shell命令或简单的文件读取、搜索、测试或构建——直接运行，无需生成工作者。
外部可见、破坏性或隐私敏感的工作，除非用户已明确授权。

The 6 commands you need most

最常用的6条命令

bash

undefined

bash

undefined

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

#（启动→result初始化→send --from-file→确认面板正在处理 #→阻塞监控）。优先使用此命令而非手动链式执行步骤；它不会出现顺序错误，且会在等待前检测“任务未送达CLI”的情况。 agent-tmux codex assign job ~/repo /abs/path/prompt.txt

Bounded one-shot (headed by default; add --headless only when the user opted in):

有限一次性任务（默认带界面；仅当用户选择时添加--headless）：

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

agent-tmux codex start --exact job ~/repo '任务。完成后将最终JSON写入包装器提供的结果路径。' agent-tmux codex result wait-required job --fields status,summary --wait 600 --json # 进程退出时返回结果 agent-tmux codex supervise --result-required --silent-while-unchanged --json job # 单次静默调用，直到终端事件发生 agent-tmux codex stop job

Interactive one-worker flow (only when follow-ups are needed): start -> send-wait -> supervise -> stop.

交互式单工作者流程（仅当需要后续操作时使用）：启动→send-wait→监控→停止。

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

agent-tmux codex start --exact worker ~/repo '任务。完成后将最终JSON写入包装器提供的结果路径。' agent-tmux codex send-wait worker '后续指令。' 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.

多工作者场景：通过一条带限制的调用阻塞等待首个/全部/N个完成。

agent-tmux codex watch --any --timeout 600 --json w1 w2 w3


Full walkthrough: `references/core-workflow.md`.

agent-tmux codex watch --any --timeout 600 --json w1 w2 w3


完整演练：`references/core-workflow.md`。

result.json completion contract

result.json完成约定

Agents write

$TMUX_AGENT_DIR/<name>/result.json

with

schema_version: 1

, canonical

status

(

success|failed|blocked|needs-input

summary

artifacts

, and

errors

(optional

verdict

decision

). Codex/generic prompt sends inject the literal result path once per session; the worker cannot rely on

$TMUX_AGENT_RESULT

inside tool sandboxes. Branch in this order — never scrape the pane when a valid result exists:

.present -> .valid -> .body

bash

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

.present:false

, the agent never wrote the file — re-prompt with the literal path from

result --path <name>

. Full schema, worked example,

status --json

fields, approval-gate exit codes, concurrency model:

references/contracts.md

代理会将结果写入

$TMUX_AGENT_DIR/<name>/result.json

，包含

schema_version: 1

、标准

status

（

success|failed|blocked|needs-input

）、

summary

、

artifacts

和

errors

（可选

verdict

decision

）。Codex/通用提示发送会在每个会话中注入字面结果路径；工作者在工具沙箱中无法依赖

$TMUX_AGENT_RESULT

。按以下顺序判断——当存在有效结果时，绝不要抓取面板内容：

.present -> .valid -> .body

。

bash

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

如果

.present:false

，说明代理从未写入该文件——使用

result --path <name>

获取的字面路径重新提示。完整 schema、示例、

status --json

字段、审批网关退出码、并发模型：

references/contracts.md

。

Safety

安全注意事项

Wrappers use permissive CLI flags by default (
```
--dangerously-skip-permissions
```
for Claude,
```
--yolo
```
for Codex). Never use for destructive, privacy-sensitive, externally visible, payment, or irreversible work without explicit user authorization.
```
status --json
```
reports
```
confirmation_detected:true
```
plus
```
blocked_reason
```
when a pane appears to wait for confirmation. It does not auto-accept; answer only after you trust it.
Before spawning more than one worker: ask the user for tool+model+effort per worker, set a worker upper bound, and forbid cascade spawning in every prompt. Details:
```
references/multi-agent.md
```
.

Secret injection (

--secret KEY=URI

, fail-closed) and audit log (

TMUX_AGENT_TOOLS_AUDIT_LOG

references/security.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

参考文档

Load these only when you hit the relevant scenario — they are not needed for routine use:

```
references/core-workflow.md
```
— full single-worker workflow, session naming, remote sessions, peer-review, approval gates, the inline-vs-worker gate.
```
references/profiles.md
```
— custom CLI profile keys, precedence, examples, detection overrides.
```
references/cheatsheets.md
```
— full capability table, scenario commands, marker pitfalls, failure triage.
```
references/multi-agent.md
```
— dialogue/fanout rules, bridge pattern, SSH participants, github-comment behavior.
```
references/contracts.md
```
—
```
status --json
```
/
```
result.json
```
schemas, approval exit codes, concurrency, inventory/cleanup.
```
references/security.md
```
— secret injection, audit log, environment overrides, pre-flight checks.
```
references/troubleshooting.md
```
— failure modes and fixes for stuck/unsent/stale-marker scenarios.
```
references/recipes.md
```
— copy-pasteable workflows (approval gate, fanout, DAG).

仅在遇到相关场景时加载这些文档——日常使用无需查看：

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

Bundled schemas

捆绑schema

schemas/

ships

result-status-summary.schema.json

and

fanout-summary.schema.json

— the offline fallback the scripts already resolve for

result.json

validation when no other copy is found on disk.

The

agents/

subagent bundle (

tmux-delegate.md

claude-oneshot.md

codex-oneshot.md

) is retired — see CHANGELOG. The inline-vs-worker gate and the one-shot forwarding pattern they carried now live in the

using-tmux-agent-tools

skill's decision tree; there is nothing to install into

~/.claude/agents/

anymore.

schemas/

目录包含

result-status-summary.schema.json

和

fanout-summary.schema.json

——当磁盘上未找到其他副本时，脚本会使用这些离线副本进行

result.json

验证。

agents/

子代理包（

tmux-delegate.md

、

claude-oneshot.md

、

codex-oneshot.md

）已停用——查看CHANGELOG。它们承载的内联vs工作者网关和一次性转发模式现在位于

using-tmux-agent-tools

skill的决策树中；无需再安装到

~/.claude/agents/

目录中。