Orca orchestration で Claude と Codex を組ませた記録｜ペアプロは組めるのか、handoff との違い

隣のペインで Codex が動いている。Claude Code から、あれに話しかけられるのか。この素朴な疑問が出発点でした。

Orca で複数のエージェントを並べていると、次に欲しくなるのは連携です。片方に実装させて片方にレビューさせたい、あるいは 2 つのエージェントでペアプロさせたい。Orca には orchestration という、まさにそのための仕組みが載っています。ならばこれを使ったほうが Claude と Codex の協働はやりやすいはずだ、というのが今回の仮説でした。

実際に 2 回走らせて記録しました。1 回目は実作業の委譲、2 回目はこの記事そのもののレビューです。結論から言うと、出てくる形はペアプロと同じ骨格に乗ります。ただし人間同士のペアプロとは、介入の仕方が決定的に違いました。

結論｜3 行で押さえる Orca orchestration

先に要点だけ整理します。

1. 組み上がるのはドライバーとナビゲーターの形です。ペアプロは元から非対称な作業なので、役割分担の骨格はそのまま乗ります。ただし共同注視や短い相互フィードバックまでは今回測っていません
2. 人間同士と違うのは、介入が非同期になることです。途中で指示は送れますが、届くのはワーカーが次に確認したときで、書いている手を止める割り込みにはなりません
3. 効くのは構造化されたやりとりで、届かない沈黙もあります。認証切れは 2 分で表面化した一方、CLI の承認待ちで止まった回は 10 分間ずっと静かでした

きっかけ｜「見えている」と「操作できる」は別だった

最初に確認したのは、ターミナルマルチプレクサ側から隣のエージェントに触れるかどうかでした。画面には Claude Code と Codex が並んでいます。ところがマルチプレクサからは Codex が認識されず、インストールされていない扱いになりました。プロセス一覧には確かにいるにもかかわらず、です。

原因は起動元でした。Codex が Orca 側のランタイムから起動されていたため、マルチプレクサの管理下に入っていなかったのです。同じ画面に並んでいることと、プログラムから操作できることは別問題でした。

ここが分岐点になります。マルチプレクサ層で解こうとすると管理外のプロセスに手が届かないので、Orca 側のターミナル API に回る必要がある。そしてそこまで来ると、単に文字を送り込むのか、それとも orchestration という構造を使うのか、という選択が出てきます。

Orca orchestration とは｜Run / Task / Dispatch の 3 層

orchestration は、Orca に載っているエージェント間の連絡と委譲の層です。用語が 3 つあり、ここを取り違えると設計を誤ります。

Run は名前空間と、コーディネーターの受信箱です。目的をひとつ持ちますが、それだけです。スケジューラではないので、Run を作ってもワーカーの配置や実行順は決めてくれません。

Task は作業項目です。依存関係を持たせられるので、複数の Task をつないで DAG を組めます。状態は pending・ready・dispatched・completed・failed・blocked の 6 つです。

Dispatch は、1 つの Task の 1 回の試行を、1 つのターミナルに割り当てたものです。ここが実質的な権限の所在で、完了報告も生存報告も Dispatch に紐づきます。ターミナルのハンドルは経路情報にすぎず、恒久的な identity ではない、とガイドは明記しています。

タスクを配って報告を受け取る側を Orca は coordinator、受け取って作業する側を worker と呼びます。この記事でも、仕組みの説明ではコーディネーターとワーカー、あとで出てくる役割の話ではナビゲーターとドライバーと書き分けます。

使うには Orca のランタイムが動いている必要があり、設定の Experimental から orchestration を有効化しておきます。コマンドは実行中のランタイムへの RPC として動きます。

素の terminal send と何が違うのか

連携を組む方法は、実際には 2 通りあります。並べると差がはっきりします。

A: 素のターミナル操作

orca terminal send --terminal <handle> --text "<依頼>" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca terminal read --terminal <handle> --json

送って、落ち着くまで待って、読む。3 手を毎回自分で回します。ここで wait --for tui-idle を省くと、相手がまだ考えている最中に読みに行って空振りします。

