What can you do with this server?

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.

Which integrations are available for this server?

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.

How do I use Codex Native Bridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Codex Native Bridge start 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

by PatrickStar-sketch

Overview Schema Related Servers Score Discussions

JavaScript

Local

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 @name mentions 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 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.
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	`codex` on your `PATH`, logged in — required for the `codex_native_*` tools
Claude CLI	`claude` on your `PATH`, logged in, when Claude is a room member
Other agents	Optional. `opencode`, `grok`, or CodeBuddy Code (auto-detected inside `WorkBuddy.app`) enable their own providers
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
npm link

npm link exposes codex-native-room from this checkout; later source updates are picked up without another copy step.

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 accepted as bridge job inputs, separated by `:` (`;` on Windows). The explicit room desktop mode can reach outside them; see Security.
`CODEX_NATIVE_ALLOW_FULL_ACCESS`	(off)	Gates an explicitly requested `danger-full-access` sandbox for ordinary non-room jobs. Project-room desktop-capability mode is a separate operator policy; see Security.
`CODEX_NATIVE_ROOM_DESKTOP_MODE`	(off)	Legacy compatibility flag for old room clients. New browser requests freeze their own permission choice; see Security.
`CODEX_NATIVE_CODEX_BIN`	`codex`	Path to the Codex binary.
`CODEX_NATIVE_CLAUDE_BIN`	`claude`	Path to the Claude Code binary; only needed by the three-party project room.
`CODEX_NATIVE_STATE_DIR`	`~/.codex-native-bridge`	Where job records, logs, shared rooms, and generated images are stored.
`CODEX_NATIVE_ROOM_POLL_MS`	`250`	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
`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 or edit a bitmap with Codex's native image model, optionally using reference images
`codex_native_prune`	Delete finished job records, logs, and images past the retention window (`maxAgeDays` OR beyond `keepJobs`; run with `dryRun` first)
`codex_native_room_post`	Append a timestamped human, Claude, or Codex message to an isolated room
`codex_native_room_read`	Read entries after one participant's cursor, with optional non-advancing `peek`

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_native_health` / `grok_native_models`	Grok install, auth mode, account model catalog, effort tiers
`grok_native_start` / `status` / `result` / `reply` / `jobs` / `cancel`	Durable Grok jobs and session resumption
`grok_native_image`	Real bitmaps and video through Grok's native visual tools; a turn producing no file fails rather than describing one
`codebuddy_native_health`	CodeBuddy binary, account model catalog, profiles, sandbox caveats
`codebuddy_native_start` / `status` / `result` / `reply` / `cancel`	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
`codex-native-room init <roomId> --project <absolute-path>`	Create a collaborative room; both agents receive whole-room messages and may delegate or peer-review work
`codex-native-room start <roomId>`	Start the complete room in the background and return its local URL; repeated starts do not create a second instance
`codex-native-room stop <roomId>`	Stop an idle room; refuses while a job is active
`codex-native-room stop <roomId> --cancel-active`	Cancel the active job, then stop the room
`codex-native-room status <roomId>`	Show daemon, agent, current-job, and recent-error state
`codex-native-room run <roomId>`	Run the complete room in the foreground for debugging
`codex-native-room join <roomId> --as <author>`	Print the latest 20 complete entries, follow new entries, and append every stdin line as an `authorType: "human"` message
`codex-native-room tail <roomId>`	Follow entries written after startup without reading stdin
`codex-native-room post <roomId> --as <author> <text>`	Append one human message, print it in transcript form, and exit
`codex-native-room serve ...` / `watch ...`	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-project

Open 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 Claude to 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. Set CODEX_NATIVE_ROOM_DESKTOP_MODE=1 to load the full Claude Code desktop tool surface. High-risk actions still require user confirmation.
Send to Codex to give Codex sole initial ownership for implementation, commands, tests, or native tools.
Open Group settings to 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 display Ultra, but project rooms invoke the Claude Code CLI, so its current claude --help is authoritative (this machine currently tops out at max). Codex Sol/Terra currently expose Ultra. 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 last usage 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 conversation in 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 @claude or @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-project

Change 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 zx

http://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 zx

Claude 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 3

The 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 @P cannot self-wake.
A human entry can target P with case-insensitive @P as 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 as the plan used @builder is descriptive and does not transfer the turn. user@P.com and @Pxyz never count.
With --on-human, any entry whose authorType is human also 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 3

A 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-token

Each 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 feature

