Codex Native Bridge
Codex Native Bridge lets Claude Code delegate durable background tasks and native image generation to your local Codex CLI, with model profiles, thread resumption, and job management — no API key required.
Health & model inspection: Check server status, live model catalog, reasoning profiles, and image generation capability.
Start durable jobs: Launch background coding tasks with configurable profiles, sandbox levels, and timeouts.
Monitor & retrieve results: Poll job status, get complete outputs including file changes, commands, and token usage.
Resume threads: Continue a previous job with optional model/effort overrides.
Manage jobs: List recent jobs, cancel running jobs, and prune old records.
Generate native images: Create or edit bitmap images with prompts and optional references.
Security & validation: Sandbox enforcement (default workspace-write, opt-in full access), pre-flight model/plan checks, secret redaction from outputs, and path containment within allowed roots.
Durability: Job state persists across Claude restarts, stored on disk.
Integrates with Codex CLI (OpenAI's agentic coding tool) using existing ChatGPT/Codex login without API key, enabling image generation, thread resumption, and model-aware task execution.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Native Bridgestart a background task to refactor utils"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex Native Bridge
English | 简体中文
A local collaboration bridge that lets Claude Code delegate to other coding agents on your machine, and run a real human + agents project room in the browser. It provides durable jobs, directed agent handoffs, per-provider reasoning profiles, session resumption, and native image generation.
Five agent providers are registered: Codex CLI, Claude CLI, OpenCode, Grok Build, and CodeBuddy Code (bundled with WorkBuddy). Each keeps its own model catalog, effort tiers, and sandbox capabilities; the bridge only exposes what a provider was verified to actually accept.
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 and Codex are treated as two equal but different project agents. Either can analyze, challenge, design, complete bounded project-file work, delegate to the other, and review the other's result. The bridge preserves the evidence around each handoff — 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.
A real three-party project room. Talk to Claude and Codex in a local browser. Whole-room messages invite both models to contribute; directed
@namementions assign ownership, and delegated results return to the delegator for peer review.A recoverable room daemon. Agent cursors, pending triggers, Claude sessions, Codex threads, and job outcomes are durable. Messages written while the daemon is down are processed after restart.
Visible failures. Quota exhaustion, CLI startup failures, timeouts, and task errors appear in the room and status panel instead of silently degrading.
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
imageGenerationitem, 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.Working-directory overlap protection. Writable jobs cannot accidentally run at the same time in the same project tree.
Explicit permission modes. Non-room jobs stay scoped by default; project rooms can intentionally use desktop-capability mode. See Security.
Related MCP server: Clanker
Requirements
Node.js | ≥ 20 |
Codex CLI |
|
Claude CLI |
|
Other agents | Optional. |
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-checkIf 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
npm linknpm link exposes codex-native-room from this checkout; later source updates are picked up without another copy step.
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.mjsRestart 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 |
| (empty) | Required. Absolute directories accepted as bridge job inputs, separated by |
| (off) | Gates an explicitly requested |
| (off) | Legacy compatibility flag for old room clients. New browser requests freeze their own permission choice; see Security. |
|
| Path to the Codex binary. |
|
| Path to the Claude Code binary; only needed by the three-party project room. |
|
| Where job records, logs, shared rooms, and generated images are stored. |
|
| Default polling interval, in milliseconds, for the room CLI. |
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 |
| Bridge status, live model catalog, image capability, reasoning profiles |
| Models and supported reasoning efforts for the current account |
| Start a durable background task; returns a job id immediately |
| Poll a job's status (wait ≥ 30s between polls) |
| Full result: final message, file changes, commands, images, token usage |
| Continue a previous thread; inherits its model and effort by default |
| List recent jobs — use this to recover after a Claude restart |
| Cancel a running job and its process tree |
| Generate or edit a bitmap with Codex's native image model, optionally using reference images |
| Delete finished job records, logs, and images past the retention window ( |
| Append a timestamped human, Claude, or Codex message to an isolated room |
| Read entries after one participant's cursor, with optional non-advancing |
Grok Build and CodeBuddy Code get their own symmetric groups rather than a
provider argument on the tools above, so an existing Codex call cannot become a
different agent by one wrong field:
Tool | Purpose |
| Grok install, auth mode, account model catalog, effort tiers |
| Durable Grok jobs and session resumption |
| Real bitmaps and video through Grok's native visual tools; a turn producing no file fails rather than describing one |
| CodeBuddy binary, account model catalog, profiles, sandbox caveats |
| Durable CodeBuddy jobs and session resumption |
Shared conversation rooms
Rooms preserve project dialogue, agent state, and task handoffs. The recommended path runs the browser plus real Claude and Codex collaborators under one daemon.
Command | Behavior |
| Create a collaborative room; both agents receive whole-room messages and may delegate or peer-review work |
| Start the complete room in the background and return its local URL; repeated starts do not create a second instance |
| Stop an idle room; refuses while a job is active |
| Cancel the active job, then stop the room |
| Show daemon, agent, current-job, and recent-error state |
| Run the complete room in the foreground for debugging |
| Print the latest 20 complete entries, follow new entries, and append every stdin line as an |
| Follow entries written after startup without reading stdin |
| Append one human message, print it in transcript form, and exit |
| Backward-compatible low-level component commands; new rooms normally do not need them |
When running from a source checkout, replace codex-native-room with node src/room-cli.mjs. The CLI and MCP server must share CODEX_NATIVE_STATE_DIR. The browser binds only to 127.0.0.1; do not port-forward or expose it publicly.
Recommended: one room per project
node src/room-cli.mjs init my-project \
--project /absolute/project/path \
--title "My project room" \
--port 47850
node src/room-cli.mjs start my-projectOpen the exact tokenized URL returned by start. That page is the same-origin UI gateway for every room owned by the same local human: selecting another project group replaces the room data in place without a cross-port page reload, while each room keeps its own daemon and Agent lifecycle. Project groups are listed in the fixed left sidebar and the active three-party conversation fills the remaining space. Use + to create another local project group. On mobile, the Project rooms button opens the left drawer.
The composer defaults to
Everyone. Both Agents receive the message, the first responder is not fixed, and either may explicitly hand off, challenge, and review. Select Claude or Codex only when a single direct Agent is wanted.Send to
Claudeto give Claude sole initial ownership. The default scoped project mode disables shell, Chrome, and native writes, leaving read/research tools plus the project-confined audited writer. SetCODEX_NATIVE_ROOM_DESKTOP_MODE=1to load the full Claude Code desktop tool surface. High-risk actions still require user confirmation.Send to
Codexto give Codex sole initial ownership for implementation, commands, tests, or native tools.Open
Group settingsto choose and save Claude/Codex models and effort levels. The UI keeps provider-native effort names only where the selected executable actually supports them. Claude Desktop may displayUltra, but project rooms invoke the Claude Code CLI, so its currentclaude --helpis authoritative (this machine currently tops out atmax). Codex Sol/Terra currently exposeUltra. Settings apply directly to the next job; an already-running job is not switched mid-turn, and smart scheduling no longer overrides the saved choice.The room header and settings drawer show provider-reported Token usage for the rolling hour and current local day, separated by Agent. Codex aggregation uses the current turn's
lastusage rather than summing thread-cumulative totals; provider cost appears only when the provider reports it. This is usage telemetry, not subscription quota remaining.The expanded current-task card keeps its execution-record scroll position across live refreshes. Long-running Claude jobs add an elapsed-time heartbeat so the record no longer appears frozen while the CLI is still working.
Use the paperclip, drag files onto the composer, or paste clipboard images/files directly. They are copied into the project-local, ignored
.room-uploads/directory. Sent project paths become guarded preview/download links; supported images render as inline thumbnails.Each human and Agent message has a compact copy action that copies only the original message text. The current-task strip also offers a guarded stop action: after confirmation it terminates the worker process group, records a canceled terminal result, and rebuilds the Agent context from the durable room summary on the next turn instead of resuming a partial native session.
New conversationin Group settings is available only while the room is idle. It clears both native provider sessions and creates a durable boundary: old ordinary chat remains visible but is excluded from later prompts, while the project summary and active decisions remain. Obsolete decisions can be revoked by source message without rewriting the append-only audit log; revoked decisions are no longer injected.Messages sent while a targeted Agent is already working are durably queued for its next job; they do not mutate the running provider turn. The composer states that boundary explicitly. Unsent drafts survive room switches. The sidebar distinguishes executing/completed/failed/idle from mere daemon availability, counts unread Agent replies, and the destination room opens at the first unread reply.
Either agent can hand off by starting a new line with
@claudeor@codex. The delegating agent becomes the automatic reviewer when the delegated job completes, so review works in both directions.
Free collaboration contract
Smart scheduling, structured pre-judgment, automatic model selection, and the former quality-first controls are disabled. Claude and Codex use their independently saved models and effort levels.
The default Everyone turn wakes Claude and Codex together. Whichever Agent responds first may plan, implement, question, or report; execution order and finalizer are not fixed. Start a new line with @claude or @codex when the peer should continue. After a delegated job completes, the delegator becomes the automatic reviewer. Without an explicit handoff, an Agent may answer and finish its own turn normally; neither Agent is forced to produce a minimum number of replies. Legacy collaboration does not emit a structured machine footer and does not use the managed terminal-state, evidence-gated extension, or six-reply convergence protocol.
One room runs one job at a time, preventing simultaneous writes while preserving bounded evidence-driven review.
Claude uses its own Claude Code login and quota. Codex uses its own ChatGPT/Codex login and quota. A provider failure is shown explicitly; the room never silently swaps providers.
Common lifecycle commands:
node src/room-cli.mjs status my-project
node src/room-cli.mjs stop my-project
# To stop immediately while an agent is active:
node src/room-cli.mjs stop my-project --cancel-active
node src/room-cli.mjs start my-projectChange model and effort in Group settings. To tune sandbox, role, quota, or round limits, stop the daemon, edit $CODEX_NATIVE_STATE_DIR/rooms/<roomId>/room.json, and restart the room.
Low-level room and MCP workflow
The original component-level workflow remains available:
codex-native-room serve release-review --as zxhttp://127.0.0.1:43127/?token=<generated-local-token>Open the exact returned URL locally. The page shows the complete transcript with separate colors for human, Claude, Codex, and workflow messages. Type Use the current clean checkout. and press Enter; Shift+Enter inserts a line break. The message is appended with author: "zx" and authorType: "human". The terminal join seat remains available as an alternative:
codex-native-room join release-review --as zxClaude posts its own words to the same room through codex_native_room_post:
{"roomId":"release-review","author":"claude","authorType":"claude","text":"Implement the bounded storage change; do not commit."}Claude then starts Codex with the same room:
{"task":"Implement and verify the requested change.","roomId":"release-review","roomParticipant":"codex","cwd":"/absolute/project/path"}The worker reads entries after Codex's cursor, adds them to the turn/start user input, and advances only through the entries actually injected. When the job completes with a non-empty finalMessage, that message is appended with authorType: "codex" and the job id. The web timeline and an optional terminal seat both follow all three speakers:
12:34 zx Use the current clean checkout.
12:35 claude Implement the bounded storage change; do not commit.
12:36 codex Implemented and verified.Without watch, a new codex_native_start or codex_native_reply call is still required when Codex should respond.
Event-driven, multi-participant Codex watchers
Each watcher occupies one named participant seat. --as defaults to codex for backward compatibility and must satisfy the same participant-name validation used by room cursors. --role adds a prompt-level responsibility, while --sandbox selects the job sandbox and defaults to workspace-write.
codex-native-room watch <roomId> \
--as <participant> \
--role "<responsibility>" \
--sandbox <read-only|workspace-write> \
[--on-human] \
--cwd /absolute/project/path \
--profile balanced \
--interval 250 \
--max-per-hour 12 \
--max-human-per-hour 60 \
--max-agent-rounds 24 \
--soft-agent-rounds 12 \
--max-stalled-agent-rounds 3The watcher starts at the room's current end, so existing history is not treated as a new trigger. --cwd defaults to the process's current directory and must be inside CODEX_NATIVE_ALLOWED_ROOTS; --profile defaults to balanced. Autonomous Agent/system wakes use --max-per-hour (12 per rolling hour by default), while human-driven wakes use the independent --max-human-per-hour bucket (60 by default). A mixed wake counts against both buckets; reaching either required cap keeps the trigger pending and exposes its recovery time.
Trigger rules v2 for a watcher whose participant name is P are exact and ordered:
If
author === P, the entry never triggers P. This check happens before inspecting its text, so even a self-authored@Pcannot self-wake.A human entry can target P with case-insensitive
@Pas an independent word anywhere in the text. For agent or system entries, the mention must start a new line, such as@builder implement this; an inline sentence such asthe plan used @builderis descriptive and does not transfer the turn.user@P.comand@Pxyznever count.With
--on-human, any entry whoseauthorTypeishumanalso triggers.Everything else is silent. In particular, an unmentioned agent broadcast wakes nobody.
This intentionally changes the f26658a rule that no Codex-authored entry could ever trigger a watcher. The v2 loop-safety model is no self-wake + broadcasts do not trigger + a finite agent-round budget. Directed agent-to-agent handoffs are now allowed; undirected automatic reply chains are not.
Autonomous collaboration has three configurable safety layers. --max-agent-rounds <n> defaults to 24 and is the absolute ceiling that only a new human entry can reset. --soft-agent-rounds <n> defaults to 12 and pauses when there is no recent verifiable progress. --max-stalled-agent-rounds <n> defaults to 3 and stops after that many consecutive no-progress entries. The round count is the number of authorType: "codex" or "claude" entries after the room's most recent human entry.
Verifiable progress is limited to a new workspace/diff fingerprint, a changed test result, a newly completed image artifact, a distinct failure, or a validated source finding. A source finding must resolve through realpath inside the room project and match its persisted line range and excerpt hash; citing the same location again produces the same fingerprint. Repeated diffs, identical test results, the same error, reworded summaries, and 【关键决策】/【项目摘要】 markers do not count. Progress never resets the hard ceiling. A pure agent/system trigger that reaches the ceiling, fails the soft checkpoint, or trips the idle brake pauses for a human; a human trigger resets the count. The rolling human/autonomous hourly buckets remain independent resource safeguards, and the runtime persists all four counters for the web UI.
Only one non-terminal job may exist for a room. Room-backed manual starts and automatic watcher starts use the same per-room lock around durable job creation; multiple watcher processes therefore cannot pass the idle check together. A qualifying entry observed while a room job is active remains pending until the room is idle. The watcher uses the existing durable job/worker path, so the worker injects unread room entries and writes a non-empty final response back with authorType: "codex".
The automatic task prompt states the participant's own name, its role (when provided), why it woke, other participant names already visible in the room transcript, how to transfer the turn by starting a new line with @name, and the remaining budget. A blank final response remains a silent no-op. The watcher is event-driven only; it does not generate random or periodic speaking pulses.
For two roles sharing one checkout, use read-only for the architect/reviewer and workspace-write for the implementer. Read-only jobs are exempt from the existing cwd-overlap guard, so the reviewer can inspect the same project directory without weakening the writer's guard:
# Terminal 1: architecture and review
codex-native-room watch feature-room \
--as planner \
--role "Design and review the change; transfer approved implementation to @builder. Do not settle open direction or architecture choices yourself: escalate with @zx so the human can run a cross-model debate outside the room and bring the conclusion back." \
--sandbox read-only \
--cwd /absolute/project/path \
--profile high \
--max-agent-rounds 24 \
--soft-agent-rounds 12 \
--max-stalled-agent-rounds 3
# Terminal 2: implementation
codex-native-room watch feature-room \
--as builder \
--role "Implement the approved plan, run tests, then transfer review to @planner." \
--sandbox workspace-write \
--cwd /absolute/project/path \
--profile balanced \
--max-agent-rounds 24 \
--soft-agent-rounds 12 \
--max-stalled-agent-rounds 3A person can join the same room and start a bounded collaboration:
12:00 zx @planner design a safe fix for the failing cache invalidation.
12:01 planner Plan: isolate the cache key and add a regression test. @builder implement this plan.
12:04 builder Implemented; focused tests pass. @planner please review the diff.
12:05 planner Review passed. Human: the change is ready for your decision.
12:06 zx Approved; stop here.The first human message resets the count. The three following agent messages consume three of the six rounds. The final planner message reports to the human instead of transferring again.
Transcript output includes local time, author, and content. Continuation lines of a multiline message are indented to the content column. Authors are colored by authorType only when stdout is a TTY; redirected and piped output never contains ANSI escapes.
join and tail read the JSONL file directly and never call readRoomEntries or advanceRoomCursor. Human viewing therefore neither creates a participant cursor nor advances Codex's, Claude's, or any other participant's cursor.
author is a free-form display name. authorType is one of human, claude, codex, or the daemon-owned system workflow type. codex_native_room_read requires a participant; a normal read advances only that participant's cursor, while peek: true leaves it unchanged. Different participants therefore see and consume the same room independently.
Room state is local append-only JSONL:
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/log.jsonl
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/cursors.json
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/room.json
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/runtime.json
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/daemon.log
$CODEX_NATIVE_STATE_DIR/rooms/<roomId>/access-tokenEach log line has this shape:
{"seq":1,"at":"2026-07-30T12:34:56.000Z","author":"zx","authorType":"human","text":"Use the current clean checkout."}Entries written from a completed delegation also contain jobId. Sequence allocation, appends, and cursor updates are protected by a per-room cross-process lock. roomId accepts only letters, digits, ., _, and - (maximum 80 characters), so it cannot escape the room state directory.
A room is an isolation namespace, not an authentication or authorization system. Anyone who can call this local MCP server can use a valid room id.
If roomId is omitted, delegation behaves exactly as before: the task text is passed through unchanged, no room cursor is read or advanced, no room result is written, and developerInstructions are unchanged.
Working-directory overlap guard
Before creating any job, the bridge compares its canonical cwd with every non-terminal writable job. Two directories overlap when their realpath values are identical or either one is an ancestor of the other: /a/b therefore overlaps /a/b/c. Resolving .. components and symlinks before comparison prevents aliases of the same directory from bypassing the guard.
The check and durable job creation run under one global cross-process lock, so different rooms, MCP callers, Claude Code sessions, and watcher processes cannot race through the check. Processes that should coordinate must use the same CODEX_NATIVE_STATE_DIR, because that directory contains both the job registry and the lock.
read-only jobs are fully exempt: they neither block writable jobs nor are blocked by them. Image jobs are not exempt by kind. A workspace-write image job still gives Codex write access to its cwd, so its usual intent to produce only an image is not a filesystem guarantee; an image job is exempt only when its sandbox is actually read-only.
codex_native_start, codex_native_image, and codex_native_reply accept allowConcurrentCwd (default false). Passing true bypasses the guard for that creation only and should be reserved for intentional concurrent writes. The room watcher never bypasses it: a conflict skips that wake, prints a warning containing the conflicting job id, cwd, and status, and continues watching.
Use one room per project as the normal operating convention, but do not rely on room identity as a filesystem lock. For intentional parallel implementation, give each job a separate sibling Git worktree:
git worktree add ../my-project-feature featurePoint one job at the original checkout and the other at ../my-project-feature. Sibling worktrees do not overlap under this rule; pointing a job at their common parent does overlap both.
Reasoning profiles
Profile | Model | Effort | Use for |
| GPT-5.6 Luna | low | Searches, small fixes, formatting, mechanical work |
| GPT-5.6 Terra | medium | Everyday implementation, tests, multi-file work |
| GPT-5.6 Sol | high | Architecture, planning, difficult debugging |
| GPT-5.6 Sol | xhigh | High-risk cross-module changes, critical review |
| GPT-5.6 Sol | max | Problems where |
| GPT-5.6 Sol | ultra | Large autonomous multi-agent work |
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 toimage_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.
Room permissions are scoped by default. Ordinary bridge jobs and new browser-created room jobs keep workspace-write confined to the task directory. The composer can make one explicitly targeted new task read-only, project-writable, or desktop-capable; desktop capability requires a typed confirmation and is never the default. Every new job freezes its actual effectiveSandboxPolicy for audit; later UI changes do not rewrite or weaken a running job. Old records without that field are reported as unknown rather than inferred from current code.
Desktop-capability mode is explicit and high trust. A browser user must choose 完全访问, target exactly one Agent, and type 完全访问 before the next task is created. Codex then uses dangerFullAccess; Claude uses Claude Code's auto permission mode with native tools, Chrome, user/project settings, MCP servers, plugins, hooks, and skills. Codex runs with approvalPolicy: "never"; there is no OS file sandbox or interactive approval checkpoint. Native tools and user extensions can reach resources outside the project. Task instructions still request confirmation before deletion, deployment, commit, push, account, or purchase actions, but those are behavioral guardrails only. Use the default mode, read-only, a dedicated OS account, or a project-only container when strict isolation matters. CODEX_NATIVE_ROOM_DESKTOP_MODE=1 remains only for older room clients that do not carry an explicit per-task choice.
Explicit non-room danger-full-access is gated twice. Outside project-room desktop mode, the operator must set CODEX_NATIVE_ALLOW_FULL_ACCESS=1 on the server, and the caller must pass dangerousConfirmed: true. Project-room desktop capability uses the separate CODEX_NATIVE_ROOM_DESKTOP_MODE=1 operator gate.
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 validation is not room-agent containment. Every requested cwd, outputDir, and referenceImages path is resolved through realpath and checked against CODEX_NATIVE_ALLOWED_ROOTS. This validates bridge inputs, but a room Agent running in desktop-capability mode can still use native tools outside those roots. Reference images must already exist; not-yet-created output paths are checked against their nearest existing ancestor. Room ids are separately constrained to a single safe path component under the bridge-owned state directory.
The room web server is local and capability-URL protected, not a user account system. codex-native-room serve is hard-coded to 127.0.0.1. Each room has a private random token stored with mode 0600; every page, asset, and API request requires that token plus the exact loopback Host. Once accepted by one room server, that token acts as an operator UI capability for same-origin gateway access to every room in the shared state directory owned by the same local human; rooms owned by another human are rejected, including start/open requests. Treat the URL accordingly. Every response carries a strict CSP, nosniff, and Referrer-Policy: no-referrer; user-controlled values are rendered only as plain text. Browser posts also require a non-simple custom header and reject a foreign Origin. The token does not make the service suitable for a network: do not port-forward, reverse-proxy, tunnel, or expose it to another machine.
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.
Explicit desktop-capability mode trusts the project and both Agents. When
CODEX_NATIVE_ROOM_DESKTOP_MODE=1, it provides whole-machine native access without an OS sandbox; leave it off, useread-only, a dedicated account, or a project-only container when files outside the project must be unreachable.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.
Room context is layered and bounded, not a full replay. Each agent turn sees a persistent public summary — only conclusions explicitly published in the room with
【项目摘要】,【关键决策】, or【决定】markers, each with its sourceseq— plus a byte-bounded window of the most recent entries. Agents are instructed to publish those markers whenever a turn establishes durable project context, so the user normally does not need to add them manually. When the unread backlog exceeds that window, older unmarked entries are intentionally dropped once the turn succeeds and the cursor advances past them; they are not replayed later. Unmarked older chatter is ephemeral by design, which is what keeps the context from growing without bound.Skills stay provider-native and permission-bounded. Codex keeps its native Skill discovery. Claude receives an explicit local plugin assembled only from
~/.claude/skills(orCODEX_NATIVE_CLAUDE_SKILLS_ROOT) and can invoke matching Skills automatically. Skill instructions do not grant additional file, shell, network, or MCP access.Room navigation is stable. Project groups remain name-sorted when selected, and a room initially configured with port
0persists its first successful loopback port so restarts keep the same local URL.The UI gateway is hosted by the currently opened room daemon. It removes cross-port reloads but is not a separate highly available process; stopping that host daemon closes the current browser gateway until another room URL is opened.
Development
npm test # no network required
node --check src/*.mjsTests cover Codex and Claude profiles/workers, path containment, cwd-overlap detection and atomic creation, the non-room full-access gate and frozen room-permission audit, room ordering/cursors/concurrent writers, durable daemon lifecycle and single-owner locking, messages written during downtime, CLI posting/following/partial-line safety, local web security/polling/posting, directed handoffs and loop protection, failure writeback, subagent thread routing, and worker startup-failure recovery.
License
MIT — see LICENSE.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- AlicenseAqualityCmaintenanceA local MCP server that lets Claude delegate scoped work to Codex with structured results and guardrails, supporting planning, code review, build, reverse engineering, and long-running background tasks.11MIT
- AlicenseAqualityFmaintenanceMCP server for running external coding agents as background tasks inside Claude Code. Supports multiple backends including Codex, Grok, GLM, DeepSeek, and more.7MIT
- Alicense-qualityBmaintenanceAn MCP server that enables Claude to discover and delegate tasks to local Codex Skills and plugins, bridging Claude's natural language understanding with Codex's execution capabilities.Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server for running Claude Code and the Codex CLI as a pair: Claude drives, and hands self-contained tasks to Codex as background jobs.8MIT
Related MCP Connectors
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Cloud-hosted MCP server for durable AI memory
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PatrickStar-sketch/codex-native-bridge'
If you have feedback or need assistance with the MCP directory API, please join our Discord server