Codexマルチエージェント・オーケストレーターを作ってみた｜完全自走に寄せるために考えたこと

はじめに

こんにちは。
業務改善エンジニアのこめまるです。

今回は、Codex を複数の役割に分けて協調実行させるオーケストレーターを作ってみた話をまとめます。

1つの AI に全部まとめて依頼するのではなく、

• 司令塔
• 調査担当
• 実装担当
• 検証担当

のように役割を分けて、なるべく人が細かく指示しなくても前に進む構成を目指しました。

最初は「複数エージェントで相談しながら進める」色が強かったのですが、改善を重ねる中で、現在は execution-first、つまり計画だけで終わらず、毎ターン実編集まで進む思想にかなり寄せています。

この記事はこんな人におすすめ

• Codex CLI を使っている方
• 複数エージェント構成に興味がある方
• AI コーディングを「単発補助」ではなく「継続実行」に寄せたい方
• 完全自走っぽい仕組みをどう設計するか知りたい方

これは何か

codex-multi-agent-app は、Codex を複数の役割に分けて協調実行させるためのオーケストレーターです。

役割は以下の4つです。

• Parent: 全体方針、進行、停止判定、次アクション決定
• Research: 影響範囲、対象ファイル、前提、制約の整理
• Implement: 実ファイル編集
• Test: build/check、確認観点、回帰確認

イメージとしてはこんな感じです。