ただし待てば解決するわけでもありません。この待機が返す「落ち着いた」は、作業が終わった状態と、入力を待って止まっている状態を区別しないからです。返ってきた画面を読んで、完了なのか質問なのかを解釈するのは呼び出し側の仕事になります。

B: orchestration

orca orchestration run-create --objective "<目的>" --json
orca orchestration task-create --spec "<仕様>" --json
orca orchestration worker-start --task <task_id> --worktree current --agent codex --json
orca orchestration check --wait --types worker_done,escalation,question,status --timeout-ms 900000 --json

構造が付くぶんコマンドは増えます。しかし違いは行数ではなく、最後の check --wait が受信側だという点です。A では相手の様子を自分で見に行って解釈しますが、B では完了報告・質問・状況報告・行き詰まりが型を持って届きます。質問には reply で答えられます。

逆向きの経路もあります。作業の途中で方針を足したいときは、Dispatch を宛先にして送れます。

orca orchestration send --to dispatch:<dispatch_id> --subject "追加の指示" --body "<内容>" --json

これは画面への文字の打ち込みではなく、構造化された受信箱への投函です。ワーカーが次に check したときに受け取ります。

handoff には使ってはいけない

ここは仕様として明確に線が引かれています。公式のスキルガイドは、次のような依頼を orchestration で扱うことを禁じています。

• 「これを別のエージェントに渡して」
• 「別の worktree でやらせて」
• 「これを引き継いで」

これらは所有権の移譲であって、監督ではないからです。orchestration の dispatch --inject は、渡す相手に「完了したら報告しろ」という前置きを注入します。所有権を渡すつもりで使うと、渡された側に誰も待っていない報告義務が生えてしまいます。ガイドは、この場合に task-create を実行することすら禁じています。追跡用の行を作った時点で、それは監督された委譲だからです。

監督つきの orchestration を使ってよいのは、依頼者が明示的に「監督して」「完了を待って」「結果を返して」「DAG を組んで」と求めたときだけ、と書かれています。所有権を渡すだけなら、次のどちらかを使って、その後は見に行かないのが正しい形です。

# 新しい worktree ごと渡す
orca worktree create --name <task-name> --no-parent --agent codex --prompt "<依頼>" --setup run --json
 
# すでにいるエージェントに渡す
orca terminal send --terminal <handle> --text "<依頼>" --enter --json

1 回目｜Claude がナビゲーター、Codex がドライバー

ここからが検証です。組んだ構成は次のとおりでした。

役割は人間が決めました。Claude Code が指示・検証・判断だけを担当してファイルには触らず、Codex が実作業をすべて引き受ける形です。役割を決めたあとの受け渡しは Dispatch を通してエージェント間で直結し、人間が出力をコピー & ペーストで運ぶ工程は挟んでいません。

worktree は分けていません。対象リポジトリの既存のチェックアウトをそのまま指定しています。ガイドが、衝突が実際に起きる場合か依頼者が明示的に求めた場合以外は新しい worktree を作るなと指示しているためです。実際に Orca が返したレシートでも、worktree は再利用、エージェントターミナルは新規作成、と記録されていました。

タスクの仕様の書き方にも工夫を入れました。手順・対象・既知の落とし穴は課題管理側に書いておき、仕様には「最初にこれを読め」と参照だけを書いています。仕様の本文にすべて展開するより、渡す情報を一箇所で版管理できるほうが後から効きます。

なお、この構成に踏み込んだ直接の引き金は生産性の向上ではありませんでした。Claude Code 側が数日前に利用上限に当たって一度止まっており、消費を抑えるために「自分は書かずに見る側へ回り、手を動かすのは Codex に任せる」という方針が先にあったためです。片方の予算が尽きたから、もう片方に体を借りる。実務ではこちらの動機のほうが起こりやすいのではないかと思います。

起動は 41 秒

Orca のランタイムに問い合わせて取れた時刻です。

Run の作成からワーカーが動き出すまで 41 秒です。構造を足すコストとしては十分に軽いと言えます。

