Local Codex Bridge

English · 简体中文

A thin supervisory MCP bridge between external AI supervisors and native Codex.

Current release: V2.3.4

Local Codex Bridge is a lightweight MCP stdio adapter for Windows and macOS:

ChatGPT / external AI supervisor
              ↕
        Local Codex Bridge
              ↕
      native Codex app-server
              ↕
   native Codex threads / turns

It lets an AI that is good at conversation, planning, and sustained supervision oversee real engineering work performed by local native Codex. It does not recreate Codex.

The supervisor owns the goal, resources, boundaries, risks, approvals, and acceptance. Codex retains its native autonomy for coding and execution.

The Bridge stays thin:

• It creates no second job or task system.
• It does not copy Codex conversation history.
• It keeps no parallel thread database.
• It does not cache the “current model.”
• It does not rebuild Goal, Queue, or Search.
• It does not replace Codex session, thread, or turn semantics.

The native Codex thread/session remains the source of truth for execution.

Changelog · Protocol and compatibility assumptions

---

What V2.3.0 introduced

V2.3.0 expanded the public supervisory surface to 12 MCP tools while retaining the boundary of exposing only the native surface needed for supervision.

The release added or refined:

• Independent paging of native persistent History.
• Native Goal: read, set, and clear a persistent objective.
• Native Queue: manage follow-up input for an active workflow.
• Native Search: search across threads and locate occurrences within a thread.
• On-demand capability and lineage metadata.
• Typed compact observation, drainage, and loss semantics.
• A single event-driven observe wait of up to 120 seconds.
• Delivery of every successful tool result through structuredContent.
• One shared Bridge core for Windows and macOS, with differences confined to native platform boundaries.

Bridge does not reimplement these capabilities. Native Codex still owns History, Goal, Queue, Search, and the thread lifecycle; Bridge provides bounded mappings and supervision.

---

Responsibilities

External supervisor / ChatGPT

The supervisor is suited to:

• Understand the user’s goal.
• Break down the work.
• Set scope, resources, and risk boundaries.
• Decide when to keep observing, correct, approve, or interrupt.
• Judge whether the result meets acceptance criteria.
• Provide oversight when Codex cannot safely decide on its own.

Native Codex

Native Codex continues to own:

• Thread and turn lifecycles.
• Workspace files and command execution.
• Its context and persistent history.
• Sandbox and approval-policy behavior.
• The actual model and reasoning effort in use.
• Persisted execution results.
• Native Goal, Queue, Search, and lineage.

Local Codex Bridge

Bridge connects the two:

• MCP stdio ↔ Codex app-server JSONL.
• Bounded exposure of state needed for supervision.
• Forwarding explicit control intent.
• Failing closed at high-risk, ambiguous, or protocol boundaries.
• No second orchestration runtime.

---

The 12 MCP tools

See src/tools.ts for the full schemas and runtime validation.

Content delivery and read policy

History and Search default to content_policy:"protected". Secret-shaped content detection may reject an entire page, including ordinary code that matches the detector. A caller may explicitly choose content_policy:"exact" to deliver unchanged native text to the MCP caller for that call. This may expose sensitive content; it is not saved as a session preference and has no automatic fallback. Protected mode provides default detection and an explicit choice point, not an access boundary that prevents the supervisor from obtaining the original content.

Successful Goal and Queue reads and responses preserve native values without secret-shape filtering of their bodies. Known oversized echoed input is rejected before a write; native-added fields can still produce an acknowledged mutation whose result cannot be delivered. Do not resubmit the mutation for that reason. For an oversized multi-item page, a smaller limit may help. If one item remains oversized, inspect it on the native side; repeatedly making the same Bridge read cannot recover it. Errors and operational diagnostics remain redacted.

These exact responses do not inherit Observe’s short-text, internal-array, or field-count budgets. They remain subject to actual byte limits, required-field checks, and defensive serialization checks. Failure never returns a partial page or fabricated cursor. See the protocol details.

In compact view, terminal.final_result_pending: true means final text awaits a later page, and final_result_meta is omitted until then. Follow next_cursor even if the status is terminal. Once the text arrives, inspect final_result_meta.complete: false means source text was not fully received or live retention clipped it. Raw and terminal text also have a 48k cap. If more content is needed, read narrow History for that thread and terminal turn, or inspect native Codex. Ordinary compact-event budgets remain unchanged.

---

Typical supervision workflow

1. Start or continue a turn

A successful codex_turn response only means native turn/start was accepted. It does not mean the task is complete.

Long-running work should usually continue under codex_observe supervision.

codex_turn
    ↓
