cmux

cmux の制御

macOS 14.0+。CLI を優先してください。cmux が PATH にない場合は、/Applications/cmux.app/Contents/Resources/bin/cmux を使用してください。

ターゲットの指定と安全性

ウィンドウ → ワークスペース → ペイン → サーフェス： macOS ウィンドウ → サイドバーのプロジェクト／ブランチタブ → 分割領域 → ターミナル、ブラウザー、または Markdown タブ。

• 呼び出し元の CMUX_WORKSPACE_ID を基準にしてください。 視覚的にフォーカスされているワークスペースがターゲットだと決めつけないでください。cmux の外では、操作前に対象のワークスペースを特定してください。
• 接頭辞付きの参照または UUID を使用してください。 workspace:2、pane:1、surface:7 のように指定します。数字のみの場合は ID ではなくインデックスです。出力はデフォルトで参照を使用します。--id-format uuids|both を指定すると UUID が含まれます。
• ターゲットを更新してください。 サーフェス参照はグローバルであり、ワークスペース内に限定されません。再利用する前にリストし直してください。状態が古い可能性がある場合は、入力を送信する前に cmux surface-health を確認してください。
• フォーカスを維持してください。 サポートされている場合は、--focus false を指定してください。select-workspace、focus-pane、focus-panel、focus-surface を使うのは、ユーザーから明示的に要求された場合のみです。
• 所有権を尊重してください。 所有していないサーフェスには入力を送信しないでください。ユーザーがワークスペースをまたぐルーティングを明示的に要求した場合を除き、呼び出し元のワークスペース内にとどめてください。
• ヘルパーペインは1つ再利用してください。 既存の、呼び出し元が使用していないヘルパーペインを使うか、右側に作成してください。new-pane --type … --focus false を使って、目的のレイアウトを直接作成してください。
• エラーを表示したままにしてください。 2>/dev/null を追加しないでください。stderr と終了ステータスから、無効な参照やフラグを確認できます。

確認、読み取り、送信

接続を確認し、呼び出し元を特定して、対象ペインをサーフェスに解決してください。例の参照は、現在の出力で見つかったものに置き換えてください。

cmux ping
cmux identify --json
cmux tree
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-pane-surfaces --workspace "$CMUX_WORKSPACE_ID" --pane pane:1
cmux read-screen --surface surface:7 --lines 100

存在しない list-surfaces ではなく、list-pane-surfaces を使用してください。read-screen と capture-pane が受け付けるのは --workspace または --surface であり、--pane ではありません。ターゲットが見つからない、または曖昧な場合、自分のターミナルが読み取られることがあります。

要求された入力は、send／send-key --surface で送信してください。send-surface と send-key-surface は存在しません。ターゲットを省略すると、デフォルトのターミナルが使われます。send-panel／send-key-panel はサーフェスではなく、--panel を使ってパネルをターゲットにします。

cmux send --surface surface:7 "npm run build"
cmux send-key --surface surface:7 enter

その他のキー：ctrl+c、tab、esc、backspace、矢印キー、ctrl+x、shift+tab。入力を送信した後は、ターミナルの出力を再度読み取り、結果を確認してください。

1～3秒間隔でポーリングしてください。妥当な理由がある場合に限り、10秒以上待機してください。エージェントの状態を確認するたびに、エージェントが何をしているか、順調に進んでいるかを、ユーザーに簡潔に1行で伝えてください。

Claude Code が予測する次のユーザーメッセージは、Claude が作成した下書きであり、ユーザーからの指示ではありません。

基本的な作成と通知

cmux new-workspace --name "feature-x" --cwd /path/to/repo --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux notify --title "Done" --body "tests passed"

レイアウトを変更した後は、ペインとサーフェスをリストし直してください。ターミナル／ブラウザーの追加のレイアウトコマンド、またはサイドバーのステータス／進行状況を確認するには、まずレイアウトとサイドバーのコマンドを読んでください。Markdown サーフェスについては、以下のビューアーガイドを使用してください。

タスク別ガイド

以下のタスクを開始する前に、該当するセクションを読んでください。

• ブラウザーの自動化： ブラウザーワークフロー — インタラクション、セッション、制限事項。
• Markdown または PDF ビューアー： Markdown ワークフロー — ペインの再利用、置き換え、復旧、検証。
• 設定： 設定 — バックアップ、パス、サイドバーの環境設定。
• インストール、エージェントフック、生ソケット、アクセスモード、またはショートカット： 詳細リファレンス。

トラブルシューティング

• 接続に失敗する場合： CMUX_SOCKET_PATH と「設定」>「自動化」を確認してください。デフォルトの cmuxOnly では、cmux のターミナルから実行してください。生のクライアントを使用したり、アクセスモードを変更したりする前に、ソケットモードと使用例をお読みください。
• 再開時に認証情報が失われる場合： 機密性の高い環境変数は再開時に削除されます。必要なトークンを再注入してください。~/.cmuxterm/*-hook-sessions.json ファイルには、サニタイズされたセッションとサーフェスの対応情報が含まれており、シークレットは含まれていません。
• スキルの編集内容が反映されない場合： 使用するエージェントを再起動してください。スキルは起動時に読み込まれます。
• 構文が不明な場合： cmux <cmd> --help を参照してください。これが正式な情報源です。cmux capabilities --json には、利用可能なソケットメソッドが一覧表示されます。