cmux-orchestration

cmux オーケストレーション

最上位のエージェントはコントローラー（Codex、Claude、Fable など）で、証拠を収集し、範囲を限定したパッチを作成し、テストを実行して報告するワーカーの TUI に作業を委任します。コントローラーは、割り当て、状態、競合制御、検証、統合、そしてユーザー向けの最終回答を担います。

すべての実行では、次の項目も読み込みます。

• cmux — ペイン、サーフェス、ルーティング、ヘルスチェック。
• cmux-workspace — 呼び出し元のワークスペースへのスコープ設定、ヘルパーペインの再利用、ソケットの指定、非破壊的な自動化。

不変条件

• ユーザーが別の対象を指定しない限り、すべての操作を呼び出し元のワークスペース内に限定します。
• フォーカス中のウィンドウへのフォールバックより先に、CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH を指定します。
• 明示的な surface:N 参照を使ってワーカーを操作します。
• フォーカスは現在の状態に保ちます。ユーザーからの依頼がある場合に限り、focus-pane、focus-panel、select-workspace、およびフォーカスが変わるタブ操作を使用します。
• ワーカーのサーフェスは開いたままにします。明示的にクリーンアップを依頼された場合、またはタスクの契約に含まれる場合にのみ閉じます。

事前確認

呼び出し元のコンテキストと現在のレイアウトを確認します。

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

右側にヘルパーペインを1つ設けるのが望ましいです。呼び出し元が使っていないことが明らかなヘルパーペインがあれば、そのペインにワーカーのサーフェスを追加します。なければ、右側にターミナルペインを1つだけ作成します。

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

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

プロンプトを送信する前に、返された各 surface:N を状態レジストリに記録します。

ワーカーを起動する

デフォルトのプロファイルは2つです。opus 上の Claude Code（claude-opus）と、gpt-5.5 上の Codex（codex-gpt-5.5）を、明示的に指定したサーフェスで起動します。

rtk cmux send --surface surface:<claude> \
  "rtk claude --dangerously-skip-permissions --model opus --name cmux-claude-opus\n"
rtk cmux send --surface surface:<codex> \
  "rtk codex --yolo -m gpt-5.5 -C \"$PWD\"\n"

Claude は必ず --dangerously-skip-permissions を、Codex は必ず --yolo を付けて起動します。ワーカーは無人で実行されるため、権限の確認プロンプトで停止してはなりません。計画優先の実行では Claude の --permission-mode plan を追加します。これらのフラグは併用できます（「計画優先の委任」を参照）。

実行中の TUI にプロンプトを送信する

cmux send "...\n" が送信まで行うのは、通常のシェルの場合のみです（上記の起動コマンド）。実行中の TUI（Claude Code、Codex）では、末尾の \n はソフト改行として貼り付けられます。プロンプトは送信されずに残り、ワーカーは何も表示せずに停止します。

• 最初のプロンプトは、起動時の CLI 引数として渡す方法を推奨します（rtk claude --dangerously-skip-permissions "…prompt…", rtk codex "…prompt…"）。これにより、TUI の起動完了を待つ競合状態と送信の問題を回避できます。例外：Codex の計画優先の起動は引数なしで行います（「計画優先の委任」を参照）。

• 実行中の TUI への追加の指示は、テキストを送信した後、Enter を明示的に送信します。

  rtk cmux send --surface surface:<worker> "…follow-up prompt…"
  rtk cmux send-key --surface surface:<worker> enter
  

• rtk cmux read-screen --surface surface:<worker> で確認します。入力行が空で、スピナーまたは作業中を示すインジケーターが動作していることを確認してください。確認されていない送信は、届いたものとして扱いません。

計画優先の委任

編集前に調査が必要な作業（根本原因の修正、複数ファイルまたは複数パッケージにまたがる変更、使い慣れていないコードなど）では、ワーカーを計画優先で実行します。ワーカーが計画を立て、あなたが確認して承認した後、ワーカーが自律的に作業を進めます。起動フラグ、shift+tab の操作、ステータス行の確認、承認メニューは、TUI ごとに正確な手順が異なります。計画優先で委任する場合は、ワーカーを起動する前に references/plan-mode.md を最後まで読んでください。