codex_observe
    ↓
 ┌───────────────┬────────────────┬─────────────────┐
 │ continue      │ steer          │ respond         │
 │ observing     │ same turn      │ real pending    │
 │               │                │ request         │
 └───────────────┴────────────────┴─────────────────┘
    ↓
terminal state / acceptance

Key rules:

• A long interval without new command output does not prove Codex is stalled.
• Use codex_steer for new semantic information or a correction, not a timed nudge.
• codex_respond can answer only a real pending request.
• Use codex_interrupt when the current turn actually needs to stop.
• thread_id is a native Codex thread identity, not a permanent task ID invented by Bridge.

2. Keep live state separate from persistent history

codex_observe serves current live supervision; codex_history reads native persisted turns and items.

After Bridge restarts, loses its runtime ring, or no longer has a live cursor, it does not manufacture a seemingly active runtime from history. Read codex_history to recover persistent content.

codex_search locates content; History reads it. An occurrence’s turnCursor can anchor a narrow History read in the same thread, but Search does not replace History.

3. Keep Goal, Queue, and Steer distinct

• Goal: the persistent objective of a native thread.
• Queue: follow-up input that native Codex executes after the current active workflow.
• Steer: an immediate semantic correction to the current active turn.

These are not three spellings of a “next prompt,” and Bridge does not combine them into its own task model.

codex_goal(action:"set") requires an explicit budget intent:

Bridge sends no extra resume or turn-start request for Goal set, get, or clear. An active Goal may still cause native Codex to continue execution. Goal clear is not an interrupt or a barrier against work already scheduled. Use the exact codex_interrupt when the current turn must stop.

Queue delete likewise does not interrupt a turn that has already begun.

---

codex_observe

The default view:"compact" delivers bounded, typed supervision facts. Use view:"raw" for a narrow inspection of retained native events.

Optional wait_ms performs one event-driven wait with a fixed deadline, up to 120000 ms. Bridge does not poll in the background or decide on its own that Codex is stalled.

Keep these distinctions in mind:

• Continue either view with next_cursor.
• stream_lost reports evicted streaming deltas.
• facts_lost reports evicted other supervision facts.
• cursor_lost summarizes either kind of loss; it does not tell you to jump to cursor_floor.
• With runtime_available:false, live pending, terminal, and cursor fields may only be unavailable placeholders. Do not infer that nothing happened.

When runtime_available:true, compact pending_requests is a complete current snapshot. Compact omits it when empty; absence means there are currently no pending requests, not that this page contains no update.

Compact terminal.final_result is also subject to the delivery window of the final item and terminal cursor. Final text may already have arrived as a message fact, so a compact terminal on one page may contain only status and error, without final_result. An absent field does not mean the raw terminal snapshot or persisted History lacks final text. Do not skip next_cursor or infer status just to force these fields onto one page.

---

Terminal state: use status

Always classify a terminal by native terminal.status first.

Do not infer terminal status from other fields:

• final_result does not mean the turn succeeded.
• terminal.error does not necessarily mean status:"failed".
• A turn with status:"interrupted" may carry a structured error.
• Bridge does not need a separate error notification to learn the terminal reason.

Read terminal.status first, then interpret final_result and error as separate facts about that terminal.

---

Successful results use structuredContent

In V2.3.0, the complete result of every successful tools/call is in:

result.structuredContent

result.content contains only a tiny text marker, not parseable success JSON.

Older clients that parse successful results from text content need to migrate to structuredContent.

Errors still use explicit isError and text-error paths; they are not disguised as successful results.

---

Do not retry a write just because it timed out

If a native mutating request was written to app-server but its acknowledgement timed out, Bridge reports the outcome as:

UNKNOWN / possibly accepted

This is not a confirmed failure.

Affected requests include:

• thread/start
• thread/resume
• turn/start
• turn/steer
• turn/interrupt
• thread/goal/set / thread/goal/clear
• thread/queue/add / update / delete / reorder

Observe or read native state first, then decide on any further action.

Do not resubmit a mutating request solely because its acknowledgement timed out.

Bridge does not automatically retry, compensate, or guess the result.

---

History and Search

codex_history follows the native history mode:

• Paginated thread: page the turn index, then read items in a specified turn.
• Legacy thread: page complete turns.

Bridge creates no item/chunk cursors of its own and does not silently read a full history after a paging failure.

A successful History page must be delivered losslessly. A page that exceeds the transport byte boundary, triggers the selected content policy, or fails defensive JSON serialization is rejected in full. Bridge does not return partial data with a cursor.

codex_search maps native Search only:

• kind:"threads": locators across threads.
• kind:"occurrences": occurrence locators inside a specified paginated thread.

Search does not build a Bridge semantic index, score relevance, infer a workspace restriction, or fall back to reading complete History.

See PROTOCOL-ASSUMPTIONS.md for exact paging, cursor, and transport contracts.