ただし、これはコマンドを打ち始めてからの時間です。その前段に、どのエージェントをどこで動かすか決め、ハンドルを特定し、orchestration と素のターミナル操作のどちらを使うか判断する工程があります。話題が出てから実際にワーカーが動き出すまでで測ると、13 分ほどかかっていました。

12 分で 4 通が届いた

起動から 12 分のあいだに、ナビゲーター側へ 4 通のメッセージが届きました。内訳は質問が 3 通、状況報告が 1 通で、行き詰まりの通知はゼロです。

ナビゲーターの側は、待機のタイムアウトで起こされたわけではありません。実際、15 分のタイムアウトで待ち直した回数は 0 回でした。届いたものに応答し、確認して待ち直す。それが実際の動き方です。

ただし 4 通が 1 通ずつ別々に待機を起こしたかどうかは、記録から確定できていません。check は届いた分をまとめて 1 つの Delivery として返すため、複数通が同じ回で一緒に来ることがあります。確かなのは、タイムアウトではなく受信で起こされたという点までです。

この経路が効いたのは、外部サービスの認証が期限切れになっていた件でした。ワーカーは作業対象に到達できず、その場で質問を上げてきています。起動から 2 分ほどで表面化しました。素のターミナル操作でも、待機して画面を読めば同じことに気づけたはずです。ただしその場合、止まっている画面を読み解いて「これは認証エラーで詰まっている」と判断するのはナビゲーターの側の仕事になります。何を聞かれているかが構造化されて届くかどうかが、この 2 つの差です。

返信だけで済む質問と、人間が要る質問

届いた 4 通は、性質で 3 つに分かれました。ここを分けておくと、どこまで自動で回るかの見積もりが立ちます。

仕様の曖昧さは、この仕組みがいちばん素直に効く領域です。テキストで返せば済みます。今回は、指示に書いた件数と入力データの実際の件数が違っており、ワーカーが正しく指摘してきました。件数を直書きせず「まだ処理されていないもの」という判定基準で渡すべきだった、という反省がここから出ています。

環境の権限には人間の対応が要ります。対話的なログインを通せるのは人間だけです。外部リソースに触るタスクを渡すなら、着手前に認証の生死を確かめておくと 1 往復減ります。

品質の判断は少し複雑です。返信自体はテキストで返せますが、判断の材料を見るのはナビゲーターの役目でした。つまり「書かない側に回れば何も読まなくて済む」とはなりません。読まなくて済むのではなく、読む対象を選べるというのが正確なところです。

判断を仰ぐときは、判断材料を作って渡す

品質の判断について、ワーカー側の動きに再現する価値のある工夫がありました。

対象が 20 件以上あったため、ワーカーは 1 件ずつ聞くのではなく、全件を 1 枚にまとめた一覧を自分で作ってから判断を仰いできました。ナビゲーターはその 1 枚を見るだけで全体を評価できます。

判断を求めるときに材料をこちらで整えておく。人間相手のレビュー依頼では当たり前の作法ですが、エージェント間の受け渡しでも同じように効きます。仕様を書くときに「判断を仰ぐ場合は材料をまとめてから聞け」と入れておくと、往復が短くなります。

なお、このときナビゲーターが出した回答は不採用でした。判断の基準がリポジトリ内のドキュメントに書かれており、それを割っていたためです。あわせて「諦める前に代替を一段探し、無ければその項目を落として確定してよい」という条件を付けています。ただ却下するのではなく、次に進める条件まで書く。ここも人間のレビューと同じです。

終わり方はターミナルの切断だった

12 分後、この実験は完了報告ではない形で終わりました。エージェントのターミナルが閉じられ、プロセスが落ちています。ランタイムの記録では、終了理由は operator による切断、失敗の内容は「ターミナルが operator の要求で閉じられた」でした。稼働時間は 11 分 43 秒です。

生存報告は最後まで 1 件も記録されていません。この記事で実測した Dispatch は 3 つありますが、いずれも生存報告はゼロでした。ガイドは、長い作業のときに Dispatch の前置きが求めた場合に限って生存報告や状況報告を送るよう指示しています。つまり届くかどうかは前置きの内容とワーカーの実装次第で、こちらが --types に並べただけでは生えません。結果として、ナビゲーターは相手が生きているか知る手段を持たないまま待つことになりました。

