codex-mcp

Plan with Claude · Execute with OpenAI Codex · Review with Claude

A Claude Code plugin and MCP server that runs a disciplined plan → execute → review loop: Claude interviews you and designs the plan, Codex writes the code, then Claude reviews each task and the final pass alongside a required Codex codex_review; findings are compared, fixes go back, and non-blocking improvements wait for your decision — all from a single command.

 ·  macOS · Windows · Linux  ·  Node ≥ 20  ·  MIT

Quick start

1. Prerequisites — Node ≥ 20 and the Codex CLI, authenticated:

npm i -g @openai/codex
codex login          # ChatGPT Plus/Pro/Team — or set OPENAI_API_KEY

2. Install the plugin (bundles the /codex-flow command + the codex MCP server):

/plugin marketplace add anhnguyen0905/codex-mcp
/plugin install codex-flow@codex-mcp

3. Run it in any project:

/codex-flow implement a dark-mode toggle on the settings page

# from npm (recommended — ships a prebuilt dist, nothing to compile)
claude mcp add --scope user codex -- npx -y @anhnguyen0905/codex-mcp
# or straight from this repo, which builds from source on first run
claude mcp add --scope user codex -- npx -y github:anhnguyen0905/codex-mcp

claude mcp list should then show codex … ✔ Connected. Copy commands/codex-flow.md to ~/.claude/commands/ for the workflow command, or just use the plugin install above which bundles both.

The plugin is distributed as a git clone and dist/ is gitignored, so up to v0.14.0 a freshly installed plugin had no build and its node dist/index.js launcher exited immediately.

Since v0.15.1 the bundled .mcp.json runs the published npm tarball (npx -y @anhnguyen0905/codex-mcp@<version>), which ships a prebuilt dist/ — nothing is compiled at install time. Updating the plugin is the fix:

/plugin update codex-flow@codex-mcp

If you are pinned to an older version, patch that install once instead:

cd ~/.claude/plugins/cache/codex-mcp/codex-flow/<version>
npm install --no-audit --no-fund && npm run build

Then restart Claude Code and confirm with claude mcp list (or call codex_health).

Related MCP server: MCP-Claude Code Bridge

How it works

Claude Code ──(MCP stdio)──▶ codex-mcp ──spawns──▶ codex exec --json

/codex-flow runs six phases, keeping Claude as the planner/reviewer and Codex as the implementer:

The bundled session-report skill writes a per-session bundle to .codex-flow/reports/<YYYYMMDD-HHMMSS>/ with planning, allocation, task, cost, and summary reports plus explicit claude / codex / both PIC attribution.

The server spawns codex exec non-interactively, parses its JSONL event stream, and returns a structured result (sessionId, agentMessage, fileChanges, commands, token usage, diff).

Highlights

Index-based skill selection

Instead of blind-loading whole skill collections, /codex-flow selects only the skills a task needs from a local index: it classifies the request's role facets (engineering, data, marketing, growth, research, design…) and loads every relevant skill that fits a context budget (~3% of the window), embedding distilled rule blocks into the Codex prompts. Skills on disk cost zero context until selected; third-party skills are vetted once before first use.

The index covers ~/.claude/skills, ~/claude-skill-library, and the skills/ dir of every installed plugin (newest version per plugin) — so selection knows about skills the machine already has instead of reporting a gap. And a domain facet never ends with zero skills: when nothing indexed fits, Step 7 re-indexes, vets, searches (gh/catalog/web), and — failing all of that — authors the missing SKILL.md before execution, so the library grows toward the work.

node scripts/sync-awesome-skills.mjs --clone   # build a local library from awesome-claude-skills
node scripts/build-skills-index.mjs            # → ~/.claude/skill-library/INDEX.md

Besides the phase skills, the plugin ships 15 domain skills authored through Step 7 — paid media, unit economics, media planning, warehouse modeling, event taxonomy, attribution, causal inference, survey design, ASO, localisation, OKRs, creative briefs, influencer strategy, SOPs and data-quality checks — so they are indexed and selectable out of the box. Their numeric thresholds are labelled derived, unverified: replace them with your own account history before treating any of them as a target.