---

Capability and lineage

codex_threads can expose native capability and lineage metadata on demand, including:

• canAcceptDirectInput
• sessionId
• forkedFromId
• parentThreadId
• Source information

These are native metadata, not a Bridge writer lease, permission model, or lifecycle database.

parent_thread_id and ancestor_thread_id can filter spawned descendants. Spawn lineage and fork lineage are different concepts. Bridge does not recursively build a relationship graph or automatically resume or take over a thread from lineage.

---

Model and reasoning effort

Bridge does not take ownership of Codex’s “current model” state.

If codex_turn omits model and effort, Bridge:

• Does not call model/list.
• Does not infer the current model.
• Does not send a new model or effort override.

If the supervisor specifies a model, Bridge performs bounded validation against the current native catalog. It does not cache the catalog or create a current-model registry.

Where upstream metadata cannot establish that a model and effort combination is incompatible, Bridge does not guess. Native Codex makes the final decision.

---

Elicitation is currently unsupported

mcpServer/elicitation/request is not currently part of the response surface supported by codex_respond.

If native Codex emits such a request, Bridge:

• Retains and exposes it.
• Does not silently discard it.
• Does not guess its response schema.
• Does not fabricate a generic answer.

Support would require an explicit, stable, validated upstream contract.

---

Quick start

Requirements

• Windows or macOS
• Node.js 24+
• Official Codex executable:
  • Available as codex on PATH, or
  • Specified explicitly with CODEX_EXE.

This project does not bundle or depend on the @openai/codex npm package.

Clone, build, and test

git clone https://github.com/zoeynine/Local-Codex-Bridge.git
cd Local-Codex-Bridge
npm ci
npm run typecheck
npm run build
npm test

Start directly

Windows PowerShell:

$env:CODEX_EXE = 'C:\path\to\codex.exe' # Omit if codex is on PATH
npm start

macOS / POSIX shell:

CODEX_EXE=/path/to/codex npm start

You may omit CODEX_EXE if codex is already on PATH.

Configure an MCP client

A strict MCP stdio client should launch the built Node entry directly:

command: node
args:    /dist/src/index.js
env:     CODEX_EXE=

Client configuration formats vary, but the final command should run directly:

node /dist/src/index.js

Do not put npm start behind Secure MCP Tunnel or another strict JSON-RPC stdio transport. npm lifecycle output can contaminate protocol stdout.

After the Bridge tool set changes, an already connected MCP client usually needs to reconnect or restart to refresh its tool catalog.

---

Optional: Secure MCP Tunnel

Remote MCP use can place Secure MCP Tunnel in front of Bridge:

remote MCP client
        ↕
Secure MCP Tunnel
        ↕
node /dist/src/index.js
        ↕
native Codex

Tunnel authentication, profile, port, readiness endpoint, and process lifecycle are external configuration.

This repository:

• Does not create a Tunnel profile.
• Does not store production credentials.
• Does not hard-code a production port.
• Does not turn the Tunnel control plane into a Bridge HTTP API.

---

Windows

The optional Tray in windows/ is a lightweight launch and status layer for an installed Tunnel client. It is not required for the Bridge core.

The canonical launcher is LocalCodexBridgeTray.*.

Local settings template:

windows/local-settings.example.json

The actual windows/local-settings.json remains ignored and is not committed.

Configuration precedence:

1. Explicit command-line arguments.
2. LOCAL_CODEX_BRIDGE_* environment variables.
3. Legacy LUMEN_CODEX_V2_* environment variables.
4. Ignored local settings.

The Tray does not restart Tunnel automatically. It stops a process started by the current Tray instance only after rechecking that process identity, profile, PID, and related information still match.

---

macOS

Start Mac Codex Bridge.app, launcher/, and bin/start-production-tunnel provide macOS Finder and Tunnel integration.

They are platform layers. The Bridge still runs the same entry:

dist/src/index.js

After changing the launcher or Finder bundle, rebuild and validate on macOS 12+:

launcher/build-launcher.sh
npm run test:macos

Windows and macOS are two platform entry points to one Bridge, not separate implementations.

---

Security and trust boundaries

Local Codex Bridge does not create a new operating-system sandbox.

Actual file, command, network, and process capabilities still depend on native Codex configuration and each turn’s:

• sandbox
• approval_policy

For example:

• danger-full-access broadens the file, command, and process access allowed by the sandbox.
• approval_policy=never does not expand the OS sandbox by itself, but removes the interactive approval layer.

These are separate risk dimensions.

Also keep in mind:

