auto-tmux

# auto-tmux Skill 让 AI 像熟练运维一样操作 tmux：优先使用 `scripts/auto-tmux.sh` 安全封装读取终端输出、发送按键、批量巡检、协作/救援其他终端；使用 `scripts/swarm-state.sh` 管理蜂群任务、锁、状态和结果；必要时再回退到 tmux 原生命令。默认兼容 `tools/external/.tmux`（gpakosz/oh-my-tmux），并在本技能内通过 `assets/oh-my-tmux` 与 `assets/tmux-src` 暴露上游 submodule。 ## When to Use This Skill 触发条件（满足其一即可）： - 需要远程读取/复制某个 tmux pane 的最新输出（日志、提示、错误）。 - 需要向指定 pane 发送按键/命令（确认 `y`、`Enter`、`Ctrl+C`、广播同一窗口）。 - 需要批量巡检/接管多 AI 终端（蜂群协作、自动救援卡死任务）。 - 用户显式要求进入 Codex Pilot Mode：让当前主 Codex 通过 tmux 控制一个持久化、交互式、对人类可见的 worker Codex pane。 - 需要初始化 AI 多终端工作台、等待输出 pattern、录制 pane 日志或保存巡检证据。 - 需要给 tmux 蜂群建立任务队列、状态日志、文件锁和结果报告。 - 需要快速回忆 oh-my-tmux 快捷键、前缀或同步面板操作。 - 需要在当前仓库复用 `tools/external/.tmux` 配置并避免修改主配置。 - 需要从技能目录内快速查看 oh-my-tmux 配置或 tmux 上游源码入口。 ## Not For / Boundaries - 不用于执行非 tmux 环境（目标不存在时先创建 session/window/pane）。 - 不直接编辑 `~/.tmux.conf` / `.tmux.conf`（遵循 oh-my-tmux：修改请放到 `.tmux.conf.local`）。 - 不盲发破坏性按键：`kill-server`、`rm -rf` 等必须先 capture-pane 确认目标上下文。 - 不把脚本当成权限绕过器；敏感会话、密码输入、生产数据库操作仍需人工确认。 - 如果 tmux 版本 < 2.6，需先升级再使用本技能的命令组合。 ## Quick Reference ### 常用模式（≤20 条，直接复制即用） **脚本帮助与语法检查** ```bash bash -n skills/auto-tmux/scripts/auto-tmux.sh bash -n skills/auto-tmux/scripts/swarm-state.sh bash -n skills/auto-tmux/scripts/swarm-brief.sh bash -n skills/auto-tmux/scripts/swarm-watch.sh bash -n skills/auto-tmux/scripts/swarm-archive.sh bash -n skills/auto-tmux/scripts/swarm-board.sh bash -n skills/auto-tmux/scripts/swarm-deps-graph.sh bash -n skills/auto-tmux/scripts/swarm-export.sh bash -n skills/auto-tmux/scripts/swarm-timeline.sh bash -n skills/auto-tmux/scripts/swarm-blockers.sh bash -n skills/auto-tmux/scripts/swarm-results.sh bash -n skills/auto-tmux/scripts/swarm-report-pack.sh bash -n skills/auto-tmux/scripts/swarm-assign.sh bash -n skills/auto-tmux/scripts/swarm-health.sh bash -n skills/auto-tmux/scripts/remote-readonly.sh bash -n skills/auto-tmux/scripts/record-summary.sh bash -n skills/auto-tmux/scripts/check-jsonl.sh bash -n skills/auto-tmux/scripts/review-checklist.sh bash -n skills/auto-tmux/scripts/verify-report-pack.sh bash -n skills/auto-tmux/scripts/incident-report.sh bash -n skills/auto-tmux/scripts/completion.bash bash -n skills/auto-tmux/scripts/safety-check.sh bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh bash -n skills/auto-tmux/scripts/swarm-dispatch.sh bash -n skills/auto-tmux/scripts/validate-auto-tmux.sh skills/auto-tmux/scripts/auto-tmux.sh help skills/auto-tmux/scripts/swarm-state.sh help ``` **查看快捷键帮助**（oh-my-tmux 双前缀：主 `C-a`，备用 `C-b`，前缀后按 `?`） ```text [按] <prefix> ? ``` **枚举拓扑（脚本优先）** ```bash skills/auto-tmux/scripts/auto-tmux.sh topology skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub ``` **枚举拓扑（原生命令兜底）** ```bash tmux list-sessions tmux list-windows -a -F '#S:#I:#W#F' tmux list-panes -a -F '#S:#I.#P #{pane_current_command} #{pane_title}' ``` **读取指定 pane 最近输出** ```bash skills/auto-tmux/scripts/auto-tmux.sh inspect -t <session>:<window>.<pane> -n 40 skills/auto-tmux/scripts/auto-tmux.sh capture -t <session>:<window>.<pane> -n 120 ``` **原生读取指定 pane 最近 120 行** ```bash tmux capture-pane -t <session>:<window>.<pane> -p -S -120 ``` **向指定 pane 发送命令或确认键** ```bash skills/auto-tmux/scripts/safety-check.sh --text "make test" skills/auto-tmux/scripts/auto-tmux.sh send -t <session>:<window>.<pane> --text "make test" --enter skills/auto-tmux/scripts/safety-check.sh --file /tmp/prompt.md --strict skills/auto-tmux/scripts/auto-tmux.sh paste -t <session>:<window>.<pane> --file /tmp/prompt.md --enter --dry-run skills/auto-tmux/scripts/auto-tmux.sh rescue -t <session>:<window>.<pane> --pattern "(y/n)" --reply y ``` **原生发送确认键** ```bash tmux send-keys -t <session>:<window>.<pane> "y" Enter ``` **安全中断挂住任务** ```bash tmux send-keys -t <session>:<window>.<pane> C-c ``` **开启/关闭窗口内广播（同步全部 pane）** ```bash tmux set-window-option synchronize-panes on tmux set-window-option synchronize-panes off ``` **一次扫描全部窗口并截取最近输出（蜂群巡检）** ```bash skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80 skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback" --save-dir /tmp/auto-tmux-scan ``` **受控广播到指定 session** ```bash skills/auto-tmux/scripts/auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run ``` **生成证据快照/交接报告** ```bash skills/auto-tmux/scripts/auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot -n 120 skills/auto-tmux/scripts/swarm-brief.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-brief skills/auto-tmux/scripts/swarm-watch.sh --session ai-hub --swarm-dir /tmp/ai_swarm --iterations 3 --interval 10 skills/auto-tmux/scripts/swarm-archive.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/ai-hub-handoff.tar.gz skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-board.md skills/auto-tmux/scripts/swarm-deps-graph.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-deps.md skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-export skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md skills/auto-tmux/scripts/swarm-results.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-results.md skills/auto-tmux/scripts/swarm-results.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-results.md --jsonl /tmp/ai-swarm-results.jsonl skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-report-pack skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-report-pack --attach /tmp/auto-tmux-remote skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-report-pack --tar skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-health skills/auto-tmux/scripts/remote-readonly.sh --host user@example.com --session ai-hub --out /tmp/auto-tmux-remote --dry-run ``` **远程救援：发现等待输入即发送 y** ```bash target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)" skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y --dry-run skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y ``` **新建 AI 蜂群工作台（1 指挥 + 3 工人）** ```bash skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex" skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub skills/auto-tmux/scripts/auto-tmux.sh cleanup --session ai-hub --dry-run ``` **Codex Pilot Mode（主 Codex 控制一个持久化交互式 worker Codex）** ```bash # 只在用户显式输入 Codex Pilot Mode 激活提示词后使用；完整提示词见 references/codex-pilot-mode.md。 tmux new-session -d -s codex-pilot -n worker 'codex' bash skills/auto-tmux/scripts/auto-tmux.sh topology --session codex-pilot bash skills/auto-tmux/scripts/auto-tmux.sh capture -t codex-pilot:worker.0 -n 120 bash skills/auto-tmux/scripts/swarm-dispatch.sh \ --role codex-worker \ --target codex-pilot:worker.0 \ --session codex-pilot \ --task "进入持久 worker 待命状态，等待主 Codex 后续分派任务" \ --send \ --dry-run ``` **启用 oh-my-tmux 配置（仓库内版本）** ```bash repo_root="$(git rev-parse --show-toplevel)" ln -sfn "$repo_root/skills/auto-tmux/assets/oh-my-tmux/.tmux.conf" ~/.tmux.conf cp -n "$repo_root/skills/auto-tmux/assets/oh-my-tmux/.tmux.conf.local" ~/.tmux.conf.local ``` **记录 pane 输出到文件** ```bash skills/auto-tmux/scripts/auto-tmux.sh record start -t <session>:<window>.<pane> --dir /tmp/auto-tmux-records skills/auto-tmux/scripts/auto-tmux.sh record stop -t <session>:<window>.<pane> skills/auto-tmux/scripts/record-summary.sh --dir /tmp/auto-tmux-records --out /tmp/auto-tmux-record-summary.md skills/auto-tmux/scripts/check-jsonl.sh /tmp/ai-swarm-results.jsonl --require-key type --require-key id --require-key status skills/auto-tmux/scripts/review-checklist.sh --pack /tmp/ai-swarm-report-pack --out /tmp/ai-swarm-report-pack/review-checklist.md skills/auto-tmux/scripts/review-checklist.sh --pack /tmp/ai-swarm-report-pack --strict skills/auto-tmux/scripts/verify-report-pack.sh --pack /tmp/ai-swarm-report-pack skills/auto-tmux/scripts/incident-report.sh --type mis-send --out /tmp/auto-tmux-incident.md ``` **等待 pane 出现完成信号** ```bash skills/auto-tmux/scripts/auto-tmux.sh wait -t <session>:<window>.<pane> --pattern "Tests passed|BUILD SUCCESS" --timeout 300 ``` **初始化蜂群状态、任务和锁** ```bash skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接" skills/auto-tmux/scripts/swarm-state.sh task-import --file /tmp/tasks.txt --prefix batch --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh task-depend --id task-002 --blocked-by task-001 --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh task-ready --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh task-next --owner <session>:<window>.<pane> skills/auto-tmux/scripts/swarm-state.sh lock-acquire --name README.md --owner <session>:<window>.<pane> skills/auto-tmux/scripts/swarm-state.sh lock-prune --older-than 3600 --dry-run skills/auto-tmux/scripts/swarm-state.sh task-block --id task-001 --owner <session>:<window>.<pane> --reason "等待输入" skills/auto-tmux/scripts/swarm-state.sh task-fail --id task-001 --owner <session>:<window>.<pane> --reason "测试失败" skills/auto-tmux/scripts/swarm-state.sh task-list --status FAIL --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh metrics --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh task-reopen --id task-001 --owner <session>:<window>.<pane> --reason "重新执行" skills/auto-tmux/scripts/swarm-state.sh validate --dir /tmp/ai_swarm skills/auto-tmux/scripts/swarm-state.sh report --dir /tmp/ai_swarm ``` **脚本端到端自测** ```bash source skills/auto-tmux/scripts/completion.bash skills/auto-tmux/scripts/auto-tmux-smoke-test.sh skills/auto-tmux/scripts/validate-auto-tmux.sh ```