using-tmux-agent-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

using-tmux-agent-tools

使用tmux-agent-tools

You decide inline vs worker, pick the wrapper, then defer to the

tmux-agent-tools

hub skill for mechanics. You are not a wrapper.

你需要决定采用inline还是worker模式，选择对应的包装器，然后将具体操作委托给

tmux-agent-tools

核心skill处理。你本身并非包装器。

BYPASS — inline is the DEFAULT

绕过规则 — inline 为默认方式

Handle the task inline unless a named exception below fires. This is a forcing gate, not ambient advice: record the winner BY NAME for inline and worker outcomes alike — "it looks substantial" or "this is trivial" without naming a bullet is not a valid gate pass.

Overrides (win over everything):

```
explicit-inline
```
— the caller says "inline" / "quick" / "don't spawn a worker".
```
single-known-command
```
— the whole task is one already-known command (test, build, lint), even when it touches many files.

Delegate ONLY when one of these four exceptions fires:

```
independent-context
```
— the read-plan-write volume would flood the main context window (the commander does not do grunt work).
```
parallel-or-background
```
— work must proceed while the main session continues, or several independent tasks run at once.
```
different-engine
```
— the stage needs another CLI/model (second-model review, imagegen → Codex, profile-specific work).
```
existing-teammate
```
— a follow-up in the same repo/domain where a persistent worker already holds context: send to THAT worker (after
```
result init
```
); never start a duplicate.

No exception fired → inline, receipt

no-delegate-trigger

除非触发以下指定例外情况，否则以inline方式处理任务。这是强制规则，而非一般性建议：无论最终选择inline还是worker模式，都必须明确记录触发的规则名称——仅以“任务看起来复杂”或“任务很简单”为由而未明确对应规则项，不符合规则要求。

优先级最高的覆盖规则（优于所有其他规则）：

```
explicit-inline
```
— 调用者明确要求“inline”/“快速处理”/“不要启动worker”。
```
single-known-command
```
— 整个任务仅包含一个已知命令（测试、构建、代码检查等），即使该命令涉及多个文件。

仅当触发以下四个例外情况之一时，才进行委托：

```
independent-context
```
— 读取-规划-写入的数据量会占用主上下文窗口的大量资源（指挥官不执行 grunt work）。
```
parallel-or-background
```
— 工作必须在主会话持续运行的同时进行，或者需要同时执行多个独立任务。
```
different-engine
```
— 任务阶段需要使用另一个CLI/模型（如二次模型评审、图像生成→Codex、特定配置文件的工作）。
```
existing-teammate
```
— 在同一仓库/领域的后续任务中，已有一个持久化worker持有上下文：将任务发送给该worker（执行
```
result init
```
之后）；绝不要启动重复的worker。

未触发任何例外情况 → 采用inline方式，记录

no-delegate-trigger

。

QUESTIONS — if delegating, one-shot or teammate? State which, and why.

疑问 — 若进行委托，选择一次性worker还是协作worker？说明选择类型及原因。

One-shot (one bounded answer, no follow-up of any kind) → interactive
```
start --task-shape bounded
```
(headed; the pane is the debug surface —
```
--headless
```
only when the user explicitly opted in); exactly one
```
result wait-required
```
, then
```
stop
```
unless keepalive was requested. Shell-safe name matching
```
[A-Za-z0-9._-]+
```
; arrange failure-safe cleanup equivalent to
```
trap cleanup EXIT
```
(success, wait failure, or interruption).
Teammate (expect a second message to the SAME worker) → interactive
```
start
```
(no
```
--headless
```
); do not
```
stop
```
between tasks; reuse via
```
skills/tmux-agent-tools/references/multi-agent.md#persistent-teammates-worker-reuse
```
.

一次性（One-shot）（任务有明确边界，无任何后续操作）→ 交互式执行
```
start --task-shape bounded
```
（带界面；面板作为调试界面——仅当用户明确选择时才使用
```
--headless
```
）；执行恰好一次
```
result wait-required
```
，除非请求保持存活，否则执行
```
stop
```
。使用符合
```
[A-Za-z0-9._-]+
```
格式的安全Shell名称；安排等效于
```
trap cleanup EXIT
```
的故障安全清理机制（适用于成功、等待失败或中断场景）。
协作worker（Teammate）（预期会向同一个worker发送第二条消息）→ 交互式执行
```
start
```
（不使用
```
--headless
```
）；任务间不执行
```
stop
```
；通过
```
skills/tmux-agent-tools/references/multi-agent.md#persistent-teammates-worker-reuse
```
实现复用。

ONE OWNER —

assign

is the supervision boundary

单一所有者 —

assign

为监管边界

Dispatch one external CLI worker with one blocking

agent-tmux <cli> assign <name> <directory> <prompt-file>

call.

assign