委任パケット

各ワーカーのプロンプトは、単独で成立する契約として送信します。以下を含めてください。

• リポジトリのパスと具体的な目的
• ワーカーの役割とモデル
• 実行モード：計画優先または直接実行
• 対象範囲に含まれるファイル、パッケージ、サーフェス
• 明示的に対象範囲から除外するファイルと動作
• 競合を避けるための、担当ファイルまたは作業範囲
• 期待する証拠：ファイル、行番号参照、コマンド、差分、失敗、スクリーンショット、および明示された不確実性
• 実行する検証コマンドまたはブラウザー操作
• 停止条件：予期しないコード構造、コマンドの繰り返し失敗、認証またはモデルの障害、対象範囲外の編集が必要になった場合

小さく独立した作業範囲を優先します。重複するファイルの担当範囲を割り当てるのは、コントローラーがただちに統合して競合を解決する場合に限ります。

状態レジストリ

タスク台帳または引き継ぎに、簡潔なレジストリを維持します。

• コントローラーの識別情報
• ワーカーの役割とモデル
• workspace:N、pane:N、surface:N
• 送信したプロンプト／目標と開始時刻
• 状態：starting、planning、plan-review、plan-accepted、running、waiting、 blocked、reported、verified
• 申告されたファイルまたは作業範囲
• ワーカーが報告したコマンドと結果
• コントローラーが実施した検証
• 最終処置：accepted、rejected、superseded、blocked

長時間の実行では、cmux のサイドバー状態を使って呼び出し元のワークスペースに進捗を紐付け、オーケストレーションが完了または中断されたら消去します。

rtk cmux set-status orchestration "running" \
  --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
rtk cmux set-progress 0.4 --label "Workers running" \
  --workspace "${CMUX_WORKSPACE_ID:-}"
rtk cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- \
  "Started cmux orchestration"

ワーカーの出力を検証する

検証が済むまでは、ワーカーの出力を信頼できないものとして扱います。フォーカスを変更せずに監視および検証します。

• ワーカーのサーフェスを読み取り専用でポーリングまたは確認します。出力が不明瞭な場合は、簡潔な状況報告をワーカーに求めます。
• 影響の大きい指摘を検証するため、引用されたファイルをローカルで再度開きます。
• 結果が完了の可否を左右する場合は、コントローラーのコマンドを新たに実行して、報告されたテスト結果を再確認します。
• ワーカーのパッチを受け入れる前に、最終的な差分を確認します。
• ワーカーが申告範囲外を編集した場合は、統合を一時停止し、受け入れるか、ユーザー承認のもとでクリーンアップを依頼するか、コントローラーによる編集で置き換えるかを判断します。

停止条件

次の場合は、即興で対応せず、停止して報告します。

• cmux が有効なワークスペース、ペイン、またはサーフェスの参照を拒否した場合。
• ワーカーの TUI がモデルのエイリアス、認証状態、作業ディレクトリ、または起動フラグを拒否した場合は、正確な阻害要因を報告し、モデルのダウングレードやツールの切り替えを行う前にユーザーの承認を得ます。
• 認証によって TUI がブロックされる場合。
• ワーカーの出力を確実に確認または制御できない場合。
• read-screen でプランモードのステータス行または承認メニューを確認できない場合、または再計画を経てもワーカーのプランが範囲外のままの場合。
• コントローラーが安全に統合できない、重複する編集がワーカーに必要な場合。
• ユーザーが承認していない、フォーカスを変更する cmux コマンドがタスクで必要な場合。

図

視覚的な説明が役立つ場合は、assets/fable-orchestrator.excalidraw（またはその PNG 版）でコントローラー／ワーカーのトポロジーを図示しています。