AgentBridge

ステータス: 移行中であり、この README は古い形を説明しています。

AgentBridge は Claude-Code-to-Codex/Antigravity ブリッジとして始まり、以下に記載されたすべての内容は今日も動作します。現在は、サポートされている任意の CLI をオーケストレーター、他の任意の CLI をワーカーにできるよう一般化しており、ルーティングはハードコードされたモデル名ではなくユーザーごとのプロファイルで駆動します。

今後の方向性については docs/architecture.md と docs/roles.md を参照してください。進行中: プロバイダーアダプター層（src/providers/）、ルーティングプロファイル（src/profile/）、agentbridge init セットアップフロー。Cursor アダプターは存在しますが未検証です。そのフラグはインストール済み CLI から読み取ったものではなく、事前知識から書かれたもので、その旨がファイルの先頭に明記されています。

移行が完了するまでは、以下のセクションを Codex と Antigravity のワーカーに関する正確な記述として扱い、docs を設計に関する正確な記述として扱ってください。

Chapter: Orchestrators

AgentBridge は /agentbridge … コマンド群をMCP プロンプトとして公開するため、prompts/list をサポートする MCP クライアントであれば、サーバー自体から同じコマンドを取得できます。ホストごとのコマンドファイルをインストールしたり同期したりする必要はありません。

これらのコマンドの背後にある考え方は doctrine/ にあり、モデル名は一切使用しません。ロール毎にルーティングし、.agentbridge/profile.json はロールを、ユーザーが実際にインストールしているものへマップします。

Claude Code が作業を外部ワーカーとしての Codex CLI と Antigravity CLI（agy) に委任できる、ローカルな小型 stdio MCP サーバーです。すでにログインしている CLI セッションを使用するため、API キーは不要です。

Claude がオーケストレーターであり続けます。AgentBridge は意図的に単純な配管機構です。Claude の構造化されたリクエストをワーカーのプロンプトに変換し、CLI を実行し、コンパクトな構造化結果を返すだけです。

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

Related MCP server: agent-intern

これは何でないか

クラウドサービスでも、Web UI でも、データベースでも、デーモンでも、ダッシュボードでも、ジョブキューでも、アカウントシステムでも、API キー管理でもありません。Claude Code が stdio 上で起動し、終了時に停止する 1 つの Node.js プロセスです。

動作の仕組み

1. Claude が codex_run または antigravity_run を、構造化されたリクエスト（goal、mode、model、effort、paths、contract、acceptance criteria…）とともに呼び出します。

2. AgentBridge は、それらのフィールドだけからワーカープロンプトを組み立てます。それ自体がモデルを実行することはありません — これは文字列の組み立てであって、推論ではありません。

3. 書き込みスコープを確保し、git 作業ツリーをスナップショットし、引数の配列（shell: false）で CLI を起動します。

4. CLI の機械可読出力を解析し、ワーカーの最終結果（内部の推論は取り出さない）を抜き出し、git を diff して実際に何が変更されたかを判断し、コンパクトな JSON 結果を返します。

MCP 呼び出し 1 回 = ワーカーの試行1 回。AgentBridge は一切リトライしません。もう 1 回試行する価値があるかどうかは Claude の決定です。

Requirements

AgentBridge は、Codex や Antigravity の認証情報を読み取ったり、コピーしたり、エクスポートしたり、変更したりしません。ログインした人間が行うのとまったく同じ方法で CLI を起動するだけです。

インストールとビルド

npm install

npm run build

npm test

テストスイートはすべてモックプロセスを使用するため、通常の npm test でモデルクォータは消費しません。

Claude Code への登録

一度ユーザースコープで登録すれば、すべてのプロジェクトで使用できます。

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

ターミナルから確認:

claude mcp list

claude mcp get agentbridge

次に、Claude Code の中から /mcp を実行して確認します。agentbridge が接続済みとして表示され、codex_run・antigravity_run・bridge_status の 3 つのツールが見えるはずです。完全なヘルスレポートを得るには Claude に bridge_status を呼び出してもらいます。

AgentBridge を再ビルドした場合は、Claude Code を再起動するか /mcp からサーバーに再接続して、新しい dist/ を読み込んでください。

プロジェクトディレクトリ

ワーカーは単一のプロジェクトディレクトリ内で実行され、そこにスコープされます。解決順は以下です。

1. AGENTBRIDGE_PROJECT_DIR、その次にレガシーの CLAUDE_PROJECT_DIR（Claude Code がエクスポートするもの）。

