codex-bridge

codex-bridge

クラッシュ、ウィンドウを閉じた後、再起動後も続けられる Claude Code 向け Codex ジョブ。Codex による画像生成も組み込まれています。 Windows を優先して構築された、依存関係のない MCP サーバーです。すべての呼び出しはジョブとしてディスクに保存されるため、Claude を終了したり、電源が失われたり、プロセスを強制終了したりしても、codex_resume で作業を再開できます。

役割：Claude Code は実装を担当します。Codex は計画と画像の作成を担当します。

_{この録画内のサーバー呼び出しは実際のものです（Codex の effort: low。アイドル時間はカットされています）。claude mcp add の行はスクリプトで挿入されています。録画の生データは docs/demo.cast です。asciinema play docs/demo.cast で再生できます。}

クイックスタート

Node.js 20 以降と、インストールしてログイン済みの Codex CLI が必要です。

claude mcp add codex-bridge -- npx -y @xallindrome-labs/codex-bridge

Claude Code を再起動し、たとえば 「レート制限を追加する計画を Codex に立ててもらい、バックグラウンドで進めながら作業を続けて」 と依頼します。Claude は background: true を指定して codex_plan を呼び出し、後で回答を取得します。

その他の MCP クライアントの場合は、stdio サーバーとして npx -y @xallindrome-labs/codex-bridge を実行してください。

プラットフォームに関する注意： 実際の Codex ジョブを実行した Windows 11 上で開発・テストされています。CI では、Linux、macOS、Windows（Node 20 および 22）でサーバーの起動、MCP の通信、npm の tarball からインストールした場合の動作を確認します。また Linux と macOS では、偽の codex を使用して、ジョブが実行・完了し、サーバーを強制終了しても保持されることを確認します。CI には実際の Codex CLI がないため、macOS と Linux での実際の Codex ジョブは未テストです。報告や修正を歓迎します。

ツール	機能	サンドボックス	デフォルトのモデル／労力
codex_plan	Codex が実装計画、設計レビュー、セカンドオピニオンを作成します。cwd 内のプロジェクトを調査します。	read-only（常時）	Codex の設定におけるデフォルト
codex_image	Codex が画像を生成または編集します。ブリッジは、生成されるたびに各画像を output_dir にコピーします。	read-only（常時）	gpt-6-luna / high
codex_result	ジョブの結果または進捗を取得します（wait_seconds は最大 240）。または最近のジョブを一覧表示します。
codex_resume	中断、タイムアウト、失敗したジョブを、停止したところから再開します。
codex_cancel	実行中のジョブを停止します。

codex_plan と codex_image は次の項目を受け付けます。

• effort：low、medium、high、xhigh、max、ultra（Luna が対応するのは max までです）。
• model：この呼び出しでデフォルトのモデルを上書きします。
• background: true：すぐに job_id を返すため、Claude は作業を続けられます。
• session_id：以前の Codex スレッドを続行します。たとえば「アイコンをもっと暗くして」などです。

codex_image は、生成する画像の枚数を指定する count も受け付けます。複数枚を生成する場合に設定してください。これにより k/count 形式の進捗表示と、不足している画像だけを正確に生成する再開処理が有効になります。

比較

OpenAI の codex-plugin-cc は、Claude Code から Codex を使う公式の方法で、得意分野をうまくこなします。レビューと復旧のためのスラッシュコマンドです。一方、codex-bridge は MCP サーバーで、異なる点に重点を置いています。ジョブが失われないことと、画像です。

プラグインの課題トラッカーには、ジョブが失われることに関する未解決の課題がいくつかあり、codex-bridge はそれぞれの問題を避けるように設計されています。以下は設計を調べてまとめたもので、直接比較テストに基づくものではありません。