owns start, result init, verified send, processing confirmation, and terminal supervision. Do not add a native supervision proxy: while

assign

runs, no second supervisor may concurrently call

status

capture

probe

result

, or another wait. Hosting that one

assign

call inside a sub-agent is not a proxy — see below.

Keep the long supervise off the expensive main context: host that one blocking

assign

in a cheap general-purpose sub-agent (model override, e.g. Sonnet), or in a background task. The host still makes exactly one

assign

call — it hosts, it does not proxy. Exception — a harness that reaps long-running tasks (local Claude Code kills them after ~10 min, together with any tmux server in the task tree) cannot hold the blocking wait at all: there, dispatch with

assign --detach

in a short foreground call, then harvest with bounded

result wait-required --wait <s>

calls. A single diagnostic call is allowed only when dispatch or harvest reports an abnormal result.

通过一个阻塞式

agent-tmux <cli> assign <name> <directory> <prompt-file>

调用，调度一个外部CLI worker。

assign

负责启动、结果初始化、验证发送、处理确认及终端监管。不要添加原生监管代理：当

assign

运行时，不得有第二个监管者同时调用

status

、

capture

、

probe

、

result

或其他等待命令。将该

assign

调用托管在子agent中不属于代理行为——详见下文。

避免占用昂贵的主上下文进行长时间监管：将该阻塞式

assign

调用托管在低成本的通用子agent中（可覆盖模型，如Sonnet），或作为后台任务。托管者仍仅执行一次

assign

调用——仅负责托管，不承担代理职责。例外情况——若有工具会终止长时间运行的任务（例如本地Claude Code会在约10分钟后终止任务，以及任务树中的任何tmux服务器），则完全无法保持阻塞等待：此时需通过前台短调用执行

assign --detach

进行调度，然后通过有限次数的

result wait-required --wait <s>

调用获取结果。仅当调度或获取结果报告异常时，才允许进行一次诊断调用。

SELECT — wrapper by task shape

选择 — 根据任务类型选择包装器

Loop-shaped chain (audit / plan→build / consensus / triage) → the
```
using-workflows
```
skill, not this router.
ONE coding CLI as a supervised worker (most common) →
```
agent-tmux <cli>
```
(claude / codex / agy built in; gemini, cursor, custom via profile).
Same prompt across MANY workers →
```
tmux-agent-fanout
```
; bounded TWO-party exchange →
```
tmux-agent-dialogue
```
. BOTH require the user's explicit authorization for count, tool, model, and effort — never assume it.
Inspect / housekeep existing sessions →
```
tmux-agent-sessions
```
(resolve, inventory, cleanup) · live overview →
```
tmux-agent-dashboard
```
.
Background & scheduled →
```
tmux-agent-cron
```
· dependencies →
```
tmux-agent-dag
```
· evidence polling →
```
tmux-agent-monitor
```
· alerts →
```
tmux-agent-notify
```
.

Records →

tmux-agent-audit

tmux-agent-history

tmux-agent-replay

· worktrees →

tmux-agent-worktrees

Then read the chosen wrapper's row in the canonical capability table:

skills/tmux-agent-tools/references/cheatsheets.md

→ Full script capability table. Never paraphrase that table from memory.

循环型任务链（审计/规划→构建/共识/分类）→ 使用
```
using-workflows
```
skill，而非本路由。
单个受监管的编码CLI worker（最常见场景）→
```
agent-tmux <cli>
```
（内置claude/codex/agy；gemini、cursor及自定义工具可通过配置文件添加）。
同一提示信息分发至多个worker →
```
tmux-agent-fanout
```
；有限的双向交互 →
```
tmux-agent-dialogue
```
。这两种场景均需用户明确授权数量、工具、模型及工作量——绝不要自行假设。
检查/管理现有会话 →
```
tmux-agent-sessions
```
（解析、盘点、清理）· 实时概览 →
```
tmux-agent-dashboard
```
。
后台及定时任务 →
```
tmux-agent-cron
```
· 依赖管理 →
```
tmux-agent-dag
```
· 证据轮询 →
```
tmux-agent-monitor
```
· 告警 →
```
tmux-agent-notify
```
。

记录 →

tmux-agent-audit

tmux-agent-history

tmux-agent-replay

· 工作树 →

tmux-agent-worktrees

。

然后查看标准功能表中所选包装器对应的条目：

skills/tmux-agent-tools/references/cheatsheets.md

→ 完整脚本功能表。绝不要凭记忆转述该表内容。

DEFER — non-negotiable gates (mechanics live in the hub skill)

委托 — 不可协商的规则（具体实现由核心skill负责）

