cmux-workspace

cmux ワークスペース

タスクをエージェントを起動した cmux ワークスペース内に限定する必要がある場合は、このスキルを使用してください。ワークスペースは、cmux のサイドバーにあるタブのような単位です。ワークスペースには分割ペインがあり、各ペインには 1 つ以上のサーフェスが含まれます。サーフェスは、ユーザーが操作するターミナルまたはブラウザーのセッションです。

デフォルトのルール

ユーザーが別のワークスペース、別のウィンドウ、またはグローバルな状態を明示的に指定しない限り、操作の対象は現在の呼び出し元のワークスペースにしてください。

視覚的にフォーカスされている cmux ワークスペースが正しい対象だと決めつけないでください。エージェントが 1 つのワークスペースで動作していても、ユーザーは別のワークスペースを見ている場合があります。まず呼び出し元の環境を優先してください。

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

CMUX_WORKSPACE_ID をデフォルトのワークスペースの基点として、CMUX_SURFACE_ID をデフォルトの呼び出し元のターミナル／サーフェスの基点として使用してください。これらが設定されていない場合は、cmux identify --json を使用し、現在フォーカスされている cmux コンテキストを使用していることを明示してください。

中断を伴わない自動化

エージェントが呼び出し元のワークスペースで作業している間、ユーザーは別のワークスペース、ウィンドウ、またはアプリに視覚的にフォーカスしている場合があります。レイアウトとフォーカスは別の要素として扱ってください。推測でフォーカスを変更する動詞を呼び出さないでください。

ユーザーから明示的な依頼がない限り、次の操作は呼び出さないでください。

• select-workspace は、表示されているサイドバーのタブを切り替えます。
• focus-pane／focus-panel は、ペインまたはサーフェスのフォーカスを強制的に移動します。
• フォーカスを変更するアクションを指定した tab-action。

これらはクリックと同様にユーザーに影響する操作です。このルールは、ユーザーが別の場所を見ている可能性があるため、呼び出し元自身のワークスペース内でも適用されます。

レイアウトは一度に追加する形で構築してください。適切なサーフェスがすでに設定された新しいペインを作成するコマンドを優先してください。

# pane and content in one call, no follow-up needed
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765"
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down

作成、移動、フォーカスの順に操作を連ねるのは避けてください。レイアウトコマンドが有効な surface: または pane: の参照を拒否した場合、フォーカスを変更して回避しないでください。問題をユーザーに報告して停止してください。

動詞が対応している場合は、必ず --focus false を渡してください。move-surface --focus false はユーザーが現在注目している対象を維持します。他のコマンドにも、今後同じフラグが追加される可能性があります（https://github.com/manaflow-ai/cmux/issues/1418、https://github.com/manaflow-ai/cmux/issues/2820）。

右側の補助ペイン

現在のタスクの補助出力（プレビューアプリ、TUI、ログ、一時的なシェル、ブラウザーチェックなど）を開く場合は、呼び出し元のターミナルの右側にある補助ペインを再利用し、ワークスペースを整理してください。

まず、呼び出し元のコンテキストとペインを確認してください。

cmux identify --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json

次の方針を使用してください。

• 呼び出し元のワークスペースに、呼び出し元以外の補助ペインがすでにある場合は、別のペインを作成せず、そのペインに新しいサーフェスを追加してください。

  cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false
  

• 補助ペインがない場合は、右側にペインを 1 つだけ作成してください。

  cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
  

• 同じ自動化によって作成された、明らかに古い補助ペインが複数あり、ユーザーから整理または再利用を依頼された場合は、右側の補助ペインを 1 つ残し、重複分を削除してください。古い補助出力だと確信できないペインは閉じないでください。
• 新規または再利用した補助サーフェスには、明示的なサーフェス参照を指定してコマンドを送ってください。ユーザーから依頼されない限り、そのサーフェスにフォーカスしないでください。

つまり、「開いて」という依頼が繰り返された場合、通常は分割を増やさず、既存の右側の補助ペインにタブを作成してください。

補助ターミナルを作成したら、作業がそこで表示されていると伝える前に、使用可能であることを確認してください。

cmux surface-health --workspace "${CMUX_WORKSPACE_ID:-}"
cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:<helper> --lines 20
cmux top --workspace "${CMUX_WORKSPACE_ID:-}" --processes --format tsv

read-screen が Terminal surface not found を報告した場合、または surface-health で補助ターミナルが接続されておらず、top にもそのターミナルのプロセスが表示されない場合は、cmux CLI／ランタイムのバグとして扱ってください。コマンドがワークスペース内で実行されていると伝えてはいけません。作成した空の補助サーフェスを削除し、バグを報告するか、すでに生成されている cmux ターミナルサーフェスを使用してください。ユーザーがその回避策を明示的に依頼しない限り、表示を伴うハンドオフに、非表示の tmux、nohup、または切り離されたバックグラウンド処理を代替手段として使用しないでください。

アーティファクトのプレビュー