codex-plugin-cc で報告されている問題	codex-bridge での対処方法
ワーカーが停止した後、バックグラウンドジョブがいつまでも「running」と表示される（#704、#699）	ディスク上のファイルに加え、ハートビートとプロセスチェックに基づいてステータスを判断します。ランナーが停止すると interrupted と表示され、「running」のままになることはありません。codex_resume で続行できます。
Windows で cancel が何も通知せず失敗する（#708）	キャンセル時にマーカーファイルを書き込みます。Codex プロセスを所有するランナーは約 2 秒以内にそれを検知し、間にシェルを挟まず taskkill.exe を直接呼び出してプロセスツリーを停止します。
Windows のブローカープロセスが残存する（#718、#782）	共有ブローカーはありません。各試行は Codex の終了とともに終了する単一のランナープロセスで実行されます。
1 つのセッションを終了すると、ほかのセッションのジョブも終了する（#671）	ランナーは Claude のプロセスツリーの外部（Windows では WMI 経由）で起動するため、セッションを閉じても終了しません。

このプラグインにあって codex-bridge にないものは、スラッシュコマンドと、レビューゲートおよび復旧のワークフローです。また、codex-bridge はより新しく、ユーザー数もはるかに少ないです。プラグインがうまく動作しているなら、そのままお使いください。ジョブを失ったことがある場合や、クラッシュ後も残る画像を Codex に生成させたい場合は、こちらをお試しください。

再起動後もジョブが残る

バックグラウンドで実行されない呼び出しも含め、すべての呼び出しが ~/.codex-bridge/jobs/<job_id>/ に保存されるジョブです。

• **Claude が終了またはクラッシュした場合：**ジョブは実行を続けます。server.mjs は WMI（Win32_Process.Create）を通じて runner.mjs を起動するため、ジョブは Claude Code のプロセスツリーに属しません。Claude を閉じてもジョブは終了せず、後から起動した Claude セッションで codex_result を使って取得できます。
• ジョブ自体が停止した場合（再起動、停電、Codex のクラッシュ、プロセスの強制終了）：ジョブは interrupted とマークされます。次の Claude セッションの開始時に、そのことが通知されます。codex_resume で続行できます。
  1. 中断の直前に生成された画像があれば、まずコピーします。
  2. 同じ Codex スレッドを再開します。「N 件はすでに完了しているので、残りだけを生成してください。」
  3. Codex スレッドがまだ開始されていなければ、元のリクエストを再実行します。

画像の収集方法

Codex が画像ファイルを書き出すことはありません。Codex の画像ツールは、生成したすべての画像を ~/.codex/generated_images/<thread>/ に保存します。ランナーは 2 秒ごとにそのフォルダーを確認し、新しい画像を作成された順に output_dir へ <filename>.png、<filename>-2.png などの名前でコピーします。ジョブフォルダー内の copied.json にコピー済みのファイルを記録するため、試行をまたいで同じ画像が二重にコピーされることはありません。

これにより、次の 3 つのメリットがあります。

• 画像ジョブは読み取り専用のサンドボックスで実行されます。
• クラッシュで失われるのは、生成中の 1 枚までです。
• 再開時に完了数を正確に把握できます。

また、実際に起きていた問題も避けられます。Luna が自分でファイルを保存できる状態だったとき、何十ものシェルコマンドを使って、画像を base64 として何度も入力し直していました。時間がかかり、保存されたファイルも元の画像とは一致しなくなっていました。

• **Codex が停止する場合：**ランナーは出力がない状態が 10 分続くと実行を停止します。ジョブは timed_out とマークされ、再開できます。

各試行では、それぞれ独自の prompt.txt、events.jsonl（Codex のイベントストリーム）、stderr.txt、ハートビート、result.json が保持されます。完了したジョブは 14 日後に削除されます。

仕組み

各試行では、プロンプトを標準入力で渡して codex exec --json（または codex exec resume <thread>）を実行します。シェルは介しません。

すべての呼び出しは読み取り専用で実行されます。新しいセッションでは -s read-only と -c sandbox_mode="read-only" を渡し、再開したセッションでは -c sandbox_mode="read-only" を渡します（codex exec resume は -s を受け取りません）。Codex の設定で既定値が danger-full-access になっていても、その既定値がブリッジの呼び出しに適用されることはありません。plan のスモークテストでは、再開したセッションから書き込みを試みると失敗することを確認します。

ファイル	役割
server.mjs	MCP サーバーです。ジョブを作成し、ランナーを起動し、ディスク上のファイルからジョブのステータスを判断して、再開とキャンセルを処理します。
runner.mjs	1 回の試行を実行します。Codex を起動し、ハートビートを記録し、停止またはキャンセルを監視し、画像を収集して result.json に書き込みます。
lib.mjs	共通ヘルパーです。Codex バイナリの検索、引数の構築、イベントの解析、画像の処理を行います。

インストール方法

# for all your projects
claude mcp add -s user codex-bridge -- npx -y @xallindrome-labs/codex-bridge

# or from a local checkout
claude mcp add codex-bridge -- node /path/to/codex-bridge/server.mjs

claude mcp remove codex-bridge で削除できます（インストール時にその方法を使った場合は -s user を追加してください）。

設定（環境変数）

変数	既定値
CODEX_BIN	自動検出されます。現在 ~/.codex/plugins/.plugin-appserver/codex.exe にある codex-code-mode-host.exe と同じ場所の codex.exe が優先されます。
CODEX_BRIDGE_HOME	~/.codex-bridge
CODEX_BRIDGE_IDLE_TIMEOUT_MS	600000（Codex からの出力がない状態が 10 分続くと実行を停止します）
CODEX_BRIDGE_PLAN_MODEL / CODEX_BRIDGE_PLAN_EFFORT	Codex 設定の既定値
CODEX_BRIDGE_IMAGE_MODEL / CODEX_BRIDGE_IMAGE_EFFORT	gpt-6-luna / high

テスト

node smoke-test.mjs <scratch-dir> [plan|image|jobs|durable|all]

スモークテストは、MCP クライアントのように標準入出力経由でサーバーを操作するもので、ログイン済みの Codex CLI が必要です。Codex の利用枠を少し消費します。durable のテストでは taskkill を使用するため、現時点では Windows 専用です。

• plan：プランを実行した後、再開したセッションから書き込みを試みます。これは失敗する必要があります。
• image：画像を 1 枚生成します。
• jobs：バックグラウンドジョブ、キャンセル、effort のチェックをテストします。
• durable：
  1. ジョブの実行中にサーバーを強制終了し、新しいサーバーが結果を収集することを確認します。
  2. 画像のバッチを途中で強制終了し、新しいサーバーが中断されたと報告すること、および codex_resume で完了できることを確認します。

速度

各呼び出しには約 4～5 秒の固定コストがかかり、設定を変えてもほとんど変わりません。残りの時間は Codex の思考と生成にかかり、数秒から数分です。待ち時間を減らすには、background: true を使用し、簡単な質問では低い effort を指定し、Codex がプロジェクトを読む量を減らせるよう、関連するコードを context に含めてください。

注意事項

• Codex 独自のログインと利用枠を使用するため、別途 API キーは不要です。Claude を閉じた後もジョブが実行中の場合、完了するまでその利用枠を使い続けます。
• ブリッジの呼び出しはヘッドレスで実行されるため、Codex Desktop のサイドバーに会話として表示されません。
• プロンプトに秘密情報を含めないでください。プロンプトは OpenAI に送信されます。

問題の報告と貢献

バグ報告やアイデアは、イシュートラッカーで歓迎します。プルリクエストも歓迎しますが、レビューには時間がかかります。CONTRIBUTING.mdをご覧ください。セキュリティ上の問題は、SECURITY.mdに記載の方法で非公開でご報告ください。

ライセンス

MIT

---

Xallindromeが開発：中小企業向けに自動化と AI ワークフローを構築しています。貴社でもこのようなものをご希望の場合は、診断を予約してください。