name: startmux description: "tmux 自动化操控：一键6格Agent工作台 + 读取/广播/救援 session|window|pane，基于 capture-pane/send-keys 让 AI 自控/互控终端。触发：/startmux、蜂群协作、卡死救援、批量巡检。"

startmux — tmux 多Agent自动化工作台

让 AI 像熟练运维一样操作 tmux：一键创建6格Agent布局、读取终端输出、发送按键、批量巡检、协作/救援其他终端。

When to Use This Skill

触发条件（满足其一即可）：

• /startmux — 一键创建6格 Agent 工作台（Claude/Codex/Gemini）。
• 需要远程读取/复制某个 tmux pane 的最新输出（日志、提示、错误）。
• 需要向指定 pane 发送按键/命令（确认 y、Enter、Ctrl+C、广播同一窗口）。
• 需要批量巡检/接管多 AI 终端（蜂群协作、自动救援卡死任务）。
• 需要快速回忆 tmux 快捷键、前缀或同步面板操作。

Not For / Boundaries

• 不用于执行非 tmux 环境（目标不存在时先创建 session/window/pane）。
• 不盲发破坏性按键：kill-server、rm -rf 等必须先 capture-pane 确认目标上下文。
• 如果 tmux 版本 < 2.6，需先升级再使用本技能的命令组合。

Triggers

• /startmux — 默认会话名 agents，当前目录
• /startmux myproject — 自定义会话名
• /startmux myproject /path/to/dir — 自定义会话名 + 项目目录
• 启动tmux工作台 / 开启Agent工作台
• tmux巡检 / tmux救援 / 蜂群协作

6格工作台布局

┌──────────┬──────────┬──────────┐
│ Claude-1 │ Claude-2 │ Claude-3 │
│  主任务   │  代码审查  │  调研     │
├──────────┼──────────┼──────────┤
│  Codex   │  Gemini  │  Shell   │
│  重构     │  探索     │  自由终端  │
└──────────┴──────────┴──────────┘

创建工作台指令

当用户触发 /startmux 时，按以下步骤执行：

Step 1: 环境检查

which tmux && tmux -V

如果未安装：brew install tmux

Step 2: 检查会话

tmux has-session -t "${SESSION_NAME:-agents}" 2>/dev/null && echo "EXISTS" || echo "NOT_EXISTS"

• 已存在：告知用户，提供 tmux attach -t {session_name}
• 不存在：继续 Step 3

Step 3: 创建6格布局（后台，不 attach）

SESSION="${SESSION_NAME:-agents}"
PROJECT="${PROJECT_DIR:-$(pwd)}"

tmux new-session -d -s "$SESSION" -c "$PROJECT" -x 200 -y 50
tmux split-window -h -t "$SESSION" -c "$PROJECT"
tmux split-window -h -t "$SESSION" -c "$PROJECT"
tmux select-layout -t "$SESSION" even-horizontal
tmux split-window -v -t "$SESSION:0.0" -c "$PROJECT"
tmux split-window -v -t "$SESSION:0.2" -c "$PROJECT"
tmux split-window -v -t "$SESSION:0.4" -c "$PROJECT"
tmux select-layout -t "$SESSION" tiled

# 窗格标题
tmux send-keys -t "$SESSION:0.0" "printf '\\033]2;Claude-1 主任务\\033\\\\'" Enter
tmux send-keys -t "$SESSION:0.1" "printf '\\033]2;Codex 重构\\033\\\\'" Enter
tmux send-keys -t "$SESSION:0.2" "printf '\\033]2;Claude-2 审查\\033\\\\'" Enter
tmux send-keys -t "$SESSION:0.3" "printf '\\033]2;Gemini 探索\\033\\\\'" Enter
tmux send-keys -t "$SESSION:0.4" "printf '\\033]2;Claude-3 调研\\033\\\\'" Enter
tmux send-keys -t "$SESSION:0.5" "printf '\\033]2;Shell 自由终端\\033\\\\'" Enter

# 角色提示
tmux send-keys -t "$SESSION:0.0" "clear && echo 'Claude-1 | 主任务窗格 | 输入 claude 启动'" Enter
tmux send-keys -t "$SESSION:0.1" "clear && echo 'Codex   | 重构窗格   | 输入 codex 启动'" Enter
tmux send-keys -t "$SESSION:0.2" "clear && echo 'Claude-2 | 代码审查   | 输入 claude 启动'" Enter
tmux send-keys -t "$SESSION:0.3" "clear && echo 'Gemini  | 探索窗格   | 输入 gemini 启动'" Enter
tmux send-keys -t "$SESSION:0.4" "clear && echo 'Claude-3 | 调研窗格   | 输入 claude 启动'" Enter
tmux send-keys -t "$SESSION:0.5" "clear && echo 'Shell   | 自由终端   | git / npm / 任意命令'" Enter

tmux select-pane -t "$SESSION:0.0"
tmux set-option -t "$SESSION" mouse on
tmux set-option -t "$SESSION" pane-border-status top
tmux set-option -t "$SESSION" pane-border-format " #{pane_index}: #{pane_title} "

重要：在 Claude Code 中不要 exec tmux attach（会接管终端）。创建后告知用户在另一个终端运行 tmux a -t {session_name}。

Quick Reference

常用模式（直接复制即用）

枚举拓扑（session/window/pane）

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 最近 120 行