Prompt shape: every worker prompt filled from
```
delegation-templates
```
(GOAL / ACCEPTANCE / REPORT + common footer + tmux addendum).
No cascade: every worker prompt carries the literal ban "Do not spawn additional tmux sessions or delegate further." Only a Claude Code worker may still use its own in-process
```
Agent
```
tool (CLI-supervised, depth-capped); Codex workers have no equivalent exception.
Engine-only, never raw tmux: no hand-rolled
```
send-keys
```
/
```
capture-pane
```
/
```
new-session
```
. Plain shell only for genuine gaps — say so.
Verify every send: prefer
```
send-wait
```
. A timeout means submission is UNCONFIRMED — check liveness (
```
status --json
```
;
```
probe --metric tool_active
```
, or
```
--metric active_spinner
```
for claude) and resend only if idle. Never nudge with a raw Enter.
Preflight & safe invocation: follow the hub skill's preflight contract (resolve the wrapper bundle, run
```
setup
```
, prompt-file for task text,
```
--secret KEY=URI
```
for credentials) before the first worker command.
After the result: collect (
```
result --json
```
) →
```
stop
```
, or keep the teammate per the reuse protocol. Failure/blocked → follow up on the same worker, or escalate via
```
using-workflows
```
```
findings-triage
```
.

提示格式：每个worker的提示信息均从
```
delegation-templates
```
中填充（包含GOAL/ACCEPTANCE/REPORT + 通用页脚 + tmux补充内容）。
禁止级联：每个worker的提示信息必须包含明确禁令：“Do not spawn additional tmux sessions or delegate further.”（不得启动额外的tmux会话或进一步委托任务）。仅Claude Code worker仍可使用其自身进程内的
```
Agent
```
工具（受CLI监管，有深度限制）；Codex worker无此例外权限。
仅使用引擎，绝不直接操作tmux：不得手动编写
```
send-keys
```
/
```
capture-pane
```
/
```
new-session
```
命令。仅当确实存在功能缺口时，才可使用纯Shell命令——需明确说明。
验证每一次发送：优先使用
```
send-wait
```
。超时意味着提交未确认——需检查活跃度（
```
status --json
```
；针对claude使用
```
probe --metric tool_active
```
或
```
--metric active_spinner
```
），仅当worker处于空闲状态时才重新发送。绝不要用直接按回车键的方式催促。
预检查与安全调用：在首次执行worker命令之前，遵循核心skill的预检查约定（解析包装器包、运行
```
setup
```
、为任务文本准备prompt-file、使用
```
--secret KEY=URI
```
传递凭据）。
结果处理：收集结果（
```
result --json
```
）→ 执行
```
stop
```
，或根据复用协议保留协作worker。若任务失败/阻塞 → 在同一个worker上跟进处理，或通过
```
using-workflows
```
的
```
findings-triage
```
流程升级处理。

NOT-FOUND

未匹配场景

Another skill already owns the task (commit workflow, PR review, …) → receipt

other-skill-owner

, route there — no tmux worker. A capability no wrapper covers → plain shell as a last resort, stated explicitly. Hub reference:

skills/tmux-agent-tools/SKILL.md

(fast paths, result.json contract, safety,

references/

若任务已由其他skill负责（提交工作流、PR评审等）→ 记录

other-skill-owner

，将任务路由至对应skill——不使用tmux worker。若没有包装器覆盖对应功能 → 最后才使用纯Shell命令，需明确说明。核心参考文档：

skills/tmux-agent-tools/SKILL.md

（快速路径、result.json约定、安全机制、

references/

目录）。

using-tmux-agent-tools

Original

Translation

using-tmux-agent-tools

使用tmux-agent-tools

BYPASS — inline is the DEFAULT

绕过规则 — inline 为默认方式

QUESTIONS — if delegating, one-shot or teammate? State which, and why.

疑问 — 若进行委托，选择一次性worker还是协作worker？说明选择类型及原因。

ONE OWNER —
`assign`
is the supervision boundary

单一所有者 —
`assign`
为监管边界

SELECT — wrapper by task shape

选择 — 根据任务类型选择包装器

DEFER — non-negotiable gates (mechanics live in the hub skill)

委托 — 不可协商的规则（具体实现由核心skill负责）

NOT-FOUND

未匹配场景

using-tmux-agent-tools

Original

Translation

using-tmux-agent-tools

使用tmux-agent-tools

BYPASS — inline is the DEFAULT

绕过规则 — inline 为默认方式

QUESTIONS — if delegating, one-shot or teammate? State which, and why.

疑问 — 若进行委托，选择一次性worker还是协作worker？说明选择类型及原因。

ONE OWNER — assign is the supervision boundary

单一所有者 — assign为监管边界

SELECT — wrapper by task shape

选择 — 根据任务类型选择包装器

DEFER — non-negotiable gates (mechanics live in the hub skill)

委托 — 不可协商的规则（具体实现由核心skill负责）

NOT-FOUND

未匹配场景

ONE OWNER —
`assign`
is the supervision boundary

单一所有者 —
`assign`
为监管边界