cmux-cli

cmux CLI

タスクを cmux コマンドラインで処理するのが最適な場合や、ユーザーが cmux CLI の使い方、調査方法、スクリプト作成方法、ドキュメント作成方法を尋ねた場合に、このスキルを使用します。正確な構文を確認するには、まず実行中の CLI ヘルプを参照し、その後、ここに記載された安全ルールを適用してください。

前提条件

通常のユーザーワークフローでは、PATH 上にある cmux バイナリを使用します。

cmux --help
cmux version
cmux ping

cmux のソースチェックアウトからタグ付き Debug ビルドを試用する場合は、/tmp/cmux-cli ではなく、タグに紐づいたヘルパーを使用します。

CMUX_TAG=<tag> scripts/cmux-debug-cli.sh --help
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json

scripts/cmux-debug-cli.sh は /tmp/cmux-debug-<tag>.sock を対象とし、タグ付きアプリバンドルに含まれる対応する CLI を使用して、実行前に環境に残っている cmux ターミナルコンテキストを消去します。

構文の確認

正確なコマンドのヘルプを案内する前に、必ず CLI から現在の構文を確認してください。

cmux --help
cmux help
cmux <command> --help
cmux docs settings
cmux docs shortcuts
cmux docs api
cmux docs browser
cmux docs agents
cmux docs dock

一部のサブコマンドは、詳細なサブコマンドヘルプではなく、トップレベルのヘルプを表示します。その場合は、ローカルでソースを検索してください。

rg -n "Usage: cmux <command>|case \"<command>\"|run.*<Command>" CLI

gh api でソースファイルを取得しないでください。ローカルのチェックアウトまたはアクティブなワークツリーを参照してください。

基本モデル

cmux は Unix ソケット経由でアプリの状態を公開します。

• Window：macOS の cmux トップレベルウィンドウです。
• Workspace：ウィンドウ内にある、サイドバーのタブのようなコンテナーです。
• Pane：ワークスペース内の分割領域です。
• Surface：ペイン内のタブです。ターミナル、ブラウザー、Markdown ビューアー、差分ビューアーなどのパネルを表示できます。
• Panel：より低レベルのコンテンツ実装です。コマンドで --panel が明示的に必要な場合を除き、surface コマンドを優先してください。

ハンドル入力には通常、UUID、window:1、workspace:2、pane:3、surface:4 などの参照、または数値インデックスを使用できます。出力はデフォルトで参照を使用します。

cmux --id-format refs identify
cmux --id-format both list-pane-surfaces --workspace workspace:1
cmux --json --id-format both tree --all

ソケットの指定

cmux 内で実行する場合は、呼び出し元の環境を優先してください。

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

タグ付きアプリまたはデフォルト以外のアプリを対象にする場合は、ソケットを明示的に指定してください。

cmux --socket /tmp/cmux-debug-<tag>.sock identify --json
CMUX_SOCKET_PATH=/tmp/cmux-debug-<tag>.sock cmux ping

ソケット認証では、--password、CMUX_SOCKET_PASSWORD、Settings に保存されたパスワードの順に認証情報が解決されます。cmux capabilities --json またはコマンドのエラーで認証が実際に必要だと判明するまでは、ユーザーにパスワードを尋ねないでください。

グローバルオプション

一般的なグローバルオプション：

cmux --json <command>
cmux --id-format refs <command>
cmux --id-format uuids <command>
cmux --id-format both <command>
cmux --socket <path> <command>
cmux --password <password> <command>

自動化やスクリプトでは --json を使用してください。人向けの簡易的なステータスを出力する場合は、通常の出力を使用してください。

安全な初手のコマンド

自動化セッションを開始するたびに、コンテキストと機能を調べてください。

cmux ping
cmux capabilities --json
cmux identify --json
cmux list-windows --json
cmux list-workspaces --json
cmux tree --all --json

cmux 内では、変更を加えるコマンドの対象を、デフォルトで呼び出し元のワークスペースとサーフェスに限定してください。

cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface "${CMUX_SURFACE_ID:-}" --lines 80

一般的なワークフロー

幅広いコマンド一覧は references/commands.md を参照してください。使用頻度の高いパターン：

# Open without stealing focus when supported.
cmux open . --focus false
cmux open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}" --focus false

# Create helper output in the caller workspace.
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false

# Read and write the caller terminal.
cmux read-screen --surface "${CMUX_SURFACE_ID:-}" --scrollback --lines 200
cmux send --surface "${CMUX_SURFACE_ID:-}" "echo ok\n"
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

# Browser surface automation.
cmux browser open https://example.com --focus false
cmux browser snapshot --surface surface:5 --compact
cmux browser click "button[type=submit]" --snapshot-after

# Settings and docs.
cmux docs settings
cmux settings path
cmux config validate
cmux reload-config

