When Codex doesn't know what "done" means, it reviews Claude Code's commit against its own taste. It flags style, misses the one requirement that mattered and finds something new every round. The loop never ends, or it ends because you got tired.
That's the weak spot in the basic loop from my last post: Claude Code writes in its own worktree, Codex reviews the commit read-only, the tests run on that same commit, and a script refuses the merge unless both pieces of evidence exist.
This post fixes it with three things: a definition of done the reviewer checks line by line, house rules it checks the same way, and round rules so the loop stops. All three go into every review on my own projects. It also covers where OpenAI's official Codex plugin fits.
The setup in one paragraph
Claude Code writes. It commits each change on a branch and stops. Codex reviews that commit in a read-only sandbox: it can read files and run read-only commands like git diff, but it can't write anything. The prompt tells it never to hand back a patch, so every fix goes back to Claude Code as a new commit, and the new commit gets a new review. The verdict is one line, Verdict: ACCEPT or Verdict: CHANGES REQUIRED, saved in a file named after the commit it reviewed.
The paid Two Engines Kit has the review script and merge check I run on my own projects. Steps 1 to 5 sit on top of it, or on top of your own scripts.
The official Codex plugin
OpenAI's Codex plugin for Claude Code starts a Codex review without leaving Claude Code. It runs through your local Codex CLI, with the same install, sign-in and config. The details below are from its README and prompt files as of 9 Nov 2026.
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup
/codex:setup tells you whether Codex is ready. If Codex isn't logged in, run !codex login.
Two read-only commands start a review:
-
/codex:reviewreviews your uncommitted changes, or your branch against a base with--base main. It isn't steerable and takes no custom focus text. -
/codex:adversarial-reviewtakes focus text after the flags and doesn't fix code. Its prompt asks only for material findings and rules out style feedback, naming feedback, low-value cleanup and speculative concerns without evidence.
/codex:setup --enable-review-gate turns on an optional review gate, and --disable-review-gate turns it off. With the gate on, a Stop hook runs a targeted Codex review based on Claude Code's response and blocks the stop if that review finds issues. The gate's prompt reviews only the previous turn, and only if that turn made direct edits. It requires every blocking claim to be grounded in the repository or in tool output Codex inspected, and the answer to start with ALLOW or BLOCK and a short reason. The README warns that the gate can create a long-running loop between Claude Code and Codex and may drain usage limits quickly, and says to enable it only when you plan to actively monitor the session.
The README doesn't document a definition of done, house rules, round rules, a verdict saved under the reviewed commit, a test run on that commit or a merge check that refuses without both, and the rest of this post covers those. The gate's prompt judges one turn of edits, while this loop's verdict file names a commit, so the merge check can ask whether that commit was accepted and tested. Step 4 caps the rounds and leaves the last call to a person.
Step 1: write the brief before the code
Most review noise starts before any code exists. If the only instruction Claude Code got was "add CSV export", the reviewer has nothing to check the result against except its own opinion.
So every task starts with a short brief. Mine has four parts:
# Brief: CSV export for the orders page
## Done means
1. A "Download CSV" button on /orders downloads the orders currently
shown, with the current filters applied.
2. Columns, in order: id, created_at (ISO 8601, UTC), customer_email,
total (two decimals, no currency sign), status.
3. A customer email that contains a comma or a quote is escaped, so
the file opens in a spreadsheet with the right columns.
4. A new test covers point 3 and fails on the code before this change.
## Must not change
- The JSON response of GET /api/orders.
- Existing filters and their URL parameters.
## How it is checked
- Point 1: the route and the button in the diff.
- Points 2 and 3: the new test.
- Point 4: the test run once against the base commit, output pasted
in the commit body.
## Out of scope
- Exports for other pages. Scheduled exports.
Every line under "Done means" has to be something a reviewer can confirm from the diff or from a test. A reviewer can't confirm "Export works well" from a diff, but it can confirm "A customer email with a comma is escaped".
Point 4 is worth stealing on its own. The engine that writes the code often writes the tests too, and a test that already passes on the old code proves nothing about the change. Ask the writer to run each new test once against the base commit and show that it failed there.
Commit the brief with the change, or keep it under .ai/. My gate refuses to review a checkout with uncommitted changes or untracked files anywhere else, and it skips .ai/ so working files like this one can live there. If you add .ai/ to your .gitignore, commit that change too, or the edited .gitignore itself gets the review refused.
Step 2: house rules the reviewer can grep for
The brief covers this task. House rules cover every task: how errors are handled, where config lives, what never goes into a log.
Write them like the brief, as things a reviewer can find in a diff:
## House rules
- No new dependency without a line in the commit body saying why.
- Config comes from environment variables read in config.ts only.
No process.env anywhere else.
- Never log a full email address, token or request body.
- User-facing strings go through t(), not hard-coded text.
Put them in the files both engines already read: CLAUDE.md for Claude Code, AGENTS.md for Codex. The writer follows them while writing, and the reviewer checks against the same text. Keep the AGENTS.md section short: Codex stops adding instruction files once their combined size reaches project_doc_max_bytes.
Step 3: make the reviewer answer every line
Instead of "review this diff", ask for an answer per line:
The brief for this change is in .ai/brief.md.
For each line under "Done means" and each house rule, answer one of:
- met: give the file:line in the diff that shows it
- not met: give the file:line and what is missing
- not checkable: say what evidence would be needed
Treat the commit message and the writer's summary as claims to verify,
not as evidence. If a section is empty, say "not given" instead of
guessing what it should have said.
Findings outside the brief and the house rules need a concrete failure:
the input or steps, and what goes wrong. Style preferences are not
findings.
Keep the verdict rule: one line only, Verdict: ACCEPT or
Verdict: CHANGES REQUIRED. ACCEPT only when every line above is met.
With the kit, add this to its review prompt template. With your own scripts, append it to whatever prompt you send Codex.
A "not checkable" answer is a finding about your brief: you wrote a requirement nobody can verify.
Step 4: cap the rounds
Without round rules, a reviewer at high effort can find a new nit every round, and the change never lands. So each round gets one job:
- Round 1 lists every finding, with nothing held back for later.
- Round 2 confirms the fixes and may only add what the fixes broke.
- Round 3 and later: only blockers and security findings hold the merge. A blocker needs a failure you can reproduce. Everything else is a nit for a follow-ups file, and the reviewer can accept.
- At the cap: if the last allowed round says CHANGES REQUIRED, stop sending fixes. The verdict stays CHANGES REQUIRED, so the merge stays blocked until a person decides: change the approach, split the change, or allow one more round on purpose.
Add the rules to the prompt:
Round rules. Round 1: list every finding. Round 2: confirm the fixes and
add only what the fixes broke. Round 3 and later: only blockers and
security findings may hold the merge. Mark everything else as a nit for
the follow-ups file.
The reviewer also needs to know which round it's in. Count rounds in a small file per change:
#!/usr/bin/env bash
# rounds.sh <change-name>: count review rounds for one change; exit 3 at the cap
name="${1:?usage: rounds.sh <change-name>}"; max="${MAX_ROUNDS:-3}"
case "$max" in ''|*[!0-9]*) echo "MAX_ROUNDS must be a whole number" >&2; exit 1 ;; esac
root="$(git rev-parse --show-toplevel)" && cd "$root" || exit 1
f=".ai/reviews/$name.rounds"
mkdir -p .ai/reviews
n=0; [ -f "$f" ] && n=$(wc -l < "$f")
n=$((n + 1))
if [ "$n" -gt "$max" ]; then
echo "last round reached for $name; a person decides" >&2
exit 3
fi
echo "$n $(git rev-parse --short=12 HEAD) $(date -u +%FT%TZ)" >> "$f"
echo "round $n of $max"
With your own scripts, a short wrapper feeds the count into the prompt. Save it as review-round.sh next to rounds.sh in the root of your repository, and run it from there:
#!/usr/bin/env bash
# review-round.sh <change-name>: one counted review round with your own review script
round="$(bash rounds.sh "$1")" || exit
{ cat path/to/your/review-prompt.md; printf '\nThis is %s.\n' "$round"; } > .ai/prompt.md
path/to/your/review.sh .ai/prompt.md
Commit both scripts, or list them in .gitignore and commit that change, so the gate doesn't refuse them. The .rounds file and .ai/prompt.md they write sit under .ai/, which the gate skips.
A review that fails without any verdict uses up a round too. Delete the last line of the .rounds file before you rerun it.
Step 5: when Claude Code and Codex disagree
Sometimes the writer pushes back on a finding, and sometimes it's right. Don't let the two engines argue it out over five rounds. Use one rule: a finding stands if it comes with a reproducible failure, and goes to follow-ups if it doesn't. Anything the brief doesn't settle, like scope or anything a user would see, is your call. That costs you one short question instead of another review round.
What this doesn't do
None of this makes code correct. A reviewer can mark a line "met" and be wrong, and tests only check what they test.
Try it
To build the loop yourself, you need the read-only review, the verdict named after the commit, the test pass record and a merge check that refuses without both. Add the "Done means" section, the house rules and the round rules to the prompt you send Codex, put rounds.sh and the wrapper in your repository root, and you have the whole loop from this post.
If you want the full workflow I use on my own projects, get the Two Engines Kit. I've been building it since the first Codex and Claude CLIs. On top of the review and the merge check, it adds:
- one rulebook that Claude Code and Codex both load
- hooks and settings for both engines
- a GitHub merge script pinned to the commit that was checked, so GitHub merges nothing if the branch head moved
- an installer that previews every change and can be undone byte for byte
If you'd rather have someone else wire it up, I set up Codex to review your Claude Code commits before they merge: that's the Codex review setup. The review setup is written from scratch for your repository, its stack and its conventions, then the first review runs on one of your real branches. Nothing is copied from a template or from the Two Engines Kit.
Top comments (0)