2. MCP クライアントが通知する最初の file:// ルート。

3. サーバプロセスの作業ディレクトリ。

bridge_status は、どれが使用されたかを報告します。

Tools

codex_run

モデル。 3 つのスラッグが利用でき、それぞれが CLI にそのまま渡されます。

エフォートマッピング（オーケストレーターのラベル → Codex の model_reasoning_effort）:

マッピングは全体にわたって完全かつ決定的です。Codex の ultra ティアは意図的に公開していません。一部のモデルだけが備えているためで、3 つのうち 2 つでしか機能してくれない 6 番目のラベルを加えると、ルーティングがモデル依存になるからです。

可用性. 起動前に AgentBridge は、リクエストされたモデルと effort を Codex CLI 自身のモデルカタログ（CODEX_HOME の models_cache.json）と照合します——ただのファイル読み取りであり、推論ではありませ。

• モデルもある・effort もある → ジョブは実行される

• モデルあり・effort なし → invalid_effort を返し、details.supported_efforts を添える

• モデルなし → requested_model_unavailable を返し、details.available_models を添える

• 読み取れるカタログなし → 可用性は unverified であるという警告付きで、ジョブはとにかく実行される

何かが他の何かに置き換えられることは一切ありません。実現できないルーターングの決定は、静かに弱いモデルに落ちるのではなく、1 ステップで再ルーティングできる充分なメタデータを含む構造的なエラーとして返されます。

呼び出しは次のように構築されます:

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

プロンプトは stdin でストリームされます。モデル・effort・sandbox は毎回渡されるため、~/.codex/config.toml に何が設定されていても、実行がそれを引き継ぐことはありません。

analyze と review は Codex の実際の read-only サンドボックスを使用します——書込みは単に控えさせるだけではなく、実際に妨害します。

antigravity_run

同じスキーマで、以下が異なります。

論理名は実行時に現行の agy models 一覧と照合して解決されます:

Antigravity は推論レベルを model id に組み込んでいるため、model + effort は単一の id に解決され、別の --effort フラグは送られません。この 2 つが矛盾することはありません。 extra high と max は、より軽いティアをひっそりと実行する代わりに invalid_effort を返します。

Antigravity は意図的に安価な Flash ティアに制限されています。agy が提供する Claude モデルはルーティング可能なラベルとして公開していません。Claude クラスの推測には、実際のサンドボックスと（Codex では）選択可能な effort を備えた Claude Code 自身か Codex を使ってください。

ラベルは、同じモデルのIDの順序付き候補リストを持ちます。インストール済みCLIがそれらのどれも提供していない場合、呼び出しはrequested_model_unavailableと、利用可能なモデルの完全なリストを添えて失敗します。別のモデルに黙ってフォールバックすることは決してありません。 解決されたIDは毎回の実行でwarningsにエコーバックされます。

構築される呼び出しは次のとおりです:

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commandsはimplementの実行時のみ追加されます。スラッシュコマンドの展開が無効になっている場合はCLIが--mode planを無視するため、両方を送信すると、Antigravityが提供する唯一の書き込みなし動作が黙って破棄されてしまいます。

bridge_status

引数なし。モデルの推論は一切消費しません。--versionプローブ、agy models、1回のgit rev-parse、Codex CLI のモデルキャッシュの読み取りだけを実行します。

返す内容:

• AgentBridgeのバージョン、プロジェクトディレクトリ（どのように解決されたかを含む）、node/プラットフォーム

• git_verification — gitベースのfiles_changed / scope_violationsがここで機能するかどうか。機能しない場合、空のscope_violationsは問題なしという意味ではなく沈黙であり、warningsにその旨が示されます

• codex.installed / version / path / auth

• codex.model_status — モデルごと: available | unavailable | unverified、そのモデルに指定できるeffortラベル、CLIの生の推論レベル

• codex.model_source — 可用性の情報元と、その情報の新しさ

• antigravity.installed / version / path / auth、検出されたモデル、各論理ラベルとティアの解決結果、同じ3状態の形のmodel_status

• antigravity.unsupported_efforts — Flashが受け取れないオーケストレーターラベル

• アクティブなジョブとその書き込みスコープ

• warnings

可用性が推測されることはありません。インストール済みのCLIが軽量な証明を提供しない場合は、どちらかに断言するのではなく、unverifiedになります。

認証情報や環境変数を返すことは決してありません。