# Sidebar status for task progress.
cmux set-status build running --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"

コマンドの分類

CLI には、次のような大まかなコマンド群があります。

• アプリ／ドキュメント／設定：welcome、docs、settings、config、shortcuts、reload-config、themes。
• オープナーとビューアー：open、markdown、diff、ブラウザーコマンド。
• コンテキストとトポロジー：identify、list-windows、list-workspaces、tree、ワークスペース／ウィンドウ／ペイン／サーフェスのライフサイクルコマンド。
• ターミナル入出力：read-screen、send、send-key、capture-pane、pipe-pane、clear-history、respawn-pane。
• ブラウザー自動化：browser open、goto、snapshot、click、fill、screenshot、get、find、tab、Cookie、ストレージ。
• 通知とサイドバーの状態：notify、通知の一覧表示／読み取り／消去コマンド、right-sidebar、set-status、set-progress、log。
• エージェントのワークフロー：hooks、feed、claude-teams、codex-teams、omo、omx、omc。
• 認証とクラウド：auth、login、logout、vm または cloud。
• 高度なソケット／デバッグ：capabilities、events、rpc、surface-health、debug-terminals、trigger-flash。
• tmux 互換性：capture-pane、resize-pane、wait-for、swap-pane、break-pane、join-pane、find-window、バッファー、フック、メッセージ。

邪魔にならない自動化

ユーザーは別のワークスペース、ウィンドウ、またはアプリを見ている可能性があります。フォーカスの変更は UI のクリックと同様に扱ってください。

ユーザーから明示的に求められない限り、次のコマンドは呼び出さないでください。

• focus-window
• focus-pane
• focus-panel
• select-workspace
• フォーカスまたは選択を行う tab-action アクション
• right-sidebar focus

追加的で、対象範囲を限定できるコマンドを優先してください。

cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false
cmux send --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:7 "npm test\n"

タスク用の補助出力を作成するときは、呼び出し元のワークスペース内にある右側の補助ペインを再利用してください。まず list-panes と list-pane-surfaces を使用し、適切な補助ペインがない場合にのみ新しいペインを作成してください。

設定の境界

cmux が管理する設定は ~/.config/cmux/cmux.json にあります。Ghostty のターミナル動作は ~/.config/ghostty/config にあります。フォント、カーソルスタイル、スクロールバック、テーマ、背景の不透明度、ぼかしなど、Ghostty がすでにサポートしているターミナル動作には Ghostty の設定を優先してください。

cmux.json を編集する前に、次を実行してください。

cmux docs settings
cmux settings path

編集前に既存のファイルをタイムスタンプ付きの .bak コピーにバックアップしてから、次を実行してください。

cmux reload-config

デバッグとタグ付きビルド

cmux アプリ／ランタイムを開発する場合、CLI コマンドを実行する前にタグ付きアプリをビルドしてください。

./scripts/reload.sh --tag <tag>
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces --json

タグ付きの -derivedDataPath を指定せずに、単独の xcodebuild を使用しないでください。タグ付きアプリの実動作テストに /tmp/cmux-cli を使用しないでください。これは直近で再読み込みされたビルドを参照するため、誤ったソケットを対象にする可能性があります。

便利なデバッグファイル：

cat /tmp/cmux-last-cli-path
cat /tmp/cmux-last-debug-log-path
tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"

ルール

• 正確な構文を案内する前に、cmux --help または cmux <command> --help を実行してください。
• スクリプトとエージェントによる自動化には --json を使用してください。
• 変更を伴うコマンドは、可能な場合 --workspace、--surface、--pane、--window で対象範囲を限定してください。
• フォーカス中のウィンドウへのフォールバックより、CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH を優先してください。
• ユーザーが何かにフォーカスするよう求めた場合を除き、コマンドが対応している場合は --focus false または --no-focus を指定してください。
• cmux docs settings または cmux settings path を実行する前に、設定を変更しないでください。編集前に cmux.json をバックアップしてください。
• Ghostty がすでにサポートしているターミナル動作には、Ghostty の設定を優先してください。
• タグ付き Debug ビルドでは、CMUX_TAG=<tag> scripts/cmux-debug-cli.sh ... を使用してください。
• タスクがタグ付きアプリに関するものである場合、デフォルトのソケットに対してコマンドを実行しないでください。
• CLI で直接セットアップできる場合、コマンドを cmux に貼り付けるようユーザーに頼まないでください。

関連スキル

• skills/cmux/SKILL.md では、コアとなるトポロジーとルーティングについて説明しています。
• cmux-workspace スキルでは、現在のワークスペースの指定と補助ペインについて説明しています。
• cmux-browser スキルでは、ブラウザーのサーフェス自動化について説明しています。
• cmux-config スキルでは、安全な設定編集について説明しています。
• cmux-markdown スキルでは、Markdown ビューアーパネルについて説明しています。