Codex Orchestrator

Codex Orchestrator

Let Claude orchestrate OpenAI Codex as a supervised implementation executor.

An MCP server that couples Claude (architect, orchestrator, reviewer) with the Codex CLI (executor) through a checkpoint-slice execution model: Codex works in bounded, resumable slices; Claude reviews every checkpoint; a server-enforced state machine guarantees that nothing counts as done until reviews and checks are green. All process state is persisted in SQLite — it survives context compaction, session switches and server restarts.

Current version: 1.5.2

Platform support

Runtime	Status	Distribution
Claude Code CLI	Production ready	First-party GitHub marketplace
Claude Desktop MCPB	Released; technical verification passed	Latest GitHub release, version 1.5.2
claude.ai Remote MCP	In development	Planned for release 1.6.0

The repository ships a production-ready Claude Code plugin and the released Claude Desktop MCPB. Claude Desktop is not a prerequisite for the Claude Code plugin. The Desktop artifact, checksum, startup, MCP handshake, 17 tools, two prompts and Doctor preflight have passed technical verification. The remaining conversation-level slash-prompt run is an operator acceptance check, not an unreleased implementation item. claude.ai cannot start this local stdio server; its separate HTTP/OAuth connector therefore remains in development for 1.6.0.

The externally installed server runtime is continuously verified with Node.js 22.13–22.x and Node.js 24.x on Ubuntu, macOS and Windows. Claude Desktop's built-in Node.js runtime is independent of this external-runtime matrix. The 22.13 minimum is required because the built-in node:sqlite module is available without the --experimental-sqlite start flag only from Node.js 22.13 onward. Every runtime version and coverage floor is defined once under ssot/ (indexed by ssot/index.toml) and bound to each consumer by contract tests. The portable matrix exercises one representative per supported LTS line at its floor (22.13.0 and 24.0.0) across all three operating systems; development and the quality gate run on Node 24 (.nvmrc), while release artifacts are built on the 22.13 floor so a published bundle runs on the oldest supported runtime. The canonical quality gate enforces these production-code coverage floors: 75 % lines, 70 % branches and 75 % functions. CodeQL scans both JavaScript/TypeScript and GitHub Actions workflow code.

---

Why

Letting one model both implement and judge its own work does not scale. This server splits the roles:

• Claude plans, decomposes into clusters with acceptance criteria, picks model + reasoning effort per task, reviews results, maintains hypotheses, and confirms completion.
• Codex implements in sandboxed slices and reports in a structured SLICE_RESULT format — checkpoint, submission, or blocker (never improvising around missing information).
• The server enforces the process: confirm fails without a review and green checks, retrospectives are mandatory between clusters, limits and sandbox rules are fail-closed and unreachable from tool parameters.

A welcome side effect: implementation noise (file contents, diffs, test logs) stays out of Claude's context window — typically 85–95 % fewer Claude-side tokens per delegated implementation task, with state kept in SQLite and compact TOON snapshots instead of chat history.

How it works

flowchart TD
    User(["User"]) --> Claude["Claude<br/>orchestrator + reviewer"]
    Claude -->|"MCP tools"| SM

    subgraph SRV["codex-orchestrator MCP server"]
        direction TB
        SM["Session manager<br/>slice loop, resume, inject, limits, reaper"]
        FSM["State machine<br/>confirm gated on review + green checks"]
        Checks["Check runner<br/>allow-listed commands only"]
        WT["Worktree manager<br/>isolation + gated merge"]
        Store[("SQLite store<br/>plans, clusters, tasks, events,<br/>hypotheses, reviews, checks")]
    end

    SM -->|"codex exec / resume (--json)"| Codex["Codex CLI<br/>sandbox, model, effort per task"]
    Codex -->|"SLICE_RESULT"| SM
    Checks -->|"exit codes"| FSM
    WT --> Git[("git worktrees")]
    Codex --> Git
    SM --> Store
    FSM --> Store
    Checks --> Store