結果形式

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effortは両プロバイダーに存在します — Codexの推論レベル、またはモデルidにエンコードされた Flash tier です。files_changedとscope_violationsは、ワーカーの供述ではなく、AgentBridgeがgitから算出します。内部推論は破棄されます。summaryは16,000文字に制限され、先頭と末尾は保持され、カットされた場合はsummary_truncated: trueが設定されます。

エラー

失敗時も同じエンベロープ構造で、status: "failed"、errorカテゴリ、的確なアクションに導くmessage、そして利用可能な場合にはexit_code、stderr_tail、detailsオブジェクトを返します。

Claudeがワーカーを呼び出す例

安くて速い分析:

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

本格的な実装、最大の推論、厳密なスコープ:

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

スコープが重ならない2つのCodexワーカー — これらは同時に実行されます:

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

安価な機械的作業(アプリケーションの定型処理など)には Antigravity:

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

並行性とファイルスコープ

• implementは**allowed_pathsを必要とします**。パスはプロジェクトルートを基準に正規化され、ルートを脱出するもの（..、他のドライブ、他所への絶対パス）はプロセス開始前に拒否されます。

• アクティブなimplementジョブは、その書き込みスコープをメモリに保持します。アクティブなジョブとスコープが重なる新しいジョブは、ユーザーに警告されます。 Wait—"はscope_conflictで拒否されます。重なり合わないスコープは並行実行されます — 無関係な作業が直列化されることはありません。

• analyzeとreviewは何も予約しません。ブロックすることもされもせず、一切ブロックされません。

V1の制限: 検出はするが分離はしない

ファイルスコープの保護は違反を検出して報告します。ワーカーをそれぞれのツリーにサンドボックス化するものではありません。Codexのimplementワーカーは、プロジェクト全体にworkspace-writeで実行されるため、allowed_pathsの外に書き込むこともできます — AgentBridgeはそのようなすべてのファイルをscope_violationsに列挙し、successからのステータスを引き下げ、そのことをはっきりと伝えます。

何も自動的にリバートされません。 ワーカーが開始する前にすでに変更されていたファイルをリバートすると、あなた（またはClaude）が既に行った作業が壊れてしまいます。検出と誠実な報告がV1の契約であり、git-worktree の分離は意図的にスコープ外です。

attribution は事前状態に対して細心の注意を払います。実行前に既に dirty で、その後もバイト単位で同一のファイルは、ワーカーのせいにされません。尐ビブラウド比較は porcelain ステータスとコンテンツハッシュで行い、コミットされたファイルは HEAD 移動 diff で拾われます。

セキュリティ

• プロセスは**引数式配列とshell: false**で起動します — 補完されたコマンド文字列を決して使わしません。引数中のシェルメタ文字はリテラルのままです。

• Windowsの.cmd/.ps1ランチャー（Nodeがシェルなしでの起動を拒否するもの）は、実際のNodeエントリスクリプトに解決され、node <script>として実行されるため、shell: trueは不要です。

• プロンプトはCodexにstdin経由で渡されます。大きすぎるAntigravityプロンプトは一時ファイルに書いてパスで参照されます。どちらもWindowsの32,767文字コマンドライン制限に達しません。

• testsはワーカーのためのコンテキストです。AgentBridgeがそれを実行することはなく、AgentBridgeが実行するコマンドになるようなMCP引数はどこにもありません。

• プロジェクトルートを出るパストラバーサルは拒否されます。

• タイムアウトはプロセスツリー全体を終了します: Windowsではtaskkill /T /F、POSIXでは3秒の猶予を設けてからプロセスグループへのSIGTERMがSIGKILLへエスカレーションします。このエスカレーションは意図的に直接の子プロセスの終了を超えて続行されます。そのタイミングこそ、子孫がまだ実行中かもしれないからです。これはベストエフォート — Node は Windows Job Object を公開しないため、taskkill自体が起動できない場合は直接の子だけにしか到達できません。

• 出力バッファは制限されており（ストリームあたり8 MB）、UTF-8は再構成後にのみデコードされるため、マルチバイト文字が分割されることはありません。

• ログにはジョブのメタデータのみが記録されます。トークンや環境変数は記録されず、プロンプトと出力はAGENTBRIDGE_DEBUG=1の場合のみ。

• AgentBridge が守ってくれないもの: ワーカーは実際のコーディングエージェントで、あなたの権限で実行されます。implementモードでは独自のツールを通じてリポジトリコマンドを実行できます。allowed_pathsはそれに合わせて範囲を設定してください。

検証

AgentBridgeはワーカーが終了した後、サンドボックスの外でプロジェクト自身のチェックを自分で実行し、実際の出力を verification に返します:

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands — モードにかかわらず、この通りのコマンドを実行します。