Point 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
`fast`	GPT-5.6 Luna	low	Searches, small fixes, formatting, mechanical work
`balanced`	GPT-5.6 Terra	medium	Everyday implementation, tests, multi-file work
`high`	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. 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.

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, use read-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 source seq — 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 (or CODEX_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 0 persists 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/*.mjs

Tests 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.

Available Tools

10 tools

codex_native_cancelB

Cancel a running Codex Native job and its app-server process tree.

ParametersJSON Schema

Name	Required	Description	Default
`jobId`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses the main effect (cancel job and process tree) but does not mention side effects, idempotency, or potential errors (e.g., job not found). Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is concise and information-dense. No unnecessary words, structure is fine.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one required parameter, no output schema, and no annotations, the description is minimal. It provides the core action but lacks details on return behavior, error cases, or relationship to other tools. Adequate for a simple tool but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds minimal meaning: the jobId identifies the job to cancel, but no details on format, how to obtain it, or it being required. Fails to fully explain the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Cancel'), the resource ('a running Codex Native job'), and includes the scope ('and its app-server process tree'), effectively distinguishing it from sibling tools like codex_native_start or codex_native_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., job must be running), conditions when cancellation might fail, or when not to use it (e.g., for completed jobs).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_healthC

Check the Codex Native Bridge, current Codex model catalog, image generation capability, and reasoning profiles.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	No	Existing directory used to start Codex. Defaults to the first allowed root.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description does not disclose whether this tool is read-only, requires authentication, or has side effects. It implies information retrieval but lacks explicit safety or behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence listing the checked components. It is efficiently structured but lacks bullet points or formatting that might improve scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description should explain the format of the health check results. It only lists what is checked, not the output structure, leaving the agent unsure of how to interpret the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter 'cwd' with default behavior. The tool description adds no extra parameter information, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks multiple components (Bridge, model catalog, image generation, reasoning profiles), distinguishing it from sibling tools like codex_native_models or codex_native_status. The verb 'Check' is somewhat vague but acceptable for a health tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives such as codex_native_status or codex_native_models. The description does not mention prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_imageA

Generate a real bitmap image through Codex's native image generation tool. Use for illustrations, assets, covers, photorealistic scenes, textures, and mockups. Do not use for flowcharts, architecture diagrams, data visualizations, charts, or UI prototypes; callers should create those with code or SVG. For bitmap requests, code-drawn substitutes are rejected. danger-full-access requires explicit user confirmation before passing dangerousConfirmed: true.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	Yes	Absolute working directory inside the user's home directory.
`model`	No	Optional explicit model override.
`effort`	No	Optional explicit reasoning effort override.
`prompt`	Yes
`profile`	No	Automatic model and reasoning preset.
`sandbox`	No		workspace-write
`outputDir`	No	Absolute output directory. Defaults to bridge state images.
`timeoutMinutes`	No
`dangerousConfirmed`	No	Must be true for danger-full-access. Set only after explicit user confirmation.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It mentions that code-drawn substitutes are rejected and that danger-full-access requires explicit user confirmation. However, it does not clarify output format (e.g., file path vs. URL), synchronicity, or permissions for other sandbox levels. This is minimally adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence serves a distinct role: purpose, use cases, exclusions, and behavioral constraint. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, no output schema, and no annotations, the description should cover more behavioral context. It fails to mention the return format (file path/URL), whether the tool is synchronous or asynchronous, and the implications of other sandbox settings. It is not fully complete for such a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%, meaning the schema already documents most parameters. The description adds only one significant detail: that dangerousConfirmed must be set to true for danger-full-access. It does not elaborate on other parameters like prompt, cwd, or outputDir beyond the schema. Thus, it adds marginal value, warranting a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates real bitmap images, lists explicit use cases (e.g., illustrations, textures) and non-use cases (flowcharts, diagrams), and distinguishes itself from sibling tools (no other image generation tool). The verb 'Generate' and resource 'bitmap image' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use (bitmap images) and when-not-to-use (flowcharts, etc.) guidelines, offers alternatives (code or SVG), and highlights the danger-full-access confirmation requirement. This gives clear context for choosing this tool over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_jobsA

List recent durable Codex Native jobs. Use after Claude restarts or when a job id was lost.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`status`	No

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It implies a read-only, non-destructive operation but does not detail what 'durable' means, whether the call is blocking, or any rate limits. Adequate but minimal for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence plus a usage hint, both front-loaded with essential information. No redundant words, every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description should explain what information is returned (e.g., job IDs, statuses). It only says 'List' but does not specify the return format or that it can filter by status. The usage hint is good but incomplete for full tool understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description adds no meaning to the parameters 'limit' and 'status'. It does not explain that limit controls count or that status filters by job state. The description fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'List' and resource 'recent durable Codex Native jobs', distinguishing it from siblings that start, cancel, or check status. The usage hint 'Use after Claude restarts or when a job id was lost' adds specific purpose context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit scenarios for when to use the tool ('after Claude restarts or when a job id was lost'), which helps differentiate from tools like codex_native_status or codex_native_result. However, it does not explicitly mention when not to use it or list alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_modelsA

List live Codex models and supported reasoning efforts. Use before an explicit model/effort override.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	No	Existing directory used to start Codex. Defaults to the first allowed root.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral disclosure. The verb 'List' implies a read-only, non-destructive operation, but the description doesn't explicitly confirm safety or mention any other behavioral traits (e.g., rate limits, auth requirements). It is adequate but lacks extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary purpose, and contains zero superfluous words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with one optional parameter and no output schema, the description is sufficient. It tells the agent what the tool does, what it returns (models and efforts), and when to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (one parameter well-documented in the input schema). The tool description adds no additional meaning about the 'cwd' parameter beyond the schema, so it does not improve semantics. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'live Codex models and supported reasoning efforts'. It distinguishes from sibling tools like codex_native_start, which are action-oriented, by positioning this as an exploratory/list tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Use before an explicit model/effort override' provides explicit guidance on when to invoke this tool. While it doesn't list alternatives or when-not-to-use, the instruction is specific and actionable for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_pruneA

Delete finished job records, logs, and generated images beyond the retention window. Running jobs are never removed. Use dryRun first to see what would go.

ParametersJSON Schema

Name	Required	Description
`dryRun`	No	Report what would be deleted without deleting it.
`keepJobs`	No	Upper bound, not a floor: finished jobs beyond this many most-recent ones are deleted. A job is removed when it is older than maxAgeDays OR falls beyond this count.
`maxAgeDays`	No	Delete finished jobs older than this many days. 0 deletes every finished job.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full burden. It discloses what gets deleted (finished jobs, logs, images) and that running jobs are safe, but omits details like irreversibility, authorization needs, or rate limits. The dryRun mention helps, but overall transparency is moderate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The first sentence states the core purpose, and the second provides a critical usage tip. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters, no output schema, and no annotations, the description is fairly complete: it explains what is deleted, the retention condition, and that running jobs are preserved. It could elaborate on the interplay of keepJobs and maxAgeDays, but the schema covers that detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds little beyond what the schema already explains for each parameter (dryRun, keepJobs, maxAgeDays). The description provides context but no additional parameter semantics, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes finished job records, logs, and generated images beyond a retention window, explicitly noting that running jobs are never removed. This distinguishes it from sibling tools like start, cancel, or list operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using dryRun first to see what would be deleted, providing explicit usage guidance. It does not compare directly to sibling tools, but the action of pruning is distinct enough that no further differentiation is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_replyA

Resume a previous Codex Native thread with a follow-up task. Use the prior job id or thread id; returns a new durable job id.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	Yes	Absolute working directory inside the user's home directory.
`task`	Yes
`model`	No	Optional explicit model override.
`effort`	No	Optional explicit reasoning effort override.
`profile`	No	Automatic model and reasoning preset.
`sandbox`	No		workspace-write
`threadId`	No
`previousJobId`	No
`timeoutMinutes`	No
`dangerousConfirmed`	No	Must be true for danger-full-access. Set only after explicit user confirmation.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool resumes a thread and returns a new job id, but does not detail side effects, permissions, or state changes. Given the operation type, minimal transparency is acceptable but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the core purpose. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, no output schema, and no annotations, the description is somewhat complete for the main action but lacks guidance on parameter combinations (e.g., requirement for threadId vs previousJobId) and return details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, and the description only mentions using prior job/thread id, ignoring 8 other parameters. It adds no meaningful semantics beyond the schema, failing to compensate for low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resumes a Codex Native thread with a follow-up task, using a prior job or thread id, and returns a new durable job id. This distinguishes it from siblings like codex_native_start for new threads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use for resuming a previous thread with prior identifiers, implying not for new threads. However, it does not explicitly state when not to use or mention alternatives, though siblings exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_resultA

Read the complete result of a Codex Native job, including final message, changed files, commands, verification, image paths, and errors.

ParametersJSON Schema

Name	Required	Description	Default
`jobId`	Yes

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It details the contents of the result, offering good transparency about what the tool returns. However, it could mention that jobId must reference a completed job, but the read nature is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that lists components without fluff. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description covers the return details well. It could note that the job must be finished, but overall it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter (jobId) with 0% documentation coverage. The description does not elaborate on the parameter's format or role beyond what the schema provides, which is minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read the complete result of a Codex Native job' with specific verb and resource. It lists components (final message, changed files, etc.), distinguishing it from sibling tools like codex_native_status, but does not explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after a job completes, but provides no explicit guidance on when to use this tool vs alternatives like codex_native_status, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_startA

Start a durable Codex task in the background. Returns a job id immediately. Poll with codex_native_status, then read codex_native_result. danger-full-access requires explicit user confirmation before passing dangerousConfirmed: true.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	Yes	Absolute working directory inside the user's home directory.
`task`	Yes	Self-contained task with scope and acceptance checks.
`model`	No	Optional explicit model override.
`effort`	No	Optional explicit reasoning effort override.
`profile`	No	Automatic model and reasoning preset.
`sandbox`	No		workspace-write
`timeoutMinutes`	No
`dangerousConfirmed`	No	Must be true for danger-full-access. Set only after explicit user confirmation.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses asynchronous behavior (returns job id immediately) and safety requirements. However, it omits error handling, failure modes, and auth requirements, which would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences. First sentence explains core functionality and outcome, second sentence provides usage hints and safety warnings. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters and no output schema, the description covers the essential workflow and references sibling tools. It could mention return format more explicitly but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema already documents most parameters. The description adds context about the danger-full-access confirmation but doesn't significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it starts a durable Codex task and returns a job id immediately. It distinguishes from sibling tools like codex_native_status and codex_native_result by mentioning polling and reading results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent to poll with codex_native_status and read with codex_native_result. It also warns about danger-full-access requiring explicit user confirmation for dangerousConfirmed: true, providing clear when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_native_statusB

Read current status of a background Codex Native job. Wait at least 30 seconds between polls; do other work before checking again.

ParametersJSON Schema

Name	Required	Description	Default
`jobId`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is responsible for disclosing behavior. It only mentions polling advice but does not describe possible status values, error handling, or whether the operation is read-only. This leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no wasted words. The first sentence states purpose, the second provides actionable usage advice. Well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity (1 parameter, no output schema), the description omits crucial context: possible status values, what happens on error, and relationship to sibling tools like 'codex_native_result'. It is insufficient for selecting and using the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single required parameter 'jobId' has no description in the input schema, and the tool description adds no additional meaning or format guidance. With 0% schema description coverage, the description fails to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads the current status of a Codex Native job. The verb 'Read' and resource 'status of a background Codex Native job' are specific and distinct from sibling tools like 'codex_native_result' or 'codex_native_cancel'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance to wait at least 30 seconds between polls and to do other work before checking again. However, it does not mention when to use alternatives like 'codex_native_result' after completion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

10 tool updatesv0.1.0Jul 29, 2026
- First observedcodex_native_cancel
- First observedcodex_native_health
- First observedcodex_native_image
- First observedcodex_native_jobs
- First observedcodex_native_models
- First observedcodex_native_prune
- First observedcodex_native_reply
- First observedcodex_native_result
- First observedcodex_native_start
- First observedcodex_native_status

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: listing models, managing job lifecycle (start, status, result, cancel, reply, prune), health check, and image generation. No overlapping functionality.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with the `codex_native_` prefix, using descriptive nouns or verbs. No mixing of conventions.

Tool Count5/5

10 tools is well-scoped for the server's purpose—managing durable Codex tasks and image generation. Each tool earns its place without redundancy.

Completeness5/5

The tool surface covers the full lifecycle: start, monitor (status), retrieve (result), cancel, resume (reply), cleanup (prune), plus listing, health check, and image generation. No obvious gaps.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
214
Motecloud MemoryOAuth
io.github.motecloud
Cloud-hosted MCP server for durable AI memory
Knowledge & Memory Cloud Platforms
2
mcp
dev.augments
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Developer Tools Documentation Access
2128
docs
dev.continue
An MCP server for docs.continue.dev
Documentation Access Developer Tools Search
2

Related MCP Servers

codex-dobby-mcp
Developer Tools Coding Agents
Averyy
A
license
A
quality
C
maintenance
A 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.
Updated 2 months ago (2026-07-10 18:06 UTC)
11
MIT
Clanker
Coding Agents Code Execution Autonomous Agents
kckylechen1
A
license
A
quality
F
maintenance
MCP server for running external coding agents as background tasks inside Claude Code. Supports multiple backends including Codex, Grok, GLM, DeepSeek, and more.
Updated 2 months ago (2026-07-09 13:59 UTC)
7
MIT
Codex Capability Bridge
Agent Orchestration Autonomous Agents Developer Tools
AEcru
A
license
Not graded
quality
B
maintenance
An 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.
Updated 2 months ago (2026-07-17 01:48 UTC)
Apache 2.0
codex-offload-mcp
Coding Agents Autonomous Agents Code Execution
jgt87
A
license
A
quality
B
maintenance
An 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.
Updated a month ago (2026-07-28 20:48 UTC)
8
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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