tmux

tmux

使用 tmux CLI 以及随附的 read-tmux 和 send-tmux 辅助脚本与 tmux 会话交互。脚本位于 {baseDir}/scripts/ — 调用时请将其替换为此技能的基础目录。

先解析 pane_id

对面板进行任何操作前，先解析其 pane_id。这个稳定且明确的标识不受窗口或会话重命名影响；而且，由于重新创建的面板会获得新的 pane_id，使用它可自动将重新创建的面板视为新会话。

# From a user-supplied index (e.g. "pane 1" in the current window)
PANE_ID=$(tmux display-message -t :.1 -p '#{pane_id}')   # → %42

# From a full target
PANE_ID=$(tmux display-message -t 0:2.1 -p '#{pane_id}')

# pane_id works as -t for all pane-level commands
tmux send-keys -t %42 "echo hello" Enter
tmux capture-pane -t %42 -p
tmux select-pane -t %42 -T "my title"
tmux kill-pane -t %42

根据非正式描述查找面板

用户可能会说“另一个面板”“运行 vim 的面板”或“右边的 shell”。请先自行解析，再决定是否询问：

# All panes in current window, excluding your own
tmux list-panes -F '#{pane_id} #{pane_current_command}' | grep -v "^$TMUX_PANE "

# "The other pane" — works when there are exactly 2 panes
PANE_ID=$(tmux list-panes -F '#{pane_id}' | grep -v "^$TMUX_PANE$")

# "The pane running vim"
PANE_ID=$(tmux list-panes -F '#{pane_id} #{pane_current_command}' | grep vim | awk '{print $1}')

$TMUX_PANE 由 tmux 自动设置 — 它是你自己的面板 ID。

如果描述仍有歧义，请显示带编号的覆盖层：

tmux display-panes -d 5000   # numbered overlays appear for 5 seconds
# ask the user which number, then resolve
PANE_ID=$(tmux display-message -t :.N -p '#{pane_id}')

---

读取输出

使用 read-tmux，不要使用原始的 tmux capture-pane。该脚本会跟踪调用之间的位置，让你只收到新输出，并单独处理 TUI 应用和 shell 面板。

{baseDir}/scripts/read-tmux %42          # shell panes — delta since last read
{baseDir}/scripts/read-tmux --tui %42    # TUI apps (vim, htop, etc.) — diff of changed screen regions
{baseDir}/scripts/read-tmux --full %42   # TUI — always show full screen, no diff

增量模式（默认）：

• 首次调用：捕获截至光标位置的完整回滚内容，并保存位置
• 后续调用：仅获取上次读取后新增的行
• 没有新输出：打印 (no new output)

TUI 模式（--tui）：

• 首次调用：捕获完整的可见屏幕，并保存快照
• 后续调用：如果更改的行数不超过 50%，则输出统一差异；否则输出完整屏幕
• 没有更改：打印 (no changes on screen)

输出上限为前 2000 + 后 2000 字节。状态保存在 /tmp/tmux-skill/<pane_id>/ 中。

---

发送按键

使用 send-tmux — 它会装饰面板，并将所有参数转发给 tmux send-keys。

{baseDir}/scripts/send-tmux %42 "npm test" Enter   # run a command
{baseDir}/scripts/send-tmux %42 C-c                # interrupt
{baseDir}/scripts/send-tmux %42 C-d                # EOF / exit shell
{baseDir}/scripts/send-tmux %42 q                  # quit a pager

---

面板装饰

首次使用时，read-tmux 和 send-tmux 都会自动装饰面板 — 顶部会出现黄色的“● Operated by Claude”栏。无需手动设置。

完成后解除装饰：

tmux set-option -p -t %42 -u pane-border-status 2>/dev/null || true
tmux set-option -p -t %42 -u pane-border-format 2>/dev/null || true

---

会话

tmux list-sessions
tmux list-sessions -F '#{session_name} (#{session_windows} windows)'
tmux new-session -d -s <name> [-c <start-dir>]
tmux rename-session -t <old> <new>
tmux kill-session -t <name>
tmux has-session -t <name> 2>/dev/null && echo exists

窗口

tmux list-windows -t <session>
tmux list-windows -t <session> -F '#{window_index}: #{window_name}'
tmux new-window -t <session> -n <name> [-c <dir>]
tmux rename-window -t <session>:<index> <new-name>
tmux move-window -s <session>:<index> -t <dst-session>:<new-index>
tmux swap-window -s <session>:<a> -t <session>:<b>
tmux kill-window -t <session>:<index>

面板

# List
tmux list-panes -t <session>:<window> -F '#{pane_index} #{pane_id} #{pane_current_command}'
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_id} #{pane_current_command}'

# Create — split relative to your own pane so it opens in the right window
PANE_ID=$(tmux split-window -h -t "$TMUX_PANE" -P -F '#{pane_id}')   # side by side
PANE_ID=$(tmux split-window -v -t "$TMUX_PANE" -P -F '#{pane_id}')   # top/bottom

tmux select-pane -t %42 -T <title>
tmux move-pane -s %42 -t <dst-session>:<dst-window>
tmux break-pane -t %42 -n <new-window-name>
tmux join-pane -s <src-window> -t <dst-window>
tmux swap-pane -s %42 -t %99
tmux kill-pane -t %42

查询状态

tmux display-message -t %42 -p '#{pane_id}'
tmux display-message -t %42 -p '#{pane_current_command}'
tmux display-message -t %42 -p '#{pane_current_path}'
tmux display-message -t %42 -p '#{pane_pid}'

常用格式变量：#{pane_id}、#{pane_index}、#{pane_current_command}、#{pane_current_path}、#{pane_pid}、#{session_name}、#{window_index}、#{window_name}

---

常用模式

等待命令完成

{baseDir}/scripts/send-tmux %42 "make build && echo __DONE__" Enter
while ! {baseDir}/scripts/read-tmux %42 | grep -q "__DONE__"; do sleep 0.5; done

为任务打开新面板

WINDOW=$(tmux new-window -t myproject -n build -P -F '#{window_index}')
PANE_ID=$(tmux display-message -t "myproject:${WINDOW}.0" -p '#{pane_id}')
{baseDir}/scripts/send-tmux "$PANE_ID" "make build" Enter

中断并重新运行

{baseDir}/scripts/send-tmux %42 C-c
sleep 0.2
{baseDir}/scripts/send-tmux %42 "make build" Enter