• implementモードの場合は省略 — AgentBridgeははpackage.jsonを読んで、typecheckとtestのスクリプトが存在すれば実行します。build、dev、start は自発的には実行せず、明示的に依頼してください。

• skip_verification: true — 何も実行しないで、ワーカーの報告をそのまま信頼します。

コマンドはシェルなしで実行されるため、引用符で囲まれていない|、&&、;、>、バッククォートは半端に実行されるのではなく拒否されます。チェックの失敗はerror: "verification_failed"としてセットされ、successはpartialに下がるため、テスト成功を主張するワーカーがテスト自体より上に行くことはありません。

tests_or_checks_runとtest_resultsは、検証が行われたときにAgentBridgeが実際に実行したものを報告します。検証が行われなかった場合のみワーカーの申告にフォールバックします。

コマンドはリポジトリ由来なので、ブリーフが間違ったランナーを指し示してもAgentBridgeがそのランナーを実行することはありません。テストスクリプトがnode --import tsx --testのリポジトリは、ブリーフが何と言おうと、そのコマンドで検査されます。

環境変数

AGENTBRIDGE_CODEX_SANDBOX=auto は、analyze/review には read-only、implement には workspace-write を使います — 実装モードでは — しかし Windows では、サンドボックス化された Codex はサブプロセス出力を取得できず（パイプ stdio 上で spawn EPERM）、npm スクリプト、テストランナー、バンドラーはすべてこれを行うため、読み取りと編集はできますが、テストランナー、型チェッカー、ビルドを実行することはできません。これは設定で変更できないCodexの制限であり、implementジョブはワンショットのプローブで確認できた場合にdanger-full-accessにフォールバックし、" warnings, その旨が告知されます。Analyze と review は強制された read-only の境界を維持します。Windowsで壊れたサンドボックスヘルパー（helper_unknown_error: apply deny-read ACLs）で実行に失敗した場合、AgentBridgeはそのジョブを一度だけdanger-full-accessで再試行し、残りのプロセス中はその決定を覚えておき、境界が強化されなかったことを各結果に警告として付与します。それ以外の要因でフォールバックがトリガされることはなく、AgentBridgeを再起動すれば実際のサンドボックスを再試行します — したがって固定されたCodexリリースは自動的に復元します。macOSとLinuxはプローブ、リトライ、フォールバックを一切行いません。

ログはジョブごとにJSONの1行として保存されます。タイムスタンプ、ジョブID、プロバイダー、モデル、effort、モード、プロジェクト、実行時間、終了コード、エラーカテゴリ。

トラブルシューティング

executable_not_found — CLIが Claude Code が子プロセスに PATH を渡したものに含まれていません。 同じシェルで codex --version / --physical -- を確認するか、AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN を設定してください。

authentication_required — CLIのセッションが期限切れです。ターミナルで codex login (Codex) または agy でサインインし直してください。AgentBridgeには意図的に、認証情報に触れないため、これを修復する機能はありません。

requested_model_unavailable — モデルリストが変更されたか、インストール済みのCLIがそのモデルを提供していない可能性があります。実際に提供されているモデルを確認するには bridge_status（または agy models）を実行してください。エラーの details にはすでにその情報が含まれています。AgentBridge は、異なるモデルを静かに実行するのではなく、意図的にここで失敗します。プロバイダーがモデルIDを変更した場合は、src/models/antigravity.ts のそのラベルの候補リスト（または src/models/codex.ts の CODEX_MODELS）に新しいIDを追加して、再ビルドしてください。

output_parse_failed — CLI が機械可読な出力形式を変更した可能性があります。結果内の details.stdout_head を確認し、parseCodexEvents / parseAgyOutput と比較してください。

CLI アップデート後 — テストを再実行し、次にライブスモークチェックを実行してください:

SMOKE_LIVE=1 node scripts/smoke.mjs

これは実際の MCP セッションを駆動し、各ワーカーの最も安価な構成を実行します。SMOKE_LIVE=1 がない場合、ハンドシェイクと bridge_status のみを実行し、何も消費しません。

files_changed が常に空 — プロジェクトディレクトリが git ワーキングツリー内にありません。結果内の警告にその旨が示されています。変更検証には git が必要です。

/mcp の下に何も表示されない — 登録されたパスが dist/index.js（src/ ではなくビルド済み）を指していることを確認し、再ビルド後に Claude Code を再起動してください。

レイアウト

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check