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 を実行しているペイン」「右側のシェル」のように説明する場合があります。尋ねる前に、自分で特定してください。

# 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}')

---

出力の読み取り

生の tmux capture-pane ではなく、read-tmux を使ってください。このスクリプトは呼び出し間の位置を追跡するため、新しい出力だけを受け取れます。また、TUI アプリとシェルのペインを個別に処理します。

{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

デルタモード（デフォルト）：

• 初回：カーソルまでのスクロールバック全体を取得し、位置を保存します
• 2 回目以降：前回の読み取り以降の新しい行だけを取得します
• 新しい出力がない場合：(no new output) と表示します

TUI モード（--tui）：

• 初回：表示中の画面全体を取得し、スナップショットを保存します
• 2 回目以降：変更された行が 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