なお Task 側の状態は失敗ではなく ready に戻っており、同じ Task をそのまま再投入できます。失敗の回数は 1 で、3 回続くとその Task は失敗として打ち切られます。ワーカーが 1 回落ちても作業単位は残る設計です。

2 回目｜この記事のレビューを Codex に頼んだ

同じ仕組みで、この記事そのもののレビューを Codex に依頼しました。今度は既に起動していた Codex にそのまま渡しています。

orca orchestration run-create --objective "記事のレビュー" --json
orca orchestration task-create --spec "<レビュー観点と対象ファイル>" --json
orca orchestration worker-start --task <task_id> --terminal <既存の handle> --json

--terminal は、新しくエージェントを立ち上げる代わりに、既に動いている端末をそのまま使う経路です。完了後に同じ端末へ次のタスクを渡せば、同じセッションが文脈を保ったまま次の作業に入れます。今回は Run の作成から Dispatch 成立まで 25 秒でした。新規に立ち上げた 1 回目の 41 秒より短いのは、起動の待ちが無いぶんです。

トレードオフもあります。--terminal は --model や --effort と併用できません。推論の強さをタスクごとに変えたいなら新規で立てる、文脈を引き継ぎたいなら既存を使う、という使い分けです。

10 分間、何も届かなかった

ここで想定外のことが起きました。check --wait を 10 分回しましたが、届いたメッセージは 0 通です。

画面を見に行くと、Codex は生きていました。ただし作業中ではなく、CLI 側の承認プロンプトで人間の操作を待って止まっていたのです。人間が承認すると、そこから 2 分半で完了報告が返ってきました。

これは仕組みの穴というより、経路の性質です。orchestration に流れるメッセージは、完了報告も質問も状況報告も、いずれもワーカーが自分の意思で送るものです。エージェント CLI 自身が承認ダイアログを出して止まっている状態は、ワーカーから見れば自分が止まっていることにも気づいていないので、どの型にもなりません。送る主体が動けなくなった瞬間に、この経路は無音になります。

指摘 8 件、うち 2 件は事実の誤りだった

返ってきた完了報告は、重要度順に 8 件の指摘を含んでいました。そのうち 2 件は、この記事に書いていた事実の誤りです。

1 つは、ペアプロが組めない理由を「同じ worktree で 2 人が同時に書くと壊れるから」と一般則として書いていた点です。ガイドを読み直すと、並列作業については同じ worktree の中にワーカーごとの端末を作る形が基本で、worktree を分けるのは実際に衝突が起きる場合だけ、と書かれています。並列そのものは想定内でした。危ういのは同一ファイルを同時に触らせる構成であって、worktree の共有ではありません。

この指摘をたどると、その先にもっと大きな取り違えがありました。そもそもペアプロは 2 人が同時に同じファイルを書く作業ではありません。この前提が崩れると、「同時に書けないからペアプロにならない」という結論ごと成り立たなくなります。前の節はその結論を書き直したものです。

もう 1 つは、素のターミナル操作と比べたときの表現です。当初は「素の方式なら 15 分気づかない」と書いていましたが、掲載していたコマンド例は 60 秒で待機が返るものでした。比較の条件が揃っていない断定です。この記事では、待機が返す「落ち着いた」が完了と入力待ちを区別しない、という違いに書き直しています。

残りは、単一の試行から一般論を導いている箇所を弱める指摘、--types に並べた型だけが待機を起こすという仕様の取り違え、そして表記スタイルの違反でした。いずれも直しています。

2 周目｜今度は反転させすぎだと言われた

前回の指摘を反映し、結論を反転させたうえで、同じ Codex にもう一度渡しました。--terminal で同じ端末を指定するだけなので、新しいエージェントを立ち上げる工程はありません。返ってきたのは 6 件で、そのうち 2 件はまた事実の誤りでした。