[Parent]
  |- 方針決定
  |- 進行管理
  |- 停止判定
  `- 次アクション選定

[Research] 調査
[Implement] 実装
[Test] 検証

ポイントは、役割を分けることで1つの AI に全部を背負わせないことです。

全体アーキテクチャ

大きくは次の3層です。

1. 実行層

中心になるのは以下です。

• autonomous-orchestrator.mts
• auto-orchestrate-windows.mjs
• auto-orchestrate-tmux.mjs
• agent-viewer.mjs
• agent-viewer-helpers.mjs

この中で autonomous-orchestrator.mts が Parent の頭脳です。

主にやっていることは、

• 各 worker の実行
• 進行管理
• 停止判定
• report 生成
• budget pause
• 自動継続

です。

2. Worker 実行層

Research / Implement / Test は、それぞれ codex exec を使った別 worker として走ります。

ここでは、同じ文脈を雑に共有するのではなく、role ごとの prompt と session を持つようにしています。

3. 状態・レポート層

このアプリは単発実行で終わらないように、かなり状態を持ちます。

たとえば以下です。

• base goal
• latest instruction
• active directive
• internal phase
• execution unit
• worker sessions
• final report
• budget pause snapshot
• next task candidates

これによって、

• 継続
• 再開
• 追加指示
• 自動次タスク選定

が可能になっています。

設計の考え方

1. 完全自走を目指す

このアプリの大きな思想は、人が細かく刻まなくても、AI 側が自律的に作業を分解して進めることです。

理想形は以下です。

1. 人は大きな goal を渡す
2. Parent が internal phase に分解する
3. さらに execution unit に分解する
4. Research / Implement / Test を必要に応じて動かす
5. 結果を Parent が解釈する
6. 安全なら次フェーズへ自動継続する
7. 危険な場合だけ人に聞く

つまり、単なる自動化ではなく、自律的な進行管理を目指しています。

2. execution-first に寄せる

初期の課題は、計画だけして終わることでした。

そこで後半では Parent の行動原則を次のように変えました。

• broad goal をそのまま議論し続けない
• 1 ターンを 1〜3 ファイル規模の実装単位に縮める
• plan-only turn を抑制する
• 実編集 + build/check の証跡がないと complete にしない

この変更によって、計画だけで終わらず、実コード変更まで進みやすくなりました。

3. Parent に reviewer / navigator を持たせる

途中から、Parent は単なる司令塔ではなく、結果を読む役 も持つようにしました。

これによって Parent は、

• 何が本当に完了したか
• 何がまだ meaningful work として残るか
• 次に自然なタスクは何か

を解釈できるようになりました。

4. 安全な自動継続

auto-continue は無条件ではありません。

たとえば、以下のような条件を見ています。

• hard failure がない
• recent edit evidence がある
• recent build/check evidence がある
• 外部依存リスクが低い
• expected file scope が小さい

この条件を満たしたときだけ、Parent は次へ進みます。

実装済みの主な機能

interactive continue

TaskComplete 後でも Parent を終了せず、awaiting_instruction に入って追加指示を受けられるようにしています。

これによって、同じ run context を維持したまま継続できます。

baseGoal / latestInstruction / activeDirective の分離

追加指示を入れたときに、元の broad goal を繰り返してしまう問題がありました。

これを避けるために、状態を以下に分離しました。

• baseGoal: 最初の大目標
• latestInstruction: 直近の指示
• activeDirective: 今ターンで本当に優先する指示

これによって、文脈を保持しつつ、今ターンの優先順位だけ上書きできます。

final report

処理終了時には、Parent が詳細レポートを生成します。

保存形式は以下です。

• final-report.txt
• final-report.json

内容としては、

• overall status
• completed phases
• remaining phases
• changed files
• build/check results
• worker summaries
• Parent interpretation
• Recommended next directive

などを持たせています。

budget pause / auto-resume

usage limit に当たったときに、failed で終わらず paused_budget に落とし、再試行用 snapshot を保存するようにしました。

これによって、使い切ったら終わりではなく、回復後に再開を試す運用が可能になりました。

next-task discovery

remaining meaningful work が薄くなっても、Parent が base goal 文脈から次候補を掘れるようにしています。

カテゴリ例は以下です。

• refinement candidate
• hardening candidate
• UX candidate
• test/debt candidate
• integration candidate

ビューアー / 4窓表示

Parent / Research / Implement / Test を別窓で表示する仕組みも作っています。

• macOS window 起動
• tmux 起動
• 4窓自動配置
• role ごとの表示
• Status Board / Header / Logs 表示

メリット

実際に使ってみて、特によかったのはこのあたりです。

1. 完全自走にかなり近づける

人が毎回「次はこれをやって」と細かく采配しなくても、Parent がかなりのところまで自分で考えて進められます。

2. 大目標から着手できる

単一の小タスクではなく、たとえば

• UI 改善
• OCR 改善
• LocalVLM 導入

のような broad goal から始められるのは強いです。

3. 結果が残る

最終 report や worker summary が残るので、後から見返しやすいです。

4. 自走と安全性のバランスがある

完全に何でも勝手に進むのではなく、危険なときは止まるため、暴走しにくいです。

5. 役割が分かれていて考えやすい

Research / Implement / Test を分けているので、原因切り分けや改善方向が見えやすいです。

デメリット / 制約

1. トークン消費が大きい

複数 worker を動かし、report も厚く、レビューもするため、usage 消費はかなり重めです。

改善として、

• on-demand 起動
• execution unit の縮小

は入れていますが、それでも単体実行より高コストです。

一方で、この点は今後かなり改善余地があるとも考えています。
特に Implement や Test のように、比較的役割が明確で局所的な判断を繰り返すエージェントについては、ローカルLLMに置き換えることでトークン消費を下げられる可能性があります。

たとえば、

• Parent は高品質な判断と進行管理に集中する
• Research は必要に応じて外部モデルを使う
• Implement / Test はローカル寄りで回す

のような分担にすると、コストと自走性のバランスがかなり良くなるかもしれません。

2. 環境依存で詰まりやすい

たとえば、

• DerivedData
• PIFCache
• ModuleCache
• clang module session

など、ローカル build 環境が詰まると、自走が止まりやすいです。

3. Viewer が壊れやすい

見た目のための viewer は、ANSI 制御・改行・固定ヘッダーが難しく、何度も壊れました。

4. rule-based 解釈の限界

reviewer / navigator は便利ですが、まだ rule-based な部分があり、人間ほど柔らかく「これは実質完了」と判断できるわけではありません。

5. timeout の影響を受けやすい

Implement が環境エラーで詰まると、codex exec timed out などで Parent が慎重に止まりやすくなります。

今回特に難儀した点

1. 計画だけで終わる問題

最初は

• plan
• checklist
• 検証方針

ばかり出て、実コード変更まで進まないことが多かったです。

これは execution-first 化 でかなり改善しました。

2. interactive continue で最初の指示を繰り返す問題

base goal が強すぎて、新しい追加指示を入れても最初の goal に引っ張られることがありました。

これは、

• baseGoal
• latestInstruction
• activeDirective

の分離で改善しました。

3. viewer の Header / Logs 分離

たとえば、

• Header に Logs が食い込む
• 他 role の表示が混ざる
• Logs 見出しが固定されない

といった問題が出ました。

つまり、行数管理・カーソル制御・描画範囲固定 が難しかったです。

4. build / test よりも環境エラーで詰まる問題

実装そのものよりも、ローカル build 環境やキャッシュ状態に引っ張られて止まるケースがありました。

このフェーズでは、コードの問題より環境問題の比率が高かったです。

5. トークン上限と自動再開

usage limit に当たると作業が止まるので、budget pause / auto-resume を入れる必要がありました。

ただ、これも完全自動の期待値管理が難しく、実運用では「回復したら自動再開を試す」程度の soft 制御にしています。

今の完成度の評価

現時点の評価としては、codex-multi-agent-app は

実用 v1 は十分超えている

と考えてよいと思っています。

理由は以下です。

• complete / fail / pause / continue がある
• 自律分解できる
• broad goal を扱える
• report が残る
• next task を掘れる
• auto-continue がある
• budget pause / auto-resume がある
• interactive continue で継続できる

一方で、まだ改善余地が大きいのは以下です。

• viewer 安定化
• build 環境依存時の recovery
• rule-based からの賢い解釈
• 役割ごとのモデル最適化

今後の改善案

• viewer の完全安定化
• build/check 実行環境の分離
• reviewer / navigator の強化
• 自動再開の改善
• 実装と検証の分離強化
• 一部エージェントのローカルLLM化

特に最後の ローカルLLM化 はかなり試したいところです。

• Parent は外部モデル中心
• Implement / Test はローカルLLM中心

のようにできれば、トークン消費を抑えつつ、マルチエージェント構成の強みは残せるかもしれません。

まとめ

今回のオーケストレーターは、単なる「複数 AI を並べただけ」ではなく、かなり本格的に 完全自走で作り切る 方向へ寄せた構成になりました。

今回のポイントをまとめると、以下です。

今回のポイント

• broad goal を internal phase に分解する
• execution-first で実編集に進む
• Parent が結果を解釈する
• 次タスク候補を掘る
• 安全なら自動継続する
• usage limit で pause し、回復後の再開も試みる
• final report で進捗を残す
• 将来的には一部エージェントのローカルLLM化も狙える

まだ viewer や build 環境起因の難しさは残っていますが、今回の試行で少なくとも

人が細かく采配しなくても、かなりのところまで前に進めるオーケストレーター

には到達できたと思っています。

同じように、AI コーディングを単発補助ではなく、継続して自走する仕組みとして組みたい方の参考になればうれしいです。