codex-bridge-mcp

# Codex Bridge MCP > Let Claude or Codex make decisions and Codex execute and complete tasks in a controlled and sustainable way. Codex Bridge MCP is a local MCP that connects **Task Orchestrators** (Claude Code or Codex) with **Codex App Server**. It is not another model, nor a script that forwards a prompt to Codex. Instead, it maintains a stable execution thread, running state, approval records, and review loop for a development task. When requirements need multiple rounds of supplementation, code modifications require approval, tasks may be interrupted, and results need to be reviewed, Claude does not need to re-explain the context every time, nor does it have to take Codex's "completion" as acceptance. ## For Whom Suitable for developers and teams who already use Claude and Codex and want to use them in real engineering tasks: - Claude excels at understanding requirements, breaking down problems, making judgments, and reviewing results; - Codex excels at entering repositories, modifying files, executing commands, and completing verification; - You need an execution chain that won't break during multi-round collaboration. Claude is the default and clearest collaboration entry point; if you already use Codex as an upper-level orchestrator, you can also let Codex schedule an independent Codex Runtime through the same set of MCP tools. ## Problems Solved One-time calls to Codex are easy; the difficulty lies in making complex tasks reliably reach acceptance. | Real-world development issues | Codex Bridge MCP's approach | | --- | --- | | Execution context lost after several rounds of requirement supplementation | A task is bound to the same Codex thread, and subsequent requirements enter the same execution chain | | Repeatedly starting and stopping execution environments for the same project | A `projectRoot` reuses an active Runtime Host | | High-risk commands should not be automatically approved | Codex's approval requests are explicitly approved or rejected by the task orchestrator, and Bridge does not automatically approve | | Tasks lost after Claude, Bridge, or computer restart | Saves task, thread, event, and queue states; prioritizes reconnection, and recovers known threads if necessary | | Tasks completed but unable to determine if they meet requirements | Claude obtains real diff and continues review or issues next round of requirements | | Logs, events, and patches overwhelm model context | Returns summaries and paginated information by default, and only displays original content when explicitly requested | ## How a Task Flows ```text You propose goals and constraints │ ▼ Claude / Codex clarify requirements, break down tasks, make decisions, and review results │ stdio MCP (compatible entry point) ▼ Bridge Adapter automatically connects to or starts a shared Core, does not hold task state │ Local Streamable HTTP MCP ▼ Bridge Core uniquely holds tasks, threads, Runtime, TUI, approval, and recovery states │ WebSocket JSON-RPC ▼ Codex modifies code, executes commands, and completes verification in a real repository ``` A task usually involves the following steps: 1. Claude connects to the project session with `task_open`; Bridge defaults to reusing the task, Codex thread, and TUI already bound to the project, and only creates a new one if there is no session. 2. Claude sends supplementary requirements with `task_send`; Bridge confirms that the visible TUI of the same thread is still running, then starts the Codex turn and waits until approval, completion, failure, or interruption. 3. When Codex requires authorization, `task_send` directly returns an approval attention event; Claude makes a decision with `approval_decide` and continues to wait for the next attention event in the same turn. 4. After Codex completes a round, Claude reviews the real changes with `task_diff`; if it does not meet the acceptance criteria, it continues to send the next round of requirements. 5. When the task approaches the context limit, Claude can call `task_compact` to compress the context in the original thread. ## Core Value ### Continuous Execution, Not One-Time Forwarding `taskId` is bound to `codexThreadId`. Bridge saves the current project session in SQLite, so even if the MCP reconnects, the process restarts, or the orchestrator temporarily loses `taskId`, calling `task_open` again will return the original task and thread, and will not unexpectedly open a second TUI. ### Codex Can Also Schedule Codex Bridge supports two orchestration methods: ```text Claude Code → Codex Bridge MCP → Codex Runtime Codex → Codex Bridge MCP → Independent Codex Runtime ``` In the second method, the upstream Codex is the task orchestrator: it calls `task_open`, `task_send`, `task_status`, and `task_diff`, and Bridge starts or reuses an **independent** Codex App Server Runtime to perform the actual work. ### Approval Controllable, Responsibility Clear Bridge only saves and forwards approval requests, and does not make decisions for the task orchestrator or user. Operations that require authorization, such as command execution and file modification, must go through explicit `approve` or `deny`. Approval, completion, failure, and interruption are saved as turn attention states with monotonic revision; the orchestrator writes ACK after completing the corresponding action. ### Interruption Recoverable, Not Silent Re-run Bridge records Runtime, thread, turn, and queue states. After Core restarts, it reconciles local active turns with the actual state of the App Server through `thread/read`; work that cannot be confirmed as completed will be marked as interrupted. ### One Core, Not a Separate Runtime for Each Client Claude, Codex, or their new sessions all connect to the same local Bridge Core. MCP client connections are only temporary protocol sessions; SQLite, Runtime WebSocket, task queue, and approval requests are held by the Core for an extended period. ### Results Reviewable, Not Just Trusting "Completed" Codex's completion event is only a prompt for Claude to review. Bridge provides workspace diff, changed files, and optional patches, allowing acceptance based on real code rather than natural language declarations. ### Context Cleaner States, events, and diff return short summaries that can be used for continued decision-making: - Approval requests only provide decision-making information by default; complete payload is only requested when necessary; - Events return paginated by default, with cursors for continued reading; - Diff provides short statistics and paginated file lists by default; only complete patches are requested for line-level review. ## Product Boundary Codex Bridge MCP's responsibility is to reliably collaborate with Claude and Codex, without replacing either: - **Not a new model**: does not plan for task orchestrators or write implementations for Codex; - **Not a cloud agent**: Bridge runs locally, without additional cloud intermediaries; - **Does not automatically approve operations**: approval authority always belongs to task orchestrators and users; - **Does not use TUI to pass tasks**: normal tasks enter Codex through App Server's `turn/start`. Visible TUI is only for observation or human interaction. ## Quick Start ### Prerequisites - Windows and PowerShell; - Node.js `>= 20.11.0`; - Installed and authenticated Codex CLI, supporting `codex app-server`; - Clients supporting stdio MCP, such as Claude Code or Codex; can also directly connect to Streamable HTTP MCP. ### Installation and Build ```powershell git clone https://github.com/luojiateng/codex-bridge-mcp.git cd codex-bridge-mcp npm install npm run build ``` After building, `dist/index.js` is a stable stdio MCP entry point. It automatically connects to or starts a shared Bridge Core listening only on `127.0.0.1`, without needing to open another terminal to manage the Core. ## Core Lifecycle and Upgrade Bridge Core adopts **on-demand startup**, not a Windows auto-start service: the first time Claude Code or Codex establishes an MCP connection, the stdio Adapter starts the shared Bridge Core if there is no available Core on the local machine; when tasks need an execution environment, the Core's Runtime Host Manager starts `codex app-server` for the corresponding project. ## Capabilities | What do you want to do | Orchestrator uses | | --- | --- | | Connect to or start a sustained task | `task_open` (default `mode: "reuse"`) | | Explicitly start an isolated new thread | `task_open` (`mode: "new"`) | | Continue supplementary requirements on the original task | `task_send` | | MCP call cancellation or reconnection and continue waiting | `task_await`; un-ACKed results are also replayed by `task_open` / `task_send` | | Diagnose progress, queue, and historical events | `task_status`, `task_events` | | Approve or reject Codex operations | `approval_decide` | | Review real code changes | `task_diff` | | Compress long task context | `task_compact` | | Reconnect to or retrieve tasks | `task_recover`, `task_list` | Complete tool schema see [`src/mcp/schemas.ts`](src/mcp/schemas.ts). Product constraints, phase plans, and acceptance matrices see [`docs/phase-development.md`](docs/phase-development.md). ## Local Data and Privacy Bridge saves tasks, threads, semantic events, approvals, queues, and context snapshots locally to achieve recovery and review. The default data directory is located in `data/` under the Bridge installation directory, which may contain task content, commands, approval reasons, and diff information; `data/mcp-token` is a local HTTP access token. These local running data, logs, and `.env` are excluded by the project's `.gitignore`. Please manage them like local development logs and do not write real credentials into task descriptions, environment examples, or repository files. ## Development Verification ```powershell npm run typecheck npm run build npm run check:forbidden npm run smoke:protocol npm run smoke:context npm run smoke:queue npm run smoke:recovery npm run smoke:runtime-interruption npm run smoke:project-session npm run smoke:attention npm run smoke:diff npm run smoke:mcp ``` Real end-to-end verification uses `npm run e2e:real`. It starts or reuses a real Codex App Server, so it should only be executed in an environment where the local Codex Runtime is allowed to run. **Codex Bridge MCP is not just about letting Claude or Codex call Codex once, but about enabling orchestrators to reliably push development tasks from goals to acceptance.**