タスクで動画、画像、確認済みフレーム、スクリーンショット、PDF、その他のユーザー向けアーティファクトが生成された場合は、引き渡し前に cmux で最終アーティファクトを開いてください。呼び出し元のワークスペースの右側ヘルパーペインにファイルプレビュータブとして表示し、--no-focus を使用してユーザーが現在使用しているターミナルの選択状態を保ってください。

最終的なユーザー向けアーティファクトは /cmux-assets/<branch>/... に保存してください。ルートボリュームが読み取り専用で /cmux-assets を作成できない場合は、現在のリポジトリチェックアウト内の cmux-assets/<branch>/... を使用し、そのフォールバックを明記してください。スクラッチ用途に限り /tmp を使用し、採用したアーティファクトは開いたり報告したりする前に、永続的なツリーへコピーしてください。

絶対パス、または現在のリポジトリチェックアウトからの相対パスを使用してください。アーティファクトがワークツリー内にある場合は、最終的な引き渡し前に永続的なブランチ別アセットツリーへコピーしてください。ワークツリー内でしか使えないパスを報告してはいけません。

ワークスペースとペインは、次の順序で特定してください。

1. CMUX_WORKSPACE_ID と CMUX_SURFACE_ID を優先してください。
2. これらが設定されていない場合、または cmux に拒否された場合は、cmux identify --json を確認し、現在フォーカスされている cmux のコンテキストにフォールバックすることを明記してください。
3. 呼び出し元以外のヘルパーペインがすでに存在し、明らかに適切であれば、それを再利用してください。
4. ヘルパーペインがない場合は、--focus false を指定して右側に作成し、ペインを再度一覧表示してペイン参照を取得してください。

テンプレート：

ARTIFACTS=(
  "/cmux-assets/<branch>/demos/demo.mov"
  "/cmux-assets/<branch>/demos/frame-tail.png"
)

WORKSPACE="${CMUX_WORKSPACE_ID:-}"
SURFACE="${CMUX_SURFACE_ID:-}"

cmux identify --json
cmux list-panes --workspace "$WORKSPACE" --json
cmux list-pane-surfaces --workspace "$WORKSPACE" --json

# Pick an existing non-caller helper pane from the pane list. If none exists:
cmux new-pane --workspace "$WORKSPACE" --type terminal --direction right --focus false
cmux list-panes --workspace "$WORKSPACE" --json

cmux open "${ARTIFACTS[@]}" \
  --workspace "$WORKSPACE" \
  --pane pane:<right-helper> \
  --no-focus
cmux list-pane-surfaces --workspace "$WORKSPACE" --json

呼び出し元の環境変数が古いワークスペースを指しているために cmux open が失敗した場合は、cmux identify --json の参照を使用して一度だけ再試行してください。他のワークスペースを推測で次々と試してはいけません。開く処理が引き続き失敗する場合は、失敗を報告し、アーティファクトの正確なパスを記載してください。

階層

• Window：macOS の cmux ウィンドウです。
• Workspace：サイドバーの項目です。UI ではタブと呼ばれる場合がありますが、CLI／ソケット API ではワークスペースと呼びます。
• Pane：ワークスペース内の分割領域です。
• Surface：ペイン内のタブです。サーフェスはターミナルまたはブラウザパネルです。
• Panel：サーフェス内の内部コンテンツタイプです。パネル内部を操作するより、CLI のサーフェスコマンドを優先してください。

現在のコンテキストを確認する

cmux identify --json
cmux current-workspace --json
cmux list-workspaces --json
cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-panels --workspace "${CMUX_WORKSPACE_ID:-}" --json

ログや引き渡しで安定した UUID と人が読みやすい参照の両方が必要な場合は、--id-format both を使用してください。

cmux --json --id-format both identify

ワークスペース単位の操作

環境変数が設定されている場合でも、明示的なワークスペースフラグを優先してください。これにより、自動化の監査が可能になり、別のウィンドウでフォーカスされているワークスペースに誤って影響することを防げます。

# create a new workspace when the user asks for a new task area
cmux new-workspace --name "debug auth" --cwd "$PWD"

# rename / close (only when explicitly requested)
cmux rename-workspace --workspace "${CMUX_WORKSPACE_ID:-}" -- "build fix"
cmux close-workspace --workspace workspace:4
cmux close-surface --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:3

# additive layout (safe, no focus side effects beyond the command's own defaults)
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal

# focus-changing (USER-AFFECTING, only on explicit ask, see Non-Disruptive Automation above)
cmux select-workspace --workspace workspace:2
cmux focus-pane --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2
cmux focus-panel --workspace "${CMUX_WORKSPACE_ID:-}" --panel surface:3

呼び出し元のターミナル

現在のターミナルは、エージェントを呼び出したサーフェスです。相対パスを使う操作では、最も安全な基準として扱ってください。

# send to the focused terminal in the caller workspace
cmux send "npm test\n"

# send to the exact caller surface
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n"
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

ユーザーからその対象を指定された場合を除き、他のワークスペースでキー入力を送信したり、サーフェスを閉じたり、フォーカスを変更したりしてはいけません。

サーフェスの移動

ペイン内でサーフェスの順序を変更します。

cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --after surface:3
cmux move-surface --surface "${CMUX_SURFACE_ID}" --index 0

