tmux 自动化操控:用 scripts/auto-tmux.sh 安全读取、发送、巡检、救援、录制 session|window|pane,用 swarm-state.sh 管理蜂群任务/锁/状态,并基于 oh-my-tmux 组织多 AI 终端协作。触发:capture-pane、send-keys、批量巡检、蜂群
复制下面这句话,粘贴给 Claude Code、Codex、Cursor 等 AI 编程工具,它会读取安装说明并在你确认后完成安装。
请阅读 https://ai.atlankj.com/install/asset/gh-auto-tmux-287265f24962 ,按照其中的说明把「auto-tmux」安装到你(当前 AI 工具)中。执行前先告诉我将运行的命令和写入的位置,等我确认。
查看 AI 将读取的安装说明正在读取 GitHub 原文…
内容来自 GitHub 原始文件,由原作者维护。在 GitHub 查看
让 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。
触发条件(满足其一即可):
y、Enter、Ctrl+C、广播同一窗口)。tools/external/.tmux 配置并避免修改主配置。~/.tmux.conf / .tmux.conf(遵循 oh-my-tmux:修改请放到 .tmux.conf.local)。kill-server、rm -rf 等必须先 capture-pane 确认目标上下文。脚本帮助与语法检查
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,前缀后按 ?)
[按] <prefix> ?
枚举拓扑(脚本优先)
skills/auto-tmux/scripts/auto-tmux.sh topology
skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
枚举拓扑(原生命令兜底)
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 最近输出
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 行
tmux capture-pane -t <session>:<window>.<pane> -p -S -120
向指定 pane 发送命令或确认键
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
原生发送确认键
tmux send-keys -t <session>:<window>.<pane> "y" Enter
安全中断挂住任务
tmux send-keys -t <session>:<window>.<pane> C-c
开启/关闭窗口内广播(同步全部 pane)
tmux set-window-option synchronize-panes on
tmux set-window-option synchronize-panes off
一次扫描全部窗口并截取最近输出(蜂群巡检)
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
skills/auto-tmux/scripts/auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run
生成证据快照/交接报告
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
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 工人)
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)
# 只在用户显式输入 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 配置(仓库内版本)
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 输出到文件
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 出现完成信号
skills/auto-tmux/scripts/auto-tmux.sh wait -t <session>:<window>.<pane> --pattern "Tests passed|BUILD SUCCESS" --timeout 300
初始化蜂群状态、任务和锁
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
脚本端到端自测
source skills/auto-tmux/scripts/completion.bash
skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
skills/auto-tmux/scripts/validate-auto-tmux.sh
渲染 commander / worker / reviewer 提示词
skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "拆分并推进任务"
skills/auto-tmux/scripts/render-swarm-prompt.sh worker --target <session>:<window>.<pane> --task "只处理指定子任务"
skills/auto-tmux/scripts/render-swarm-prompt.sh reviewer --session ai-hub --task "审查 worker 产出"
skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<window>.<pane> --task "只处理指定子任务" --send --dry-run
scripts/auto-tmux.sh;直接使用 tmux 原生命令时必须保留同等安全约束。capture-pane 复核目标上下文;按键操作必须带 <session>:<window>.<pane> 绝对定位。~/.tmux.conf.local。list-windows/list-panes 建立白名单,避免误控用户窗口。codex,禁止用无头 codex exec 替代。scripts/remote-readonly.sh 采集证据;远程控制必须另行确认,不从只读脚本升级。(y/n)、password),只对匹配目标发送。Escape;先 C-c 中断、C-u 清行,再用 send-keys -l 逐字发送完整命令。scripts/safety-check.sh,批量发送先 --dry-run。inspect/capture worker pane,并把需求、上下文、边界、验收和验证命令整理成高质量提示词。/exit 回到 shell 再执行命令。pipe-pane 记录审计;广播完成后立即 synchronize-panes off。swarm-state.sh lock-acquire 声明锁。broadcast --dry-run 预览目标,再决定是否真实发送。Ctrl+C/Ctrl+D。Proceed? (y/n),先用 topology 找到真实 target。skills/auto-tmux/scripts/auto-tmux.sh topology 找到目标 <session>:<window>.<pane>。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-hub 的多个窗口。skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80 --save-dir /tmp/auto-tmux-scan 收集状态。"(y/n)" 的 pane 运行 rescue --dry-run,确认后再真实发送。Traceback 或 ERROR 的 pane,先 capture-pane 记录再人工介入。skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex" 创建 session。skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub 确认 worker 窗口存在。C-a,状态栏正常;4 个窗口可互相捕获/发送按键。C-b 无反应?
C-a,C-b 仅作备用;确保无其他程序占用 C-a。set-window-option synchronize-panes on,使用完立即关闭。tmux display-message -pt <target> '#{pane_current_path}',必要时先 send-keys 'cd /path' Enter。no such session/window/pane → 检查目标名称,先 list-sessions/list-windows 校验再重试。~/.tmux.conf.local 是否改写前缀;可在其中设置 set -g prefix C-b #!important。tmux -f /dev/null -L test 排查;多半是终端宽字符/字体导致。tmux display-message -pt <target> '#{pane_in_mode}' 判断,再用 tmux send-keys -t <target> -X cancel 退出;避免用 Escape(会触发 Meta 前缀,可能吞掉首字符)。references/index.md: 导航与文件速览references/getting_started.md: 术语、oh-my-tmux 最小接入步骤references/api.md: tmux/oh-my-tmux 常用命令、选项与 gpakosz 特色键位references/automation.md: scripts/auto-tmux.sh 子命令、安全模型与 AI 蜂群协作流程references/safety-policy.md: 发送、广播、清理、归档和敏感信息处理的安全策略references/session-safety.md: 本地 session、远程 SSH 和多 Agent 协作的分层安全边界references/jsonl-schema.md: JSONL/manifest 机器可读输出字段约定references/report-pack-review.md: report pack reviewer 最短验收路径references/reading-paths.md: commander、worker、reviewer、operator 的角色化阅读路线references/incident-runbook.md: 误发送、误广播、远程采集失败和敏感信息风险处理流程references/script-cheatsheet.md: 观察、控制、协作、报告、审计和事故处理脚本速查references/swarm-state.md: 蜂群状态、任务、锁和报告协议references/prompt-templates.md: commander/worker/reviewer 提示词模板和下发方式references/codex-pilot-mode.md: 主 Codex 控制一个持久化交互式 worker Codex 的激活提示词、边界和验收协议references/ai-swarm-collaboration.md: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制references/iteration-roadmap.md: 多轮迭代记录、能力层和后续候选方向references/iteration-closeout.md: 50 轮迭代后的能力收尾、验证链路和维护边界references/examples.md: 蜂群协议脚本与长示例references/troubleshooting.md: 典型故障到修复路径scripts/auto-tmux.sh: 安全封装的 tmux 自动化脚本入口scripts/swarm-state.sh: 蜂群任务、锁、状态和报告脚本scripts/swarm-brief.sh: 只读生成 tmux 蜂群交接报告scripts/swarm-watch.sh: 有限轮次巡检 tmux 蜂群输出和状态报告scripts/swarm-archive.sh: 打包 brief、snapshot 和 swarm state 的交接归档scripts/swarm-board.sh: 渲染任务、依赖、锁和状态日志的 Markdown 看板scripts/swarm-deps-graph.sh: 渲染 deps.tsv 的 Mermaid 依赖图scripts/swarm-export.sh: 导出任务、依赖和锁的 JSONL 状态包scripts/swarm-timeline.sh: 渲染 status.log 的 Markdown 时间线scripts/swarm-blockers.sh: 聚合 BLOCKED/FAIL 任务、锁和最近异常状态scripts/swarm-results.sh: 汇总 DONE/FAIL/BLOCKED worker 结果,支持 JSONL 导出scripts/swarm-report-pack.sh: 聚合 board、依赖图、时间线、阻塞清单、分配建议、附件、 和可选 tar.gzskills/auto-tmux/assets/oh-my-tmux、skills/auto-tmux/assets/tmux-src、蜂群实战提示词、Skill Seeker 生成的抓取材料(如需扩展自动化)。发布前自检(配合 auto-skill 校验脚本):
description 已含“capture-pane/send-keys/蜂群”等触发关键词。references/ 并可导航;无文档堆砌。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/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-smoke-test.sh 通过或在无 tmux 环境下明确跳过。skills/auto-tmux/scripts/validate-auto-tmux.sh 和 skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict 通过。manifest.jsonscripts/swarm-assign.sh: 根据 ready tasks 和 worker pane 生成只读分配建议scripts/swarm-health.sh: 汇总 tmux 与 swarm state 的只读健康检查报告包scripts/remote-readonly.sh: 通过 SSH 只读采集远端 tmux 拓扑、pane 输出和 metadata.jsonlscripts/record-summary.sh: 汇总 pane 录制日志并生成复盘摘要scripts/check-jsonl.sh: 轻量检查 JSONL 行和必需字段scripts/review-checklist.sh: 为 report pack 生成 reviewer 审计清单scripts/verify-report-pack.sh: 统一验证 report pack 的 manifest、JSONL 和审计清单scripts/incident-report.sh: 生成误发送、误广播、远程采集和敏感信息风险复盘模板scripts/audit-package.sh: 检查脚本、参考资料、SKILL 入口和 validator 的索引一致性scripts/completion.bash: Bash completion,补全 auto-tmux.sh 与 swarm-state.shscripts/safety-check.sh: 发送/粘贴/分发前检查危险命令、敏感信息和过大 payloadscripts/render-swarm-prompt.sh: commander/worker/reviewer/codex-worker 提示词渲染脚本scripts/swarm-dispatch.sh: 渲染并可选下发 commander/worker/reviewer 提示词scripts/auto-tmux-smoke-test.sh: tmux 自动化脚本端到端自测scripts/validate-auto-tmux.sh: auto-tmux 专属质量门禁assets/oh-my-tmux: gpakosz/oh-my-tmux submodule 的相对软链接入口assets/tmux-src: tmux/tmux submodule 的相对软链接入口