1 件は、この記事で最も重要な訂正です。「ナビゲーターが介入できるのは、聞かれたときと終わったときの 2 か所だけ」と書いていましたが、これは誤りでした。ガイドには、コーディネーターが任意の時点でワーカーに指示を送る経路が用意されています。

orca orchestration send --to dispatch:<dispatch_id> --subject "追加の指示" --body "<内容>" --json

見落としていたのは経路の有無ではなく、その性質のほうを書くべきだったという点でした。これは割り込みではなく受信箱への投函なので、届くのはワーカーが次に確認したときです。「介入できない」ではなく「介入が非同期になる」が正しい説明です。

もう 1 件は、反転そのものへの指摘でした。役割の非対称はペアプロの必要条件ではあっても十分条件ではなく、共同注視や短い間隔の相互フィードバックを測っていない以上「ペアプロそのもの」とは言えない、という内容です。1 周目で一般化を弱めたはずが、今度は逆向きの一般化に乗り換えていました。該当箇所は「骨格までは確認できた」という表現に直しています。

後片付けで既存の端末は閉じられない

完了報告を処理したあとは、解放するか次のタスクを渡すかを必ず決めます。

orca orchestration worker-release --dispatch <dispatch_id> --json

解放は中断ではなく後片付けです。出力を保全してから、その Dispatch が所有している端末だけを閉じます。今回は人間が先に立ち上げていた端末に渡していたため、応答は「外部の端末なので保持した、プロセスへの操作はしていない」という内容でした。他人が使っているセッションを借りて仕事を頼んでも、片付けで勝手に閉じられることはありません。

ペアプロに近づく｜非対称は欠陥ではない

当初の質問は「ペアプロさせたいならどうするのが一番いいか」でした。2 回とも、組み上がったのは片方が作業し、もう片方が判断する非対称な形です。

検証の途中まで、これをペアプロの失敗と見ていました。「同時に 2 人で書けないのだから、ペアプロにはならなかった」という整理です。しかしこれは、ペアプロが何なのかを取り違えていました。

ペアプロはもともと非対称な作業です。 ドライバーがキーボードを持って書き、ナビゲーターは書かずに見て口を出す。1 つのファイルを 2 人が同時に叩くことはありません。つまり「1 つの worktree のファイルを複数のエージェントが同時に触らない」構成は、ペアプロの制約ではなく、ペアプロの前提と同じ形です。

そう見ると、2 回とも出てきた形は失敗ではありません。実装役の Codex がドライバー、レビュー側の Claude Code がナビゲーター。仕様の曖昧さや品質の判断を聞かれて答え、途中で方針を修正する。役割分担としては、ペアプロと同じ骨格に乗っています。

ただし、役割の非対称はペアプロの必要条件であって十分条件ではありません。人間のペアプロを成り立たせているものには、同じ画面を見続ける共同注視、短い間隔の相互フィードバック、こまめな役割交代もあります。今回の 2 回はいずれもタスク単位の委譲で、そこまでは測っていません。1 回目は監督つきの委譲、2 回目は完了後のレビューとしても説明がつきます。ペアプロと呼べる骨格までは確認できた、というのが今回の到達点です。

役割の交代自体はできます。--terminal で同じエージェントに次のタスクを渡せば、事情を知っている相棒と組み続けられますし、実装の Task とレビューの Task を逆向きに割り当てれば、ドライバーとナビゲーターを入れ替えられます。ピンポンで回す形も、Task を作り直す手数を払えば組めます。

なお、ガイドには「レビュー目的の完了報告は所見を報告するだけであり、コーディネーターがファイルを編集する権限を与えるものではない」と書かれています。これは Dispatch の権限境界を定めた規則であって、ペアプロを想定した設計だという根拠ではありません。ただ、ナビゲーターが横からキーボードを奪わないという分担と形が似ているのは確かです。今回も、指摘を受けて直したのは依頼した側でした。

人間のペアプロと違うところ｜介入が非同期になる

では何が違うのか。ナビゲーターの介入が非同期になることです。

人間同士のペアプロで効いているのは、相手が誤った方向に進んだ瞬間に「あ、それ違う」と言えることです。手が止まる前に軌道が直る。ナビゲーターの価値の多くは、このリアルタイム性から来ています。