サーフェスを別の既存ペインへ移動します。ユーザーの現在の操作対象にフォーカスを保つには、--focus false を指定してください。

cmux move-surface --surface surface:240 --pane pane:172 --focus false

サーフェスを新しいペインに分割して移動します。

cmux drag-surface-to-split --surface surface:240 down

既知の操作上の問題：drag-surface-to-split は現在 V1 を経由し、UI のフォーカスを使ってワークスペースを特定するため、呼び出し元のワークスペースが画面上でフォーカスされているワークスペースでない場合、ERROR: Surface not found で失敗することがあります。https://github.com/manaflow-ai/cmux/issues/1901 で追跡されており、https://github.com/manaflow-ai/cmux/issues/3189 に関連しています。この問題が解決するまでは、作成してから分割するのではなく、レイアウトを追加する方法（上記の「非妨害型の自動化」を参照）を優先してください。

移動に失敗した場合、復旧のために focus-pane や focus-panel を呼び出してはいけません。失敗を報告して終了してください。

サイドバーの状態

ステータス、進捗、ログは通常、現在のワークスペースに関連付けて、サイドバーにこのタスクが反映されるようにしてください。

cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"

再ビルドと再読み込み

cmux アプリ／ランタイムを変更する場合は、アクティブなワークツリーからタグ付きで再読み込みしてください。タグ付きの再読み込みでは、分離されたアプリ名、バンドル ID、デバッグソケット、DerivedData パスが作成されます。

./scripts/reload.sh --tag <short-tag>

再読み込みの出力に Dev web origin が含まれている場合は、引き継ぎの前に同じワークツリーから対応する開発サーバーを起動し、応答することを確認してください。

cd web
CMUX_PORT=<printed-port> CMUX_PORT_RANGE=<range> CMUX_PORT_END=<end> bun dev
curl -fsS "http://127.0.0.1:<printed-port>"

そのサーバーは右側のヘルパーターミナルで実行し、read-screen または top でターミナルが存在することを確認してください。ヘルパーターミナルを作成できない場合は、非表示のバックグラウンドフォールバックを使わず、cmux CLI／ランタイムのバグとして報告してください。

タグなしの cmux DEV はビルドも起動もしないでください。テストやツールでソケットが必要な場合は、タグ固有のソケットを使用してください。

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

タスクで共有 iOS／ランタイムコードを扱う場合は、ワークツリーから iOS の再読み込みフローも実行してください。

ios/scripts/reload.sh --tag <ios-tag>

ソケットとアクセス

デフォルトにフォールバックする前に、cmux が指定するソケットパスを使用してください。

SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"

ソケットアクセスは、無効、cmux が起動したプロセスのみに制限、またはすべてのローカルプロセスを許可、のいずれかです。コマンドが接続できない場合は、設定を変更する前にケイパビリティを確認してください。

cmux capabilities --json
cmux ping

参考資料

• references/commands.md では、ワークスペース、ペイン、サーフェス、通知、ユーティリティの各コマンドを網羅しています。
• ../cmux-browser/SKILL.md では、同じ現在のワークスペースに関するルールに従うブラウザーサーフェスについて説明しています。

ルール

• デフォルトでは、現在の呼び出し元のワークスペースで作業してください。
• フォーカス中のウィンドウへのフォールバックより先に、CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH を使用してください。
• 状態を変更する操作では、明示的な --workspace フラグと --surface フラグを優先してください。
• ユーザーから明示的に依頼されない限り、focus-pane、focus-panel、select-workspace、またはフォーカスを変更する tab-action の動詞を呼び出さないでください。ユーザーは別のワークスペース、ウィンドウ、アプリを表示している可能性があります。
• move-surface と、対応している作成動詞には、--focus false を渡してください。
• 補助出力には右側のヘルパーペインを再利用し、存在しない場合に限り作成してください。
• 最終的な動画、画像、確認済みフレーム、その他のユーザー向け成果物は、/cmux-assets/<branch>/... または明示されたフォールバック先 cmux-assets/<branch>/... に保存し、引き継ぎ前に cmux open ... --no-focus で右側のヘルパーペインに開いてください。
• レイアウトは new-pane --type ... --url ... を使って追加的に構築し、作成してから移動し、フォーカスする一連の操作は避けてください。
• CLI コマンドが有効なサーフェス参照またはペイン参照を拒否した場合は、ユーザーに報告してください。フォーカスを変更して回避しないでください。
• ユーザーが対象を指定しない限り、別のワークスペースを閉じたり、フォーカスしたり、移動したり、入力を送ったりしないでください。
• チャットやコマンドの例では短い参照を使用してください。UUID はログ、永続化、デバッグに限って使用してください。
• アプリ／ランタイムの変更では、引き継ぎ前の実機確認として、必ずワークツリーから ./scripts/reload.sh --tag <tag> で再読み込みしてください。
• タグ付きの再読み込みで Dev web origin が出力された場合、同じワークツリーで開発サーバーが稼働し、curl -fsS <Dev web origin> が成功するまで、引き継ぎは完了していません。