One model builds. Another checks. Claude decides.
A Claude Code skill that splits work into slices, has Claude or Codex execute each one, has the other model review it, and then makes Claude reproduce every review finding before anything is committed. It works for code and for papers.
Project page · Changelog · Real-run example
flowchart LR
P["Plan<br/>Claude"] --> E["Execute<br/>Claude or Codex"]
E --> R["Review<br/>the other model"]
R --> C{"Confirm<br/>Claude"}
C -- "no valid blocker/major" --> G["commit slice"]
C -- "valid finding, round < 2" --> E
C -- "round 2 still failing" --> U["ask you"]
Why
- A model reviewing its own output tends to agree with itself. A different model family catches different mistakes.
- Reviewers also make claims they cannot back up. So a review is evidence, not a verdict: Claude reruns the tests, opens each quoted line, and marks every finding VALID or INVALID.
- Everything goes through files in
.colab/, so executors and reviewers never see the conversation, and a crashed session can resume from STATE.md.
Why it calls the Codex CLI instead of the Codex plugin
OpenAI's Codex plugin for Claude Code is built for handing Codex a task and getting its answer back. coClaudex uses Codex as one role in a pipeline, which needs control over each call, so scripts/codex_run.py runs codex exec directly:
- Executors run with
--sandbox workspace-write, reviewers with read-only.
- Reviews come back as JSON checked against a schema (
--output-schema), so findings can be counted and confirmed one by one.
- Every call sets the model and reasoning effort for its tier from
config.json, and moves to the newest model of the same family when Codex lists one.
- A crashed run resumes its own Codex thread by id (
--resume <thread_id>), not just the latest one.
- The
--json event stream gives time and tokens per run (codex_run.py stats), and a watchdog stops a run that stalls.
How it works
- Plan. Claude writes
.colab/PLAN.md: requirements, then slices of about half an hour each, each with a file scope, steps, and acceptance commands. You approve it.
- Choose. For each slice you pick a combo and a tier (or apply one choice to the whole phase).
- Execute. The executor gets a self-contained handoff plus strict rules: touch only the listed files, never run git, never weaken tests, report
BLOCKED instead of improvising.
- Review. A fresh, read-only reviewer returns schema-checked JSON. Every finding carries a severity and quoted evidence.
- Confirm. Claude reproduces findings, adds anything missed, and either commits the in-scope files or sends the slice back with a Rework section. After two rounds it escalates to you.
Combos
| reviewed by Claude | reviewed by Codex |
|---|
| Claude executes | A | B: judgment-heavy slices |
| Codex executes | C: well-specified slices | D |
Tiers
| tier | Codex exec | Codex review | Claude exec | Claude review |
|---|
| light | luna, medium | sol, low | sonnet, low | opus, low |
| standard | luna, high | sol, medium | sonnet, medium | opus, medium |
| heavy | sol, medium | sol, high (×2) | opus, medium | opus, high (×2) |
| overkill | astra, medium | astra, medium (×2) | fable, medium | fable, high (×2) |
| test | luna, low | luna, low | haiku | haiku |
Heavy and overkill add a second reviewer with a different focus. Overkill is the only tier that uses gpt-6-astra and Claude Fable; Fable needs usage credits on top of a Claude plan. test is for dry runs only. Execution and review can use different tiers (for example opus writes, sol reviews). Paper slices execute with a stronger fixed model on every tier except test. Edit skills/coclaudex/config.json to change the mapping. Codex models follow new releases on their own: when Codex lists a newer gpt-<version> model of the same family (luna, sol, astra), that one runs instead. Set codex.auto_latest to false to pin the exact names.
Install
Requires Claude Code, git and Python 3. Codex CLI (logged in) is needed for combos B, C and D.
As a plugin (recommended). In Claude Code:
/plugin marketplace add YuxiaoMa66/coclaudex
/plugin install coclaudex@coclaudex
Restart Claude Code once afterwards. Update later with /plugin marketplace update coclaudex.
From a clone (to hack on it). Symlinks keep your edits live:
git clone https://github.com/YuxiaoMa66/coclaudex.git
cd coclaudex
ln -s "$PWD/skills/coclaudex" ~/.claude/skills/coclaudex
for f in agents/coclaudex-*.md; do ln -s "$PWD/$f" ~/.claude/agents/; done
Use one method, not both.
Use
Run it from a session on Opus or stronger. The session model writes the plan and confirms every finding, and a weak plan cannot be rescued by a strong executor, while an executor's mistakes get caught by tests and review. So spend on the planner and keep executors cheap; coClaudex recommends a higher execution tier for slices typed debug.
In any git repository, ask Claude Code:
coclaudex: add rate limiting to the API. Plan it in slices, Codex executes, Claude reviews.
Useful commands while a run is going:
python3 <skill dir>/scripts/codex_run.py stats # time and tokens per run
python3 <skill dir>/scripts/codex_run.py preflight # is Codex reachable?
.colab/ is excluded from git through .git/info/exclude and kept as the audit trail: plan, state, handoffs, raw runs, reviews and confirmations.
A real run
Six slices on antigravity-mission-control, a Python CLI with 64 tests, ending in a merged pull request. The full audit trail is in examples/agy-mission-control.
- Too lenient. A Claude reviewer passed pytest-style tests as a style nit. CI runs
unittest without pytest, so the 14 new tests would never have run. Confirmation caught it and sent the slice back.
- A miss. A new
prune command treated cancel_failed jobs as finished, although their worker may still be alive. Neither reviewer raised it; the orchestrator did.
- Too strict. In round 2 a Codex reviewer rated symlink races as blockers. Checked against the threat model, they became minor follow-ups, and the reasons are on file.
- Escalations that worked. Twice a slice hit the two-round limit with a valid finding left. coClaudex stopped and asked, and the root cause ended up as one check in a shared function instead of a patch per call site.
- End state: 103 tests pass, 39 of them new, after about 36 minutes of agent time.
Earlier tests
From a fault-injection run (test tier) and two paper runs:
- A cheap reviewer passed a CLI that crashed on
--top -1; confirmation reproduced it and forced a rework.
- An executor given a CLI task without
cli.py in scope reported BLOCKED instead of editing it.
- After the orchestrator and Codex were killed mid-slice, a fresh session with only
STATE.md resumed the Codex thread and finished.
- A planted wrong venue in a
.bib file was caught by Codex with web search. A Haiku reviewer passed without searching until the template required Citations verified online: k/n.
- About 89% of Codex executor input tokens were cached, so the fixed per-call overhead is small.
Layout
skills/coclaudex/ SKILL.md, config.json, scripts/codex_run.py, templates/, schemas/
agents/ Claude executor and reviewer subagents (model and effort in frontmatter)
.claude-plugin/ plugin and marketplace manifests
docs/ project page (GitHub Pages)
License
MIT. Independent project, not affiliated with Anthropic or OpenAI.
