跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 tmux-agent-tools

Tmux Agent Tools

通过代理-tmux <cli> <command>(加上tmux-agent-sessions和其他捆绑工具)管理管理 tmux 工人的 AI 编码 CLI 的机械库。 入站点是使用-tmux-agent-tools路由器技巧——首先通过它;读取它所遵从的包装力学的这一技巧. 覆盖开始/发送等待/状态/结果/停止,结构化结果.json 完成,多工人监视,自定义的CLI简介,以及有界限的对话/fanout. 不用于普通tmux配置,主题,非tmux无头CLI使用,或人类团队辩论.

233 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

通过代理-tmux <cli> <command>(加上tmux-agent-sessions和其他捆绑工具)管理管理 tmux 工人的 AI 编码 CLI 的机械库。 入站点是使用-tmux-agent-tools路由器技巧——首先通过它;读取它所遵从的包装力学的这一技巧. 覆盖开始/发送等待/状态/结果/停止,结构化结果.json 完成,多工人监视,自定义的CLI简介,以及有界限的对话/fanout. 不用于普通tmux配置,主题,非tmux无头CLI使用,或人类团队辩论.

何时用

- Claude/Codex/agy/海关长期经营 CLI 需要后期监督的工作

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Tmux Agent Tools、Fast paths (read this first)、Overview、Required preflight and safe invocation、When to use、Command choice。 其中含规范建议的小节:分步指令。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/multi-agent.md、scripts/agent-tmux、references/core-workflow.md、references/profiles.md、references/cheatsheets.md、references/contracts.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Mechanics library for running AI coding CLIs as managed tmux workers via agent-tmux <cli> <command> (plus tmux-agent-sessions and the other bundled tools). Entry point is the using-tmux-agent-tools router skill — route through it first; read this skill for wrapper mechanics it defers to. Covers start/send-wait/status/result/stop, structured result.json completion, multi-worker watch, profiles for custom CLIs, and bounded dialogue/fanout. Not for general tmux config, theming, non-tmux headless CLI use, or human team debate.

Tmux Agent ToolsFast paths (read this first)OverviewRequired preflight and safe invocationWhen to useCommand choiceWhen not to useThe 6 commands you need mostDispatch 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 cannotbe misordered and it catches "task never reached the CLI" before waiting.

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
tmux-agent-tools
description
Mechanics library for running AI coding CLIs as managed tmux workers via agent-tmux <cli> <command> (plus tmux-agent-sessions and the other bundled tools). Entry point is the using-tmux-agent-tools router skill — route through it first; read this skill for wrapper mechanics it defers to. Covers start/send-wait/status/result/stop, structured result.json completion, multi-worker watch, profiles for custom CLIs, and bounded dialogue/fanout. Not for general tmux config, theming, non-tmux headless CLI use, or human team debate.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 7
  • references/multi-agent.md
  • scripts/agent-tmux
  • references/core-workflow.md
  • references/profiles.md
  • references/cheatsheets.md
  • references/contracts.md
  • references/security.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「tmux-agent-tools」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-eb9c3af1d2539f96-Tmux-%E4%BB%A3%E7%90%86%E5%B7%A5%E5%85%B7.html
请存为 .cursor/skills/tmux-agent-tools/SKILL.md 或 .claude/skills/tmux-agent-tools/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/ohyeh/tmux-agent-tools 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/ohyeh/tmux-agent-tools' --list

