codex-orchestrator

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.

Command	Purpose
/codex-orchestrator:orchestrate	Run a focused execution, review, monitoring, or verification phase within a run.
/codex-orchestrator:workflow	Run planning through execution, verification, closure, and report.
/codex-orchestrator:report	Author report.md from an already closed run.

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