Claude–Codex Orchestrator Plugin

A Claude Code plugin for coordinating OpenAI Codex agents. Claude plans and verifies the work; Codex handles scoped implementation and review through its CLI.

What It Does

Use this plugin when you want Claude Code to supervise Codex rather than manually relay context between the two tools. It helps Claude:

• assign or resume scoped Codex agents;
• monitor active Codex agents;
• preserve exact prompts, event streams, and handoffs;
• independently verify results and record consequential decisions.

Why This Approach?

1. Different Models Catch Different Mistakes

Claude and Codex come from different model families and harnesses, so they can catch different mistakes. Work on heterogeneous ensembles—including LLM-Blender, Mixture-of-Agents, and FrugalGPT—supports combining distinct models while warning against blind majority agreement. This plugin asks Claude to resolve disagreements from inspectable evidence rather than model votes.

2. Claude Maintains Global Context

Claude tracks the overall goal, agent history, verification, and decisions while Codex receives focused execution tasks. Anthropic's 1M context release supports using Claude for this broader context.

Large context windows are not enough on their own. Context Rot shows that performance can decline as context grows. Durable prompts, handoffs, repository state, and journal entries preserve the context that matters.

3. Native Harnesses Matter

Agent performance depends on more than the underlying model. Shell and file access, session history, approvals, sandboxing, event streams, and harness-specific prompting all affect the result. The Terminal-Bench 2.1 leaderboard reflects this by evaluating agent-and-model pairs rather than models in isolation. The plugin therefore lets Codex work through its native CLI while Claude remains in Claude Code as planner, orchestrator, and reviewer.

Requirements

• Claude Code in an IDE or terminal.
• OpenAI Codex CLI.
• Python 3.10 or newer for the bundled tools.
• A Git repository.
• A meaningful verification path such as tests, typecheck, lint, build, benchmark, screenshot, or manual inspection.

Installation

From Claude Code:

/plugin marketplace add alexzh3/codex-orchestrator
/plugin install codex-orchestrator@codex-orchestrator
/reload-plugins

Usage

Use orchestrate for one focused phase and workflow for the complete end-to-end process.

For example, to review a change within an existing run:

/codex-orchestrator:orchestrate

In run <run-id>, have a fresh Codex agent review commit <sha> against its task requirements.
Do not modify the target. Independently verify every material finding.

The operating instructions live in skills/orchestrate/SKILL.md, skills/workflow/SKILL.md, and skills/report/SKILL.md.

Workflow

The /codex-orchestrator:workflow command runs this full flow, from planning and scoped execution through verification and reporting:

flowchart TD
    A["Claude plans"] --> B["Codex reviews the plan when useful"]
    B --> C["Claude assigns scoped work"]
    C --> D["Codex implements or reviews"]
    D --> E["Claude verifies the result"]
    E -- "issues found" --> F["Codex fixes"]
    F --> E
    E -- "accepted or blocked" --> G["Claude makes the final judgment"]
    G --> H["Claude writes the final report"]

Run Layout

Runs live under .codex-orchestrator/runs/<run-id>/. Before creating a run, the workflow adds /.codex-orchestrator/ to the repository's local .git/info/exclude and verifies it is ignored; it does not modify the tracked .gitignore.

journal.jsonl
codex-impl-01/
  execution-01/
    prompt.md
    events.jsonl
    handoff.md
evidence/                 # optional
report.md                 # written by Claude after run closure

Each top-level agent directory is a persistent execution context. Every prompt, event stream, and handoff cycle gets the next numbered execution; resuming a native session creates another execution under the same agent. Each execution keeps the exact prompt, raw Codex events, and final handoff together so that each execution can be inspected later.

journal.jsonl is the compact index for the run, evidence/ holds optional supporting evidence, and report.md contains Claude's final summary. The detailed journal format, trust boundaries, and closure flow are documented in docs/orchestration-contract.md.

Historical v0.4.1 Benchmarks

These historical results are directional, not statistically reliable or like-for-like: each configuration ran only once per task, the plugin had no timeout while the solo baselines were timed, and prompt-first v0.5.0 has not been evaluated. See docs/benchmarks.md for the methodology and limitations.

Limitations

• Sequential review and fix loops may take longer than using one agent.
• Parallel work requires isolated files, resources, or worktrees.
• Conclusions are only as reliable as the available checks and evidence.

Security And Privacy

This plugin supports bounded autonomy, not unrestricted execution. Use workspace-write for normal Codex work and require explicit authorization for network access, out-of-workspace writes, Docker socket access, deployments, credentials, or expensive compute. Broad access belongs in a trusted, externally hardened container or VM.

The plugin adds no telemetry of its own. Data handling follows the configured Claude Code and Codex environments, which may inspect files, prompts, event streams, diffs, command output, and evidence you make available. Keep secrets, credentials, private keys, .env files, and sensitive production data out of scope unless you intentionally configured access.