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.

Requirements

Node.js	≥ 20
Codex CLI	codex on your PATH, logged in
Account	A ChatGPT plan that includes Codex, or an OpenAI API key configured in Codex
OS	macOS and Linux. Windows is untested.

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

Variable	Default	Purpose
CODEX_NATIVE_ALLOWED_ROOTS	(empty)	Required. Absolute directories Codex may read and write, separated by : (; on Windows). Nothing outside these paths is reachable.
CODEX_NATIVE_ALLOW_FULL_ACCESS	(off)	Set to 1 to permit the danger-full-access sandbox. Leave unset unless you have read Security.
CODEX_NATIVE_CODEX_BIN	codex	Path to the Codex binary.
CODEX_NATIVE_STATE_DIR	~/.codex-native-bridge	Where job records, logs, and generated images are stored.

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

Tool	Purpose
codex_native_health	Bridge status, live model catalog, image capability, reasoning profiles
codex_native_models	Models and supported reasoning efforts for the current account
codex_native_start	Start a durable background task; returns a job id immediately
codex_native_status	Poll a job's status (wait ≥ 30s between polls)
codex_native_result	Full result: final message, file changes, commands, images, token usage
codex_native_reply	Continue a previous thread; inherits its model and effort by default
codex_native_jobs	List recent jobs — use this to recover after a Claude restart
codex_native_cancel	Cancel a running job and its process tree
codex_native_image	Generate a bitmap image with Codex's native image model
codex_native_prune	Delete finished job records, logs, and images past the retention window (maxAgeDays OR beyond keepJobs; run with dryRun first)

Reasoning profiles

Profile	Model	Effort	Use for
fast	GPT-5.6 Luna	low	Searches, small fixes, formatting, mechanical work
balanced	GPT-5.6 Terra	medium	Everyday implementation, tests, multi-file work
deep	GPT-5.6 Sol	high	Architecture, planning, difficult debugging
xhigh	GPT-5.6 Sol	xhigh	High-risk cross-module changes, critical review
max	GPT-5.6 Sol	max	Problems where xhigh was not enough
ultra	GPT-5.6 Sol	ultra	Large autonomous multi-agent work

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

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.

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.

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. Image jobs additionally receive their own output directory as a writable root, and nothing else. read-only is available for review tasks.

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 and outputDir is resolved through realpath and checked against CODEX_NATIVE_ALLOWED_ROOTS, including paths that do not exist yet, 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              # 18 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.