Codex Claude Loop

---
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`.