• Natural-language instructions sent through codex_turn or codex_steer may lead Codex to use its existing file and command capabilities.
• The absence of a generic shell MCP tool in Bridge does not mean native Codex cannot execute commands.
• codex_threads can see persistent threads visible to the same OS user and Codex runtime. Filters do not provide access isolation.
• Bridge inherits its environment when starting app-server, except that it removes the Tunnel CONTROL_PLANE_API_KEY.
• Other environment variables remain part of the trusted launch boundary; avoid unnecessary secrets there.
• Bridge has transport sanitization and bounded projection, but is not a hostile multi-tenant gateway.
• Keep checkpoints short; do not store full prompts, transcripts, raw events, command output, or final answers.

For remote use, an authenticated and correctly configured Tunnel must provide the connection boundary.

---

Persistence

Native Codex persists:

• Threads.
• Turns.
• Conversation history.
• Native execution results.
• Thread goals.
• Queued follow-ups.

Bridge’s live event ring, active-turn runtime state, and pending requests are primarily bounded in-memory state.

After ring loss, Bridge does not reconstruct fake live state from History. stream_lost, facts_lost, and cursor_lost explicitly report missing live supervision evidence.

Checkpoint

codex_checkpoint is the one intentionally persisted piece of Bridge-side supervisory state, and it remains concise and bounded.

Windows default:

%LOCALAPPDATA%\LocalCodexBridge\checkpoints\.json

macOS default:

~/Library/Application Support/LocalCodexBridge/checkpoints/.json

Override with:

LOCAL_CODEX_BRIDGE_CHECKPOINT_DIR

The legacy LUMEN_CODEX_V2_CHECKPOINT_DIR is still supported for compatibility. Bridge does not automatically migrate old checkpoints.

---

Deliberate non-goals

Local Codex Bridge deliberately does not provide:

• A browser UI.
• An HTTP control plane or HTTP MCP server.
• A second task queue or job database.
• Transcript duplication.
• A semantic index.
• A model cache or current-model registry.
• A queued-message facade.
• Automatic retries of mutating requests.
• Automatic app-server restart.
• A generic shell or command/exec MCP surface.
• Automatic exposure of every experimental app-server API.

The aim is not to copy all of Codex app-server into MCP, but to expose the smallest validated surface needed for supervision.

---

Upgrading Codex

Bridge necessarily depends on a small set of native app-server protocol assumptions.

Current dependencies, validation status, corresponding code locations, and checks needed after upstream changes are collected in:

PROTOCOL-ASSUMPTIONS.md

When upgrading the Codex runtime, changing protocol-facing behavior, or investigating a related regression, check that list first. Do not change Bridge solely on the basis of an older implementation assumption.

---

Development and testing

Common checks:

npm run typecheck
npm run build
npm test

npm test runs shared runtime, compact, History, Goal, Queue, Search, app-server, MCP, checkpoint, platform, shutdown, UX, and related tests, then the tests for the current platform.

The protocol/compact-schema check requires CODEX_EXE to explicitly identify the official Codex executable under test. This script does not use the PATH fallback of the normal Bridge startup path.

Windows PowerShell:

$env:CODEX_EXE = 'C:\path\to\codex.exe'
npm run check:compact-schema

macOS / POSIX shell:

CODEX_EXE=/path/to/codex npm run check:compact-schema

The repository retains the historical npm run smoke:live helper, but the current script has not been adapted to V2.3.0 structuredContent, independent History, or the runtime-loss contract. It is not a valid smoke or cross-platform acceptance command for this release. Do not run it merely to qualify a release. If a live smoke test is needed later, update the script separately and review its persistent-thread side effects first.

Main implementation locations:

• src/mcp.ts — MCP stdio / JSON-RPC boundary
• src/app-server.ts — native Codex app-server process / protocol adapter
• src/tools.ts — 12 tools, schemas, and supervisory semantics
• src/runtime.ts — bounded live runtime / events / pending requests
• src/observe-compact.ts — compact typed supervision projection
• src/history.ts — lossless History delivery checks
• src/goal.ts — native Goal validation / delivery
• src/queue.ts — native Queue validation / delivery
• src/search.ts — native Search validation / delivery
• src/checkpoint.ts — optional supervisory checkpoint
• src/platform.ts — Windows / macOS platform boundary
• src/version.ts — canonical Bridge version
• windows/ — optional Windows Tray
• launcher/, bin/, Start Mac Codex Bridge.app — optional macOS integration

---

License

MIT License — see LICENSE.

Collaborators and acknowledgements

Collaborators: Xiaonian (ChatGPT) and Alden / Xingjian (Codex).

Thank you for helping turn the small idea of letting an external AI genuinely supervise native Codex, step by step, into a Bridge thin enough and clear enough to share and build on. (*╹▽╹*)

And thank you to Yu’an. Without you, I would not have tried to do something at all. ღ( ´･ᴗ･` )