npx skills add 'https://github.com/ohyeh/tmux-agent-tools' --skill 'tmux-agent-tools'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: tmux-agent-tools description: Mechanics library for running AI coding CLIs as managed tmux workers via agent-tmux (plus tmux-agent-sessions and the other bundled tools). Entry point is the using-tmux-agent-tools router skill — route through it first; read this skill for wrapper mechanics it defers to. Covers start/send-wait/status/result/stop, structured result.json completion, multi-worker watch, profiles for custom CLIs, and bounded dialogue/fanout. Not for general tmux config, theming, non-tmux headless CLI use, or human team debate. --- # Tmux Agent Tools ## Fast paths (read this first) Non-negotiable rules: 1. **Engine-only — never type raw `tmux` at a worker.** Drive every worker through `agent-tmux ` 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. 2. **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. 3. **Every blocking wait takes a timeout — never hand-roll `sleep`/polling loops.** Multiple workers: one bounded `watch --any|--all|--count --timeout --json …`. Mixed-engine fleets: trust `reason:result_updated` or resolve with `tmux-agent-sessions`. 4. **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: `/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 assign ` call — the stepwise sequence (start → result init → send → confirm-processing → blocking supervise) IS the supervision, so the proxy hosts it and nothing else (the OLD per-worker *polling* proxy stays retired, 2026-08-08). The host is ONE supervision proxy — a `general-purpose` subagent on `sonnet` low whose brief runs that single `assign` call and reports its exit code (see `model-dispatch.md` §4, 2026-08-17/18 rulings). Parent foreground `assign` is banned in ALL forms, `--detach` included, and is denied at the tool call by the `tmux-assign-host-gate` hook; parent `run_in_background` is REQUIRED, not a last-resort fallback, whenever the proxy reports anything non-terminal — measured 2026-08-30, the harness reaps a proxy's foreground call at ~600s and a subagent has no `TaskOutput`, so a reaped proxy can only report in-flight and the parent must own the wait itself (a task orphaned by a terminated subagent notifies nobody; incident c48c0d3a lost 2h40m that way). Log the reason in the run dir, and never pipe the listener — a trailing `| tail` reports `tail`'s status, so the wrapper's `exit 2` reads as success. The parent MUST NOT additionally poll `status`/`capture`/`probe` unless `assign` reports a failed step or the user asks; harvest with bounded `result wait-required --wait ` calls. A `pending` result is a TERMINATING PROCEDURE, not a verdict: keep waiting within the bound → bound expires still pending, re-prompt the worker ONCE with the literal path from `result --path ` and wait one more bounded round → only then may a pane capture stand in, labelled UNCONFIRMED and never shipped as a verified answer. Heed `assign`'s `result-path delivery UNCONFIRMED` warning — a worker that never learned its path can never write result.json, so that `pending` is permanent. Teardown order: stand the proxy DOWN BEFORE stopping the worker it supervises, or the proxy is stranded on a signal that can no longer arrive. Never brief a proxy to return the worker's output verbatim — it is forbidden to read that output, so the brief is unsatisfiable; have the WORKER write to a declared artifact path and read that file yourself. - **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`. ## Overview `agent-tmux ` runs any AI coding CLI as a managed tmux worker; claude/codex/agy are built-in presets, other CLIs use an optional profile. There are no per-CLI binaries — always spell `agent-tmux `. ## Required preflight and safe invocation Before the first worker command: 1. Resolve the wrapper bundle instead of assuming PATH. Probe, in order, `/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. 2. Run the resolved `agent-tmux setup` and stop if preflight fails. 3. 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. 4. Pass task-specific credentials only through `--secret KEY=URI`. Never embed credential values in task text or a constructed shell command. ## 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. ## 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 ` (+ 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 ''` | | 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 --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 `; a misplaced flag exits 2. Full capability table (every subcommand + when to use it): `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. ## The 6 commands you need most ```bash # 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 ``` Full walkthrough: `references/core-workflow.md`. ## result.json completion contract Agents write `$TMUX_AGENT_DIR//result.json` with `schema_version: 1`, canonical `status` (`success|failed|blocked|needs-input`), `summary`, `artifacts`, and `errors` (optional `verdict`/`decision`). The first prompt send of a session injects the literal result path (every family by default); 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`. `--fields` names keys in THAT contract, never a prompt placeholder: harvesting with `artifact_path` (which no worker writes) left two finished workers unharvested for ~24 minutes on 2026-09-08. Ask for `status,summary`, read `.body`, and request a produced file as `.body.artifacts`. A terminal result missing a requested field now exits `3` (`event:"contract-mismatch"`, worker `body` attached) instead of waiting — fix the field list, do not re-dispatch. A CLI that cannot launch exits `4` at `assign` step 0 with `blocked_reason` (`keychain_locked`, `login_required`, `quota_exhausted`, `cli_not_found`) and starts nothing: report the blocker, do not wait. For a TUI that submits on every newline, dispatch with `assign --prompt-delivery file-ref` (profile `prompt_delivery`; `agy` ships it) — agy received one pasted prompt as 12 separate inputs, `GOAL` and `CONTEXT` never arriving, and still reported `assigned:true`. ```bash agent-tmux codex result --json --wait 30 worker agent-tmux codex supervise --result-required --silent-while-unchanged --json worker ``` If `.present:false`, the agent never wrote the file — re-prompt with the literal path from `result --path `. Full schema, worked example, `status --json` fields, approval-gate exit codes, concurrency model: `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`. ## 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). ## Bundled schemas `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.

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…