tmux capture-pane -t <session>:<window>.<pane> -p -S -120

向指定 pane 发送确认键

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

一次扫描全部窗口并截取最近输出（蜂群巡检）

for w in $(tmux list-windows -a -F '#S:#I'); do
  tmux capture-pane -t "$w" -p -S -80 | sed "s/^/[$w] /";
done

远程救援：发现等待输入即发送 y

target="agents:0.1"
tmux capture-pane -t "$target" -p -S -50 | grep -qi "(y/n)" && \
  tmux send-keys -t "$target" "y" Enter

记录 pane 输出到文件

tmux pipe-pane -t <session>:<window>.<pane> -o 'cat >> /tmp/tmux-<session>-<window>-<pane>.log'

查看指定 pane 当前工作目录

tmux display-message -pt <target> '#{pane_current_path}'

Rules & Constraints

• MUST：在发送按键前用 capture-pane 复核目标上下文；按键操作必须带 <session>:<window>.<pane> 绝对定位。
• MUST：批量操作前先 list-windows/list-panes 建立白名单，避免误控用户窗口。
• SHOULD：救援/确认前先 grep 关键词（如 (y/n)、password），只对匹配目标发送。
• SHOULD：长任务开启 pipe-pane 记录审计；广播完成后立即 synchronize-panes off。
• NEVER：在未知 pane 发送破坏性命令；NEVER 在 root 会话不经确认发送 Ctrl+C/Ctrl+D。

Examples

Example 1：一键启动工作台

• 输入：/startmux
• 步骤：检查 tmux → 检查会话 → 创建6格布局 → 告知用户接入命令
• 验收：tmux ls 显示 agents 会话，6个 pane 各有角色提示。

Example 2：自动给卡住的安装脚本回车确认

• 输入：安装脚本停在 Proceed? (y/n)，位置在 agents:0.1。
• 步骤：
  1. tmux capture-pane -t agents:0.1 -p -S -50 | grep -qi "(y/n)" 确认等待输入。
  2. tmux send-keys -t agents:0.1 "y" Enter 发送确认。
• 验收：脚本继续运行，无额外多余输入。

Example 3：蜂群巡检 + 自动救援

• 输入：6个 Agent 终端分布在 session agents 的多个窗格。
• 步骤：
  1. 运行巡检循环收集最近 80 行并观察状态。
  2. 对匹配 "(y/n)" 的 pane 触发远程救援片段自动发 y。
  3. 对输出包含 Traceback 或 ERROR 的 pane，先 capture-pane 记录再人工介入。
• 验收：等待确认的终端恢复，未误伤正常任务；巡检日志保存在本地。

Example 4：从主窗格控制其他窗格

• 输入：在 Claude-1 主窗格中，需要让 Codex 窗格执行重构任务。
• 步骤：
  1. tmux capture-pane -t agents:0.1 -p -S -5 确认 Codex 窗格空闲。
  2. tmux send-keys -t agents:0.1 "codex 'refactor src/auth module'" Enter 发送任务。
  3. 定期 tmux capture-pane -t agents:0.1 -p -S -20 查看进度。
• 验收：Codex 窗格开始执行，主窗格可实时监控输出。

Hotkeys

| 快捷键 | 作用 | |--------|------| | Ctrl+B 方向键 | 切换窗格 | | Ctrl+B z | 当前窗格全屏/还原 | | Ctrl+B d | 脱离会话（后台运行） | | tmux a | 重新接入会话 | | 鼠标点击 | 直接切换窗格 | | Ctrl+B x | 关闭当前窗格 | | Ctrl+B & | 关闭当前窗口 |

Common Operations

关闭工作台

tmux kill-session -t agents

列出所有会话

tmux ls

FAQ

• Q: 为什么不自动启动 Agent？
  • A: 避免浪费 token。你可能只需要部分窗格，手动输入 claude/codex/gemini 启动。
• Q: 如何只广播当前窗口而不影响其他窗口？
  • A: 只对当前窗口执行 set-window-option synchronize-panes on，使用完立即关闭。
• Q: 远程发送命令前如何确认当前工作目录？
  • A: tmux display-message -pt <target> '#{pane_current_path}'。
• Q: capture-pane 输出为空？
  • A: 目标 pane 可能在 copy-mode，先 tmux send-keys -t <target> Escape 退出再重试。

Troubleshooting

• no such session/window/pane → 先 tmux list-sessions / list-windows 校验目标名称。
• 发送命令没效果 → 目标 pane 可能在 copy-mode，先发 Escape 退出。
• 布局错乱 → tmux select-layout -t agents tiled 重新均匀分布。

Anti-Patterns

| 避免 | 原因 | 替代 | |------|------|------| | 自动启动所有 Agent | 浪费 token | 只显示提示，手动启动 | | 在 Claude Code 内 exec attach | 接管终端导致断开 | 后台创建，提示用户另开终端接入 | | 不经 capture-pane 就 send-keys | 可能误操作 | 先读后发，确认上下文 | | 广播后忘记关闭 | 后续命令全部同步 | 用完立即 synchronize-panes off | | 硬编码项目路径 | 不可移植 | 使用参数或 $(pwd) |

References

• references/index.md: 导航与文件速览
• references/getting_started.md: 术语与最小接入步骤
• references/api.md: tmux 常用命令与选项
• references/examples.md: 蜂群协议脚本与长示例
• references/troubleshooting.md: 典型故障到修复路径