cmux コアコントロール

このスキルを使用して、cmux トポロジー、ターミナル I/O(他のペインにコマンドを送信し出力を読取)、通知、サイドバーメタデータを制御します。

環境検出

cmux は起動するすべてのターミナルに $CMUX_WORKSPACE_ID と $CMUX_SURFACE_ID を設定します。cmux コマンドを使用する前に確認してください:

if [ -z "$CMUX_WORKSPACE_ID" ]; then
  echo "Not running inside cmux — cmux commands unavailable"
fi

cmux 内で実行されていない場合は、標準ツールにフォールバックしてください(ペイン分割なし、cmux 通知なし)。

コアコンセプト

• Window: macOS cmux のトップレベルウィンドウ。
• Workspace: ウィンドウ内のタブ風グループ(サイドバーエントリ)。
• Pane: ワークスペース内の分割コンテナ。
• Surface: ペイン内のタブ(ターミナルまたはブラウザパネル)。

階層: Window > Workspace > Pane > Surface

デフォルト出力は短い参照を使用します: window:N、workspace:N、pane:N、surface:N。UUID はまだ入力として受け入れられます。UUID 出力が必要な場合のみリクエストしてください: --id-format uuids|both。

クイックスタート

トポロジー

# 常に最初に識別します — 短い参照 (pane:1, surface:N) はセッションスコープです
cmux identify --json                                          # 現在の呼び出し元コンテキスト
cmux list-workspaces                                          # ワークスペース一覧
cmux list-panes                                               # ワークスペース内のペイン一覧
cmux list-pane-surfaces --pane pane:1                          # ペイン内のサーフェス一覧
cmux new-workspace                                            # ワークスペース作成
cmux new-split right                                           # 現在のサーフェスを右に分割
cmux move-surface --surface surface:7 --pane pane:2            # サーフェスをペイン間で移動
cmux trigger-flash --surface surface:7                         # ビジュアルフラッシュ

ターミナル I/O (他のペインにコマンドを送信、出力を読取)

cmux send --surface surface:N "echo hello\n"                   # テキスト + Enter を送信 (\n = Enter)
cmux send --surface surface:N "npm start\n"                    # 別のペインでコマンドを実行
cmux send-key --surface surface:N enter                        # Enter キーを個別に送信
cmux send-key --surface surface:N ctrl+c                       # Ctrl+C を送信(プロセス停止)
cmux read-screen --surface surface:N                           # 表示されているターミナルテキストを読取
cmux read-screen --surface surface:N --scrollback              # スクロールバック履歴を含める
cmux read-screen --surface surface:N --scrollback --lines 200  # 最後の 200 行のみ

通知とサイドバー

cmux notify --title "Build Complete" --body "All tests passed"
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-progress 0.75 --label "Running tests"
cmux log --level info --source claude-code "Starting build..."

ターミナル I/O パターン

コアワークフロー: ペインを分割、コマンドを送信、完了を検出、出力を読取。

コマンドを送信する前に、完了をどのように判定するかを決めてください。 Claude Code は 2 秒を超えるフォアグラウンド sleep をブロックします — 実行内容に基づいて完了戦略を選択してください:

コマンド種別	例	戦略
バッチ(開始→終了)	npm run build, pytest	wait-for シグナル
長時間実行サービス	npm run dev, docker compose up	「ready」テキストの内容ポーリング
インタラクティブプログラム	claude, node, psql	プロンプトマーカーの内容ポーリング
即座	echo, ls, cat	即座の read-screen

バッチコマンド → wait-for

cmux wait-for -S <signal> をコマンドにチェーンします。run_in_background: true で wait を実行します。

cmux new-split right  # → surface:9
cmux send --surface surface:9 "npm run build && cmux wait-for -S build-done\n"

# run_in_background: true — 完了時に通知
cmux wait-for build-done --timeout 120 && cmux read-screen --surface surface:9 --scrollback --lines 50

サービス / インタラクティブプログラム → 内容ポーリング

期待されるテキストについて read-screen をポーリングします。バンドルされたヘルパーを run_in_background: true で使用します:

# run_in_background: true
$SKILL_DIR/scripts/poll-screen.sh surface:9 "ready|listening|Claude Code" --timeout 60

一般的なマッチパターン:

• サーバー準備完了: ready|listening on|started
• Claude Code 準備完了: Claude Code|tips:|❯
• タスク完了: ╭─|❯|\\$\\s*$
• ビルド結果: ✓|passed|error|failed

ハイブリッド例

サーバー起動 → ready 待機 → バッチ処理:

cmux send --surface surface:9 "npm run dev\n"
# run_in_background: true — サーバー ready のポーリング
$SKILL_DIR/scripts/poll-screen.sh surface:9 "ready on" --timeout 30

