tmux

tmux スキル

対話型の作業には、プログラム可能なターミナルマルチプレクサーとして tmux を使用します。標準の tmux を使う Linux と macOS で動作します。プライベートソケットを使用して、カスタム設定は避けてください。

クイックスタート（分離ソケット）

SOCKET_DIR=${TMPDIR:-/tmp}/claude-tmux-sockets  # well-known dir for all agent sockets
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/claude.sock"                # keep agent sessions separate from your personal tmux
SESSION=claude-python                           # slug-like names; avoid spaces
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200  # watch output
tmux -S "$SOCKET" kill-session -t "$SESSION"                   # clean up

セッションを開始したら、必ずユーザーにコピーして貼り付けられるコマンドを示し、セッションの監視方法を伝えてください。

To monitor this session yourself:
  tmux -S "$SOCKET" attach -t claude-lldb

Or to capture the output once:
  tmux -S "$SOCKET" capture-pane -p -J -t claude-lldb:0.0 -S -200

これはセッション開始直後と、ツールのループの最後に、必ずもう一度表示してください。早く伝えるほど、ユーザーに喜ばれます。

ソケットの規約

• エージェントは、必ず tmux ソケットを CLAUDE_TMUX_SOCKET_DIR（デフォルトは ${TMPDIR:-/tmp}/claude-tmux-sockets）の下に配置し、列挙・クリーンアップできるように tmux -S "$SOCKET" を使用してください。最初にディレクトリを作成します：mkdir -p "$CLAUDE_TMUX_SOCKET_DIR"。
• さらに分離する必要がない限り、デフォルトのソケットパスを使用します：SOCKET="$CLAUDE_TMUX_SOCKET_DIR/claude.sock"。

ペインの指定と命名

• ターゲットの形式は {session}:{window}.{pane} です。省略した場合のデフォルトは :0.0 です。名前は短くしてください（例：claude-py、claude-gdb）。
• プライベートソケットパスを使用し続けるため、常に -S "$SOCKET" を使用してください。ユーザー設定が必要な場合は -f /dev/null を外します。それ以外の場合は、-f /dev/null でクリーンな設定になります。
• 確認方法：tmux -S "$SOCKET" list-sessions、tmux -S "$SOCKET" list-panes -a。

セッションの検索

• アクティブなソケット上のセッションをメタデータとともに一覧表示します：./scripts/find-sessions.sh -S "$SOCKET"。絞り込むには -q partial-name を追加します。
• 共有ディレクトリ内のすべてのソケットをスキャンします：./scripts/find-sessions.sh --all（CLAUDE_TMUX_SOCKET_DIR または ${TMPDIR:-/tmp}/claude-tmux-sockets を使用）。

入力の安全な送信

• シェルによる分割を避けるため、リテラル送信を優先します：tmux -L "$SOCKET" send-keys -t target -l -- "$cmd"
• インラインコマンドを組み立てる場合は、展開を避けるためにシングルクォートまたは ANSI C クォートを使用します：tmux ... send-keys -t target -- $'python3 -m http.server 8000'。
• 制御キーを送信する場合：tmux ... send-keys -t target C-c、C-d、C-z、Escape など。

出力の監視

• 折り返しによる表示上の問題を避けるため、結合した行で最近の履歴を取得します：tmux -L "$SOCKET" capture-pane -p -J -t target -S -200。
• 継続的な監視には、ペインの出力を監視しない tmux wait-for ではなく、後述のヘルパースクリプトでポーリングしてください。
• 一時的にアタッチして確認することもできます：tmux -L "$SOCKET" attach -t "$SESSION"。Ctrl+b d でデタッチします。
• ユーザーに手順を伝える際は、操作とともにコピーして貼り付けられる監視コマンドを明示してください。ユーザーがコマンドを覚えていると想定してはいけません。

プロセスの起動

プロセスには、次の特別なルールがあります。

• デバッグを依頼された場合は、デフォルトで lldb を使用します。
• Python の対話型シェルを起動する場合は、必ず PYTHON_BASIC_REPL=1 環境変数を設定してください。基本モード以外のコンソールは send-keys に干渉するため、これは非常に重要です。

同期／プロンプト待ち

対話型ツールとの競合を避けるため、時間を指定してポーリングしてください。例：コードを送信する前に Python のプロンプトを待機します。

./scripts/wait-for-text.sh -t "$SESSION":0.0 -p '^>>>' -T 15 -l 4000

• 長時間実行するコマンドの場合は、続行する前に完了を示すテキスト（"Type quit to exit"、"Program exited" など）をポーリングしてください。

対話型ツールのレシピ

• Python REPL：tmux ... send-keys -- 'python3 -q' Enter。^>>> が表示されるまで待ち、-l でコードを送信します。中断するには C-c を使います。必ず PYTHON_BASIC_REPL を設定してください。
• gdb：tmux ... send-keys -- 'gdb --quiet ./a.out' Enter。ページ送りを無効にするには tmux ... send-keys -- 'set pagination off' Enter を使います。C-c で中断し、bt、info locals などを実行します。終了するには quit を実行してから y を確認します。
• その他の TTY アプリ（ipdb、psql、mysql、node、bash）：同じ手順で、プログラムを起動し、プロンプトをポーリングしてから、リテラルテキストと Enter を送信します。

クリーンアップ

• 作業が完了したらセッションを終了します：tmux -S "$SOCKET" kill-session -t "$SESSION"。
• ソケット上のすべてのセッションを終了します：tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t。
• プライベートソケット上のすべてを削除します：tmux -S "$SOCKET" kill-server。

ヘルパー：wait-for-text.sh

./scripts/wait-for-text.sh は、タイムアウトを指定して、ペイン内を正規表現（または固定文字列）でポーリングします。bash、tmux、grep があれば、Linux/macOS で動作します。

./scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]

• -t/--target ペインのターゲット（必須）
• -p/--pattern 照合する正規表現（必須）。固定文字列の場合は -F を追加します
• -T タイムアウト秒数（整数、デフォルトは 15）
• -i ポーリング間隔（秒、デフォルトは 0.5）
• -l ペインから検索する履歴行数（整数、デフォルトは 1000）
• 最初に一致した場合は 0、タイムアウトした場合は 1 で終了します。失敗した場合は、デバッグに役立つよう、最後に取得したテキストを stderr に出力します。