codex-claude-loop
/codex-claude-loop
Use when driving a gated build loop where Claude orchestrates and Codex CLI implements — Claude plans and judges, Codex plans/implements from a persistent thread, with approve-the-plan and review-the-diff gates that refuse to be skipped. For delegating serious multi-file work to Codex instead of one-shot prompts.
- Author
- ozzaii ↗
- Repository
- codex-claude-loop ↗
- Licence
- MIT
- Last repository change
- 26.07.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: lib/codex-claude-loop.sh
What it does and when to use it
Use when driving a gated build loop where Claude orchestrates and Codex CLI implements — Claude plans and judges, Codex plans/implements from a persistent thread, with approve-the-plan and review-the-diff gates that refuse to be skipped. For delegating serious multi-file work to Codex instead of one-shot prompts.
Original author description
Use when driving a gated build loop where Claude orchestrates and Codex CLI implements — Claude plans and judges, Codex plans/implements from a persistent thread, with approve-the-plan and review-the-diff gates that refuse to be skipped. For delegating serious multi-file work to Codex instead of one-shot prompts.
How it works
- The cycle (one brief)
- How to run it
- Autonomous fallback (no orchestrator to gate)
- Rails (load-bearing)
- State
SKILL.md preview
---
name: codex-claude-loop
description: Use when driving a gated build loop where Claude orchestrates and Codex CLI implements — Claude plans and judges, Codex plans/implements from a persistent thread, with approve-the-plan and review-the-diff gates that refuse to be skipped. For delegating serious multi-file work to Codex instead of one-shot prompts.
---
# codex-claude-loop — the gated Claude × Codex build loop
Claude is the principal orchestrator; it rarely types product code. Codex CLI does the
hands-on implementation from **persistent threads**. The whole thing is bash around
`codex exec` — no framework, no MCP, no daemon.
## The cycle (one brief)
```
Claude writes a brief → Codex authors a plan (persistent thread) → back to Claude
→ Claude APPROVES the plan (loop until tight) → Codex implements (same thread)
→ Claude REVIEWS the diff against the plan (loop until clean) → cl_release
```
**The persistent thread is the trick:** the plan Codex authored carries into
implementation, so it implements *its own approved plan* with full context. The approved
plan text is also sent with the implementation instruction, so if a human edited and
re-approved the plan file, the file wins over what the thread drafted.
## How to run it
`source ${CLAUDE_PLUGIN_ROOT}/skills/codex-claude-loop/lib/codex-claude-loop.sh` then use
the phase functions, or call `bash lib/codex-claude-loop.sh <phase> …` directly. Config
via env (`CL_REPO`, `CL_IMPL_MODEL`, `CL_PLAN_MODEL`, `CL_REVIEW_MODEL`, `CL_SANDBOX`,
`CL_LOCK_TIMEOUT`).
0. **First run:** `cl_doctor` (codex/jq/git/sha256 present, the four codex capabilities
the loop needs, repo + schema resolve).
1. **Codex plans:** `cl_plan <slug> <brief.md>` → writes `<slug>.plan.md`, opens a
persistent thread, stores its id.
2. **Claude approves the plan** (judgment — YOU read it): read `<slug>.plan.md`. If tight,
`cl_record_verdict <slug> plan approve "why"`. If not, re-brief and re-plan. Loop until
the plan holds. Prompt yourself to *refute* it, not rubber-stamp it.
3. **Codex implements:** `cl_impl <slug>` → resumes the thread, writes code, runs tests,
holds the writer lock, and records a success marker only if codex exited clean.
4. **Optional same-session follow-up:** `cl_prompt <slug> "<additional request>"` queues
behind the lane's writer lock, resumes the exact stored thread, and prints Codex's
response. It requires a successful implementation and makes re-review mandatory.
5. **Claude reviews the diff:** `cl_review_human <slug>` (rich review you read) — or
inspect `git diff <base>` yourself. Judge it *against the plan*. Approve
(`cl_record_verdict <slug> review approve "why"`) or send the blocking items back into
the same thread with `cl_revise <slug> "…"` and re-review. Loop until clean.
6. **Release:** `cl_release <slug>` confirms both gates still hold for the tree as it is
right now, and refuses otherwise. Then changelog, tag, merge, deploy (honor the
project's own deploy gate).
`cl_status` shows where every slug stands. `cl_wave <slug> <brief.md>` advances one step
per call and returns **3** when it is your turn, **0** when both gates hold — re-run it
after each judgment rather than expecting it to block.
## Autonomous fallback (no orchestrator to gate)
When there is no Claude brain available to judge (e.g. usage cap spent), `cl_codex_gate
<slug>` stands in a **Codex adversarial reviewer** that emits a parseable verdict
(`schemas/verdict.schema.json`, defaults to `revise` unless confident). Use it to keep the
loop moving unattended — but a real orchestrator review is the standard.
## Rails (load-bearing)
- **One writer.** `cl_impl`, `cl_revise`, and `cl_prompt` share one lock; don't bypass it.
Two Codex processes writing the same tree = corruption.
- **Never review a tree that is being written.** Both review paths refuse while the lock
is held. To genuinely overlap review and implementation, give each lane its own
worktree and its own `CL_REPO`.
- **Gates must refute, not rubber-stamp.** A gate that always approves is worse than no
gate. Blocking items need concrete fixes, and `approve` with a non-empty blocking list
is downgraded on disk.
- **A revise round is not closed by a matching sentence.** Every item you send back with
`cl_revise` is kept and handed to the next review, which is told to judge it on intent.
When you review, do the same: ask what the item was trying to prevent, then check the
code prevents it. A change that satisfies the wording and misses the point stays blocking.
- **Approvals are bound to what they judged.** Editing the plan voids its approval;
changing the tree voids the review approval. If a re-approval is refused, read the
reason rather than deleting state to make it pass.
- **The plugin guards git publication.** Normal Claude Code Bash calls for `git commit`,
`push`, `merge`, and `tag` are refused while a successful implementation is not covered
by both current approvals. The standalone skill install has no hook; neither path binds
a human terminal or deliberately wrapped git commands.
- **Verify model variants before architecting on them.** Set `CL_IMPL_MODEL` /
`CL_REVIEW_MODEL` only to models you have actually confirmed behave as you assume.
- **Tail the log within a minute of launching any lane.** A bad flag makes `codex exec`
die into its jsonl while you believe a lane is running.
- **First run = `cl_selfreview`:** have Codex adversarially tear apart THIS harness before
you trust it.
- Honor the repo's own rules (branch protection, deploy gates, secrets never printed).
## State
`~/.codex-claude-loop/<repo>-<hash of its path>/` — plans, verdicts, thread ids, base
SHAs, JSONL logs. Outside the repo so it never pollutes a tree Codex is writing, and keyed
by path so two repos with the same basename never share approvals. Override with
`CL_STATE`.
Files in this package (3)
- SKILL.md 6 KB
- lib/codex-claude-loop.sh 54 KB
- schemas/verdict.schema.json 1 KB
Versions
The database has no other skills named codex-claude-loop.
Database snapshot: 13.11.2026 · package version 90f1bf6d2b22 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100review
Cross-model orchestration between Claude Code and a local Codex CLI. Claude orchestrates, plans, and reviews; Codex implements and provides an independent second opinion. Use when you want two different model families to cross-check work rather than one model reviewing itself. - 90Codex Integration
Use this skill when delegating complex coding tasks to OpenAI Codex CLI and coordinating work between Claude and Codex. - 100harness
Orchestrator/worker/validator engineering loop. Claude orchestrates from an indexed project knowledge base, Codex CLI implements in a sandbox, the Validator agent gates every change, TASK.md tracks progress so sessions can resume, and learnings persist to MEMORY.md and the… - 90build-loop-codex
Use when building features with **Codex** (OpenAI Codex CLI) in any codebase and the work should go through a disciplined build → review → test → fix loop. Triggers on "run the build loop", "build the next task", "continue the plan", "build this feature properly", or any request… - 100codex-review
Run a bounded adversarial review of an existing implementation plan: Claude revises PLAN.md while Codex critiques it read-only in one persistent session. Use for /codex-review, "Codex review my plan", or high-stakes plans involving auth, schema, concurrency, migrations, or… - 100codex-orchestrate
Claude Code only. Use when the user explicitly invokes /agents-bridge:codex-orchestrate (or /codex-orchestrate) in Claude Code or asks Claude to orchestrate a large multi-slice plan by delegating implementation to the Codex CLI through agents-bridge. In native Codex, use $slice-runner instead.