A Claude Code plugin for coordinating OpenAI Codex agents. Claude plans and verifies the work; Codex handles scoped implementation and review through its CLI.
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.
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.
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.
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.
- 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.
From Claude Code:
/plugin marketplace add alexzh3/codex-orchestrator
/plugin install codex-orchestrator@codex-orchestrator
/reload-plugins
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.
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"]
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.
| Configuration | Regime | Passed |
|---|---|---|
| Plugin v0.4.1 | No timeout | 9/10 |
| Solo Claude Code | Timed | 8/10 |
| Solo Codex | Timed | 8/10 |
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.
- 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.
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.