codex-claude-loop

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

1. First run: cl_doctor (codex/jq/git/sha256 present, the four codex capabilities the loop needs, repo + schema resolve).
2. Codex plans: cl_plan <slug> <brief.md> → writes <slug>.plan.md, opens a persistent thread, stores its id.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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).