Skip to content
Skills Library
AI & agents · Automation

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.

Licence
MIT
Last repository change
26.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. The cycle (one brief)
  2. How to run it
  3. Autonomous fallback (no orchestrator to gate)
  4. Rails (load-bearing)
  5. State
Original SKILL.md headings · 94 lines, 842 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.