Verified by a 32-scenario scope eval (npm run skills:eval) — latest 32/32 — plus a 100-request non-engineering scope run (data analysis, marketing planning, performance marketing, market research, content, product): 99/100 covered by an existing skill, at precision@1 84/99, with the remaining case queued for Step 7 acquisition/authoring. Full procedure: skills/skill-selection/SKILL.md.

Parallel execution for large backlogs

codex-mcp serializes runs per workspace but parallelizes across workspaces, so independent tasks can run concurrently — each in its own git worktree driven by a Claude subagent, then merged and integration-reviewed per wave.

npm run waves                                  # compute execution waves from .codex-flow/TASKS.md

Waves batch tasks whose dependencies are met and whose files are disjoint, capped at 10 concurrent subagents (--max <n> to lower). Parallel is the default when task-waves reports width > 1: waves of ≤3 run automatically, while wider waves ask first; parallel execution costs N× simultaneous quota. Playbook: skills/parallel-execution/SKILL.md.

Tools

codex_execute / codex_continue / codex_review accept writeNotes: true to persist a markdown summary of the run to <cwd>/.codex-flow/notes/<sessionId>.md.

codex_execute / codex_continue / codex_review and each codex_batch task accept reasoningEffort: minimal | low | medium | high | xhigh, passed to Codex as -c model_reasoning_effort="<value>".

Sandbox modes: read-only, workspace-write (default), danger-full-access. Default execution timeout is 60 min (timeoutMs caps at 2 h). Runs into the same cwd are serialized; different workspaces run in parallel.

By default, the server automatically resumes the same session after a transient turn failure (at most 2 resumes), timeout (at most 1), or partial result caused by a missing completion marker or parse errors (at most 1, reported as no-completion-marker), with 2 s then 8 s backoff (8 s for any later resume). Set CODEX_MCP_AUTO_RESUME=0 to opt out.

Every run tool returns sessionId, agentMessage, fileChanges, commands, token usage, errors, plus:

• diff — git status --porcelain + git diff HEAD after the run (64 KB cap, truncated flag; null outside a git repo) so the caller can review without re-reading files.

• aborted — true when cancelled from the client (Esc in Claude Code); the server forwards cancellation to Codex (SIGTERM → SIGKILL after 5 s).

• attempts / resumeReasons — total attempts and the ordered reasons for automatic resumes; each codex_batch task result carries the same fields.

• liveLog — path to the raw JSONL event log when the live terminal view is enabled.

Clients that send an MCP progressToken (Claude Code does) get notifications/progress for every meaningful Codex event. Set terminal: true (or CODEX_MCP_TERMINAL=1) to also open a live-tailing window — Terminal.app on macOS, PowerShell on Windows, the first available emulator on Linux. On macOS, the window closes itself about 4 seconds after a successful run; it stays open after a failed or interrupted run. The delay defaults to 4000 ms; 0 closes immediately, and values above 60000 are clamped. Windows and Linux windows already close with their process. If no window can open, the run still succeeds; follow the liveLog or the in-session progress instead.

Configuration

Security: the server never reads, stores, or transmits your credentials — auth is handled entirely by the Codex CLI (~/.codex/). Run npm run doctor to verify your setup.

Development

npm test          # unit tests (vitest)
npm run coverage  # enforces 80% thresholds
npm run build     # tsc → dist/
npm run test:e2e  # real end-to-end smoke test (spawns Codex, uses quota)

Server (src/): index.ts (stdio entry) · server.ts (MCP tools, cwd lock, cancellation) · argsBuilder.ts (argv) · codexRunner.ts (spawn + timeout/kill) · eventParser.ts (JSONL → result) · workspaceDiff.ts (git diff) · terminal.ts / liveView.ts / progressFormatter.ts / progressNotifier.ts (live progress).

Skill & workflow scripts (scripts/): sync-awesome-skills.mjs · build-skills-index.mjs · skill-match.mjs · skill-eval.mjs · task-waves.mjs · session-cost.mjs · tail-progress.mjs.