orchestration でも、途中で指示を送ること自体はできます。前に挙げた send --to dispatch:<dispatch_id> がその経路です。ただしこれは割り込みではありません。届くのはワーカーが次に check したときなので、いま書いている手を止める効果はありません。ドライバーが黙って誤った方向に 10 分進んでいるあいだ、こちらの声はポストに入ったまま待つことになります。

2 回目に起きた「承認待ちで 10 分間何も届かない」も、同じ構造の裏返しです。ドライバーは止まっていましたが、自分が止まっていることを送るべき事柄だと認識していなかったので、ナビゲーターには何も届きませんでした。送るのも受け取るのも、ワーカーが動いていることが前提になっています。

補い方は 3 つあります。判断が要る分岐を仕様の中で先に洗い出して「ここに来たら聞け」と書いておくこと。タスクを小さく切って完了報告の回数を増やし、口を挟める機会自体を増やすこと。そして、長い作業では状況報告を求めておくことです。ガイドが依存の連鎖を 3〜4 段より深くするなと書いている範囲で、細かく刻むほうがナビゲーターは効きます。

線引き｜どこから orchestration を使うか

ここまでを踏まえた使い分けの目安です。

判断の軸は「ワーカーから届いてほしいものがあるか」です。完了報告も質問も要らないなら、構造は要りません。ガイドが依存の連鎖を 3〜4 段より深くするなと書いているとおり、深く組むほど管理コストが跳ね上がる点にも注意してください。

FIXIT

えっ、ペアプロしたかったのに、片方に頼む形になっちゃったの？

Hayate

ペアプロも書く人と見る人に分かれます。2 人同時には叩かないので、そこは同じ形です。

FIXIT

あ、そっか。じゃあ人がやるのと同じことができてるんだ。

Hayate

骨格までは、ですね。途中で指示は送れますが、届くのは相手が次に確認したときです。

FIXIT

えっ、じゃあ変な方向に進んでても、その場では止められないの？

Hayate

止まりません。なので仕様に「ここで聞け」と書いて、タスクを小さく刻んでおきます。

まとめ｜骨格は乗る。リアルタイム性だけが無い

Orca orchestration は、エージェント間の受け渡しに構造を与える仕組みです。Run で名前空間を作り、Task で作業を定義し、Dispatch で試行を割り当てる。人間がコピー & ペーストで仲介する工程が消えるのは、確かに大きな違いです。

2 回走らせて出てきたのは、ドライバーとナビゲーターに分かれる形でした。検証の途中まではこれをペアプロの失敗と見ていましたが、それは前提の取り違えです。ペアプロはもともと非対称で、2 人が同じファイルを同時に叩くものではありません。書く役と見る役に分かれること自体はペアプロの形なので、骨格としてはそのまま乗ります。共同注視や短い間隔の相互フィードバックまで再現できるかは、今回の 2 回では確かめていません。

人間同士との違いは、介入が非同期になることでした。途中で指示を送る経路はあります。ただし届くのはワーカーが次に確認したときなので、書いている手を止める割り込みにはなりません。承認待ちで 10 分間ずっと静かだった回は、送る側も受け取る側もワーカーが動いていることを前提にしている、という構造をそのまま示しています。補うには、判断が要る分岐を仕様に先出ししておくか、タスクを小さく刻んで報告の回数を増やすことになります。

そして、任せきりにはなりませんでした。認証の期限切れは人間しか通せず、品質の判断にはナビゲーターが実物を見る必要があり、承認プロンプトは人間が押すまで動きません。この記事自体、同じ仕組みで Codex に 2 周レビューしてもらい、結論そのものを 2 度書き直しています。読まなくて済むのではなく、読む対象を選べる。この期待値で組むと、うまく噛み合うと思います。

FIXIT は AI 駆動開発のクリエイティブスタジオとして、エージェントの並列運用やツールチェーンの設計を実プロジェクトで磨いています。チームへの導入を検討している方は AI 開発ツール導入支援 をご覧ください。