# (バックグラウンド通知が ready を確認した後)
cmux send --surface surface:9 "curl localhost:3000/health && cmux wait-for -S health-ok\n"
cmux wait-for health-ok --timeout 10

詳細なパターン(サーバー監視、E2E テスト、ビルドパイプライン、リモート Claude Code)については、ターミナル I/O リファレンスを参照してください。

サイドバーメタデータ

# ステータスピル: set-status <key> <value> [--icon name] [--color #hex]
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-status build "Failed" --icon xmark --color "#ff3b30"
cmux clear-status build

# プログレスバー(0.0 から 1.0、オプションの --label)
cmux set-progress 0.75 --label "Running tests"
cmux clear-progress

# ログメッセージ(レベル付き、オプションの --source)
cmux log --level info --source claude-code "Starting build..."
cmux log --level success "Build complete"
cmux log --level warning "3 deprecation warnings"
cmux log --level error "Test suite failed"

共存

• cmux 内: ペインには cmux new-split を、ターミナル I/O には cmux send/cmux read-screen を、通知には cmux notify を使用します。
• cmux 外: これらの機能は利用できません。標準ターミナルワークフローを使用してください。
• cmux でのブラウザオートメーション: 埋め込み webview オートメーションには cmux-browser スキルを使用します。
• cmux でのマークダウン表示: cmux markdown open <path> を直接使用してライブリロードパネルを開きます。
• cmux claude-teams との使用: Teams は独自の tmux-shim レイヤーをトポロジーに使用します — 直接 cmux トポロジーコマンドと Teams オーケストレーションを混在させないでください。

注意点

• cmux コマンドは cmux 外ではサイレント失敗します — cmux コマンドを使用する前に常に $CMUX_WORKSPACE_ID をチェックしてください。
• 短い参照(surface:7)はセッションスコープであり、セッション間で変更される可能性があります — オートメーションの開始時に常に cmux identify --json で現在のトポロジーを検出してください。
• send には \n で Enter が含まれます — cmux send "command\n" はコマンドを送信し、1 呼び出しで Enter を押します。明示的なタイミング制御が必要な場合を除き、別の send-key enter は不要です。
• send-keys は存在しません — コマンドは send(テキスト)と send-key(キーイベント)です。これは tmux の send-keys とは異なります。
• press は存在しません — Ctrl+C を送信するには、cmux send-key --surface surface:N ctrl+c を使用してください。
• read-screen は現在の画面状態を返します — コマンドがまだ実行中の場合、出力は不完全な可能性があります。履歴には --scrollback --lines N を使用するか、完了戦略を使用してください(上記のターミナル I/O パターンを参照)。
• Claude Code では、2 秒を超える sleep はフォアグラウンドでブロックされます — バッチコマンドには wait-for を、インタラクティブプログラムには内容ポーリングを使用します。どちらも run_in_background: true が必要です。sleep N && read-screen を避けてください — 早すぎるか遅すぎるタイミングで読取されます。
• コマンドを送信する前に常に完了検出を計画してください — 事前に決定してください: これはバッチ(wait-for)か、サービス/インタラクティブ(内容ポーリング)か、即座(即座の読取)か? 計画なしで送信するとブラインドリトライにつながります。
• set-status --color には 16 進数値("#34c759")が必要です — green のような名前付き色はサポートされていません。
• set-status には最初の引数としてキー(例: build)が必要です — キーにより、ワークスペースごとに複数の独立したステータスピルが可能になります。
• cmux claude-teams がアクティブな場合、tmux-compat シムを通じてトポロジーを管理します。直接トポロジーコマンド(new-split, move-surface)は Teams オーケストレーションと競合する可能性があります。
• cmux ウィンドウがフォーカスされ、ワークスペースがアクティブな場合、デスクトップアラートは抑制されます — 常に表示されるステータス更新には cmux log を使用してください。

ディープダイブリファレンス

リファレンス	使用場面
Terminal I/O	コマンド送信、出力読取、サーバー監視、E2E テスト、ビルドパイプライン
Sync and Automation	wait-for 同期、バッファ、cmux.json カスタムワークスペースコマンド
Handles and Identify	ハンドル構文、自己識別、呼び出し元ターゲティング
Windows and Workspaces	ウィンドウ/ワークスペースライフサイクルと順序変更/移動
Panes and Surfaces	分割、サーフェス、移動/並べ替え、フォーカスルーティング
Trigger Flash and Health	ビジュアルフラッシュ確認とサーフェスヘルスチェック
Notifications	通知 CLI、サイドバーメタデータ API、フックパターン