Codex Native Bridge

English | 简体中文

An MCP server that lets Claude Code delegate work to your local Codex CLI — durable background tasks, GPT-5.6 reasoning profiles, thread resumption, and Codex's native image generation.

It talks to codex app-server using your existing ChatGPT/Codex login. No API key required.

Unofficial project. Not affiliated with, endorsed by, or supported by OpenAI or Anthropic. "Codex" and "Claude" are trademarks of their respective owners.

Why this exists

Claude Code is good at understanding requirements, planning, and reviewing. Codex is good at executing bounded implementation work. This bridge lets Claude hand off a task, keep working, and read back a structured result — changed files, commands run, token usage, and verification output.

Compared to shelling out to codex exec, this bridge adds:

• Durable background jobs. Job state lives on disk, independent of the Claude session. Restart Claude and recover jobs by id.

• Pre-flight validation. The requested model and reasoning effort are checked against your account's live catalog before the turn starts, so you get a clear error instead of a mid-run HTTP 400.

• Real image generation. Image jobs fail loudly if Codex did not produce a native imageGeneration item, rather than silently returning a code-drawn PNG.

• Secret redaction. API keys, bearer tokens, and password/secret-shaped values are stripped from diffs, command output, and messages before they reach the caller.

• A sandbox that is closed by default. See Security.

Related MCP server: mcp-local-llm

Requirements

Verify Codex works on its own first:

codex --version
echo "reply OK" | codex exec --skip-git-repo-check

If that fails, fix it before installing the bridge — the bridge cannot work around a broken Codex setup. Note that model availability differs between the Codex desktop app and the standalone CLI; a model that works in the app may return 400 from the CLI.

Install

git clone https://github.com/PatrickStar-sketch/codex-native-bridge.git
cd codex-native-bridge
npm install
npm test

Register it with Claude Code as a user-level MCP server:

claude mcp add codex-native --scope user \
  --env CODEX_NATIVE_ALLOWED_ROOTS="$HOME/projects" \
  -- node /absolute/path/to/codex-native-bridge/src/index.mjs

Restart Claude Code, then ask it to run codex_native_health. A healthy server reports ok: true with your live model catalog.

The bridge reads its configuration once at startup. After changing any environment variable or updating the source, restart Claude Code.

Configuration

CODEX_NATIVE_ALLOWED_ROOTS has no default on purpose. An unconfigured server grants access to nothing, and codex_native_health tells you how to fix it. Point it at your project directories rather than at $HOME.

Tools

Reasoning profiles

balanced is used when no profile is given. high and above consume substantially more quota — a single review at that level can run into millions of tokens. Treat max and ultra as exceptional, not routine.

deep is accepted as a deprecated alias for high so that jobs recorded before the rename can still be resumed.

codex_native_reply inherits the prior job's model and effort unless you explicitly pass profile, model, or effort.

Image generation

codex_native_image invokes Codex's built-in image_gen tool and returns real bitmaps. Its image-specific parameters are:

• prompt: the generation or editing request.

• referenceImages: optional absolute paths to existing images used as edit targets or visual references. These are inputs to image_gen, not output locations.

• outputDir: optional absolute directory where the bridge collects the generated result.

Use it for illustrations, assets, covers, photorealistic scenes, textures, and mockups. Do not use it for flowcharts, architecture diagrams, data visualizations, charts, or UI prototypes — generated images render text poorly and cannot be edited afterwards. Build those with code or SVG instead.

When referenceImages is present, the worker prompt explicitly instructs Codex to pass those paths to image_gen as editing/reference inputs. If Codex cannot use every reference image, it must report the limitation instead of silently generating from the text alone.

If Codex finishes without producing a native image item, the job fails rather than returning a programmatically drawn substitute.

Security

Read this before enabling anything.

Sandboxes. Jobs default to workspace-write, limited to the job's working directory. read-only is available for review tasks. Image jobs get no extra write access: Codex leaves the generated file where its image tool put it, and the bridge collects it afterwards.

danger-full-access is gated twice. The operator must set CODEX_NATIVE_ALLOW_FULL_ACCESS=1 on the server, and the caller must pass dangerousConfirmed: true. A caller cannot opt itself in.

What danger-full-access actually means. The bridge runs Codex with approvalPolicy: "never" and automatically declines approval requests, because there is no interactive human on the MCP side. With full access enabled, that combination means Codex can read and write anywhere on the machine, unattended, for the duration of the job. The confirmation happens once, before anything runs; there is no checkpoint after that. Enable it only if you need it and understand the exposure.

Path containment. Every cwd, outputDir, and referenceImages path is resolved through realpath and checked against CODEX_NATIVE_ALLOWED_ROOTS. Reference images must already exist; not-yet-created output paths are checked against their nearest existing ancestor, so symlinks cannot be used to escape.

Prompt-level guardrails are not enforcement. Delegated tasks are instructed not to deploy, delete data, push, merge, or commit without explicit approval. That instruction is text the model can disregard. It is a convention, not a sandbox. Keep destructive operations behind human review.

Limitations

Everything below is a deliberate boundary, not a pending fix.

• Prompt-level guardrails are not enforcement. See Security.

• The job lock is advisory. It serialises this bridge's own writers. Anything else editing files under the state directory can still corrupt a record.

• Liveness uses PID checks. A recycled PID can briefly make a dead worker look alive. Job records still reach a terminal state via the turn timeout.

• Windows is untested. Paths and process-group signals are written for POSIX.

Development

npm test              # 20 tests, no network required
node --check src/*.mjs

Tests cover profile resolution, path containment, the closed-by-default security switches, subagent thread routing and cross-job isolation, and worker startup-failure recovery.

License

MIT — see LICENSE.