DEV Community: Iliya Oblakov

How to check whether ChatGPT and Google AI Overviews name your local business

Iliya Oblakov — Fri, 23 Oct 2026 11:55:27 +0000

If you own or market a clinic, a law firm or a service company in a UK or US city, your next client may ask ChatGPT or Google for the best [your type of business] in that city and get a short list of names. If you have never checked whether your business is on that list, this post shows you how to check it yourself with a browser and a spreadsheet. Below is the method I use and what it showed on a real med spa on 23 October 2026.

Why one question asked once tells you very little

AI answers change. Ask an engine the same question twice and it can name different businesses. Engines also guess where you are from your connection when the question has no place in it. So use fixed questions with the place name in each one, ask them the same way every week and log every answer in the same columns.

Step 1: write 10 fixed buyer questions

Write the questions a real client would type: 8 general ones and 2 that use your business name. Here is the template I use. Fill in the brackets once and then never change the wording, because a reworded question can't be compared with last week's answer.

What are the best [type of business] in [city]?
Where can I get [main service] in [neighbourhood], [city]?
Which [city] [type of business] offer [service] packages?
[Service] near [neighbourhood], [city]: which ones are good?
Which [city] [type of business] have [something you offer, such as a monthly membership]?
Where can I get [second service] in [city]?
Best [service] for [problem] in [city]: which [type of business]?
I want a top rated [type of business] in [neighbourhood], [city] for a first visit. What do you recommend?
What is [business name] in [city] known for?
What is the address, phone number and opening hours of [business name] in [city]?

Put the city in every question. In my med spa run, question 8 named two neighbourhoods and left the city out. Both ChatGPT and Google answered it for places with the same names in another state, so that answer said nothing about the business I was checking. My connection was in Bulgaria, which is one more reason the engine can't be left to guess the place.

Step 2: run them the same way every week

Open a private browser window and stay logged out.
Start a new chat for every question in ChatGPT, and never ask a follow-up. In my run ChatGPT searched the web on its own, without a toggle.
In Google, search the question exactly as written and read the AI Overview at the top. If no Overview shows, write that down, because that is a result too. Stay out of AI Mode, since it is a different product.
Paste each question from your list instead of retyping it, and save the full answer and a screenshot.

Step 3: log the same columns for every answer

One row per answer. Here is the table, with three real rows from my med spa run. Names are left out.

Date	Engine	Question	Named?	Site cited or linked?	Position	Named instead	Facts right?	Notes
23 Oct	ChatGPT	3, laser hair removal packages	yes	yes	1st	5 others	n/a
23 Oct	Google AI Overviews	2, Botox in a neighbourhood	no	no		4 others	n/a	first in the map pack under the Overview
23 Oct	Google AI Overviews	10, address, phone and hours	yes	yes			no, Saturday hours wrong	hours match a directory site

Fill in "Facts right?" for questions 9 and 10 only. Check every fact the answer states against your own website and your Google Business Profile. Write the names in "Named instead" in the order the engine gave them.

What one run on a real med spa showed

I ran this list for a med spa that is not a client, logged out, in ChatGPT and Google AI Overviews.

Of the 8 general questions, ChatGPT named the med spa in 3 and the Google Overview named it in 1. In one of the 3 ChatGPT answers it appeared only as a pin on the map, with no mention in the text.
In one Google search the med spa was missing from the Overview but came first in the map pack under it. Log the map pack in your notes column, because it is a separate result from the Overview.
Both engines named it for both questions asked by name and linked its website each time.
ChatGPT got the address, phone and hours right. The Google Overview said Saturday was 11 AM to 4 PM. The med spa's homepage says Saturday is by appointment only, its own contact page showed a different Saturday time again, and the hours in the Overview matched a third-party directory listing.
For "What are the best med spas in [city]?", the sources ChatGPT showed were three med spa directories, Yelp and Google. The business's own website was not among them.

That is one run. The plan for this sample is 3 runs on 3 different days, and I'd want all three before calling anything a pattern.

What to do with the log

Start with the facts column. If an engine gets your hours wrong, compare the hours on your homepage, contact page, Google Business Profile and directory listings, and make them all match. Then check your listing on the directories the engines cite.

Check your own site's code too. In a check of 50 med spa homepages in October, at least 27 gave no street address in their structured data and 11 got the business name wrong there. That study asked no AI engine anything, so it shows missing facts on sites and says nothing about who gets named.

Get the full audit

If you run a clinic, a law firm or a service company in a UK or US city and want this done properly, the AI Visibility Audit is the same method run in depth. I write your city into every prompt and run each prompt 3 times in each engine in your package, on 3 different days, with a fresh browser session and a new chat each time. You get screenshots of what the engines answered and which businesses they named instead of you, a check of your Google Business Profile and how you show in the map pack, your reviews compared with 3 local competitors, a technical check of up to 50 pages of your site and a list of the questions clients ask that your site never answers. All of that becomes a prioritized list of fixes, and each fix says who should do it. The report arrives 3 to 5 business days after you answer the intake email, and if it is late or has fewer than 10 specific, prioritized fixes, you get a full refund and keep the report. The audit is read-only, so I never ask for passwords or access to your accounts.

If you want a quick first look before that, the free AI city check asks ChatGPT and Google AI Overviews 3 client questions with your city in each, once in each engine, and I email you who they named.

Why my review gate refuses to run on a dirty working tree

Iliya Oblakov — Fri, 23 Oct 2026 06:13:43 +0000

Under my last post on dev.to, a reader asked whether merge-check also refuses when the working tree has uncommitted changes. It does, and so do the review and test scripts. This post covers what counts as dirty, where the check runs and why it is there.

The setup in one paragraph

two-engines-gate is the free, MIT licensed version of how I make Claude Code and Codex check each other. It has three scripts. gate.sh runs your tests and writes a pass record named after the commit. review.sh sends the commit to the other engine for a read-only review and saves the verdict under the commit hash. merge-check.sh refuses the merge unless the commit you are on has both. I wrote about the review loop and the commit hash records before. This post is about the one check all three scripts share.

The check itself

Each script defines the same small function:

clean() { # fails on changed or untracked files outside .ai/, and when git status itself fails
  local out; out="$(git status --porcelain --untracked-files=all -- . ':(exclude).ai')" && [ -z "$out" ]
}

git status --porcelain prints one line per changed file in a format meant for scripts. --untracked-files=all lists every untracked file, including files inside new folders. The pathspec ':(exclude).ai' leaves out the .ai/ folder, which is where the gate writes its verdicts, pass records and logs. If the command prints anything, the tree is dirty. If git status itself fails, the function fails too, so a broken repository never looks clean by accident. That is why the refusal message says "or git status failed".

I ran each case against the public repo on 23 October to see exactly what the scripts do:

State of the checkout	Result
A tracked file edited and not committed	refused by all three scripts
A change staged with `git add` but not committed	refused
A new file that git does not track	refused
An edited `.gitignore` that is not committed	refused
A new file under `.ai/`	allowed
A new file inside a folder that `.gitignore` covers	allowed

The refusal looks like this:

review: REFUSED: uncommitted changes or untracked files (or git status failed); commit or remove them first

Watch the .gitignore row. The README asks you to add .ai/ to the project's .gitignore, and that edit is itself an uncommitted change until you commit it, so the first review gets refused.

Why the review needs a clean tree

review.sh builds the reviewer's prompt from the commit log and git diff base...HEAD. Both of those only contain committed work. The verdict is then saved under the hash of HEAD.

The review prompt also tells the reviewer it may read any file in the checkout for context, and Codex in its read-only sandbox can do that. So if an edit sits in the working tree without a commit, the reviewer can open a file whose contents differ from the commit it is judging. Its ACCEPT would then be saved under a hash that does not contain the code it looked at. When the script refuses before the review starts, the files on disk match the commit under review.

Why the test run needs a clean tree

gate.sh runs your test command on the files on disk, and the files on disk are what the test command sees. An untracked helper file or a local fix that never got committed can make the tests pass. The pass record would then carry the hash of a commit that might fail on a fresh checkout. The guide in my kit puts it in one line: the gate refuses a dirty tree because "a check could pass on a file that is not in the commit".

The check runs before and after

Both review.sh and gate.sh run the check twice.

Before anything starts, each script deletes the earlier evidence for this commit. review.sh removes the old verdict file and gate.sh removes the old pass record. Only then does the clean check run. So a refused run cannot leave an old ACCEPT or an old pass sitting there for this commit.

After the reviewer or the tests finish, the script checks two things again: that HEAD has not moved, and that the tree is still clean. If the reviewer changed a file, review.sh prints REVIEW VOID: files changed during the review and saves no verdict. If the test command left a file behind, gate.sh fails the run. I tested that with a test command that creates a stray file:

gate: running 'bash test.sh; touch stray.txt' on 986def16acb8
gate: the run left changed or untracked files (or git status failed)
gate: FAIL (exit 1) on 986def16acb8; no pass record; full log .ai/tests/986def16acb8.log

A test suite that writes snapshots or build output into the repo will hit this. The way out is to make the suite write somewhere git ignores, and to commit that .gitignore change.

merge-check runs it first

merge-check.sh runs the same git status check before it looks at any pass record or verdict. The merge only takes the commit, so uncommitted edits would not be merged anyway. They would still mean the checkout holds work nobody reviewed or tested. With a clean checkout, a yes from merge-check covers exactly what is on disk.

What the check does not cover

Know these limits before you rely on the check.

Ignored files are invisible to it. git status does not list files that .gitignore covers, so a test that reads an ignored config file or a build cache can still behave differently on a fresh checkout. The gate does not catch that.
.ai/ is excluded on purpose, which means anything you put there is outside the check. The README calls the gate "a local guard against merging the wrong commit, not a security boundary", because anything with write access to the repository can write files under .ai/.
It only checks the local checkout. It does not push, merge or look at what is on the remote.

The same rule in the kit

The paid Two Engines Kit (currently v1.0.2) has the same rule in its own scripts. Its cross-review.sh and gate.sh both refuse a worktree with uncommitted changes or untracked files, and the guide says: "A dirty tree or an untracked file gets no record, so you cannot gate code that is not in the commit and then merge the commit." The Two Engines Kit is built on information gathered since the first Codex and Claude CLIs.

Try it

Clone two-engines-gate and run bash demo.sh to watch one full loop with a stand-in reviewer, so no model or account is used. Then edit a file in a project that uses the gate, leave it uncommitted, and run review.sh to see the refusal. The test suite in tests/run.sh has a dirty tree case and a "files changed during review" case if you want to read the check from the test side.

Why my review gate saves each verdict under the exact commit hash

Iliya Oblakov — Thu, 22 Oct 2026 07:59:21 +0000

Two recent items in the Claude Code repository, a changelog fix and a bug report, describe two ways a review step can go wrong.

What Anthropic fixed in Claude Code 2.1.305

The Claude Code changelog for version 2.1.305 has this line about Code Review, Anthropic's managed pull request reviewer:

"[Code Review] Fixed Code Review sometimes not reviewing the newest commit when several pushes landed on a pull request during a review"

Source: Claude Code CHANGELOG.md, version 2.1.305.

If nothing records which commit a review actually read, a review of an older commit looks the same as a review of the newest one. Anthropic has fixed this in its own product. The same risk exists in any setup where new commits can land while a review is running, a local one included.

What issue #103536 reports

Issue #103536 was opened on 19 Oct 2026 at 20:45 Sofia time and is titled "[BUG] Model edits tracked files during a read-only review, despite loaded 'never edit unless asked / zero autonomy' rules". The reporter writes:

"While re-reviewing pull requests, the model edited a tracked file (CHANGELOG.md) on its own initiative. It removed a duplicated entry and reworded another, and the user had not asked for either."

The environment section says why nothing stopped it:

"Auto-approval allowed the Edit and Bash tools, so nothing stopped the write"

Source: anthropics/claude-code issue #103536.

According to the issue, the rules telling the model not to edit were loaded every turn from CLAUDE.md and MEMORY.md. The Edit tool was still available, so the edit went through.

How the gate ties a verdict to one commit

two-engines-gate is a free, MIT-licensed local review and merge gate for Claude Code and Codex.

bin/review.sh reads the full hash of HEAD at the start and saves the verdict as .ai/reviews/<first 12 characters of HEAD>.md (lines 22 and 23). It deletes any earlier verdict for that commit first (line 24). After the reviewer exits, it checks that HEAD is still the same commit and stops with "REVIEW VOID: HEAD moved during the review" if it has changed (line 74). The saved file starts with a Head: line that holds the full 40-character hash (line 82).

bin/merge-check.sh then looks for .ai/reviews/<first 12 characters of HEAD>.md and refuses if the file is missing or if its Head: line names a different commit (lines 21 to 23). It also needs a test pass record named after the full hash, .ai/tests/<HEAD>.pass (lines 18 to 20), and a verdict whose reviewer is a different engine from the builder (lines 24 to 27).

When a new commit lands after a review, merge-check finds no verdict for it and refuses. The README gives the reason in two sentences: "an ACCEPT for an older commit can quietly cover code nobody reviewed. A new commit needs a new review and a new test run."

How the reviewer is kept away from Edit and Write

The gate's reviewer is always the engine that didn't write the code. With the default BUILDER=claude, Codex reviews, and review.sh calls it as codex exec -s read-only (bin/review.sh, line 60). docs/engines.md (line 13) describes this as the read-only sandbox, where Codex can read files and run read-only commands such as git diff but cannot write.

With BUILDER=codex, Claude Code reviews. This is the call in bin/review.sh (lines 66 to 68), shown here without the optional model argument:

claude -p "Do the review described on standard input." --restricted --strict-mcp-config \
  --permission-mode dontAsk --tools "Read,Grep,Glob" --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Bash,Edit,MultiEdit,Write,NotebookEdit,WebFetch,WebSearch,Task,Agent"

--tools "Read,Grep,Glob" limits the session to those three tools, and --disallowedTools also names Edit, MultiEdit, Write, NotebookEdit and Bash. docs/engines.md (line 30) says that with this call Claude Code "cannot run commands, git included, and cannot edit or write files", which is why review.sh puts the commits and the full diff into the prompt.

review-prompt.md also tells the reviewer "do not edit, create or delete files", and the gate doesn't depend on that sentence being obeyed. In issue #103536 the edit went through because the Edit tool was allowed, and in the gate's Claude Code call the reviewer starts without it. As a second check, review.sh runs git status after the review and stops with "REVIEW VOID: files changed during the review" if any file outside .ai/ changed (line 75).

What the gate doesn't do

The README lists its limits. It says the gate "does not make the code correct" and describes it as "a local guard against merging the wrong commit, not a security boundary", because anything with write access to the repository can write files under .ai/. It doesn't push, merge or talk to GitHub.

Try it, and the kit

The free gate is at github.com/IliyaOblakov/two-engines-gate. bash demo.sh in a clone walks one change through it with a stand-in reviewer, so it needs no model, account or network.

The Two Engines Kit is the paid kit, currently v1.0.2. In it Claude Code writes the code, Codex reviews it read-only, the review script saves the verdict under the commit Codex reviewed, and the merge script refuses to touch GitHub without a passing test run on that same commit. With REQUIRE_REVIEW=1 it also refuses a commit that has no saved ACCEPT. The Two Engines Kit is built on information gathered since the first Codex and Claude CLIs. It costs $29 for the first 30 sales, then $39, at rayastats.com/en/two-engines-kit.

What 50 med spa websites tell AI engines about themselves

Iliya Oblakov — Wed, 21 Oct 2026 22:41:02 +0000

On 21 and 22 October 2026 I checked the homepages of 50 small med spas in Texas, leaving out national chains and franchises. For each site I fetched the homepage and read the parts that software reads and visitors usually don't, such as the page title, the meta description, the main heading and the structured data. Structured data is a block of code that can give search engines and AI tools the business name, address, phone number and opening hours in a fixed format. On some sites I also looked at the sitemap and robots.txt.

For this article I did not ask ChatGPT, Perplexity or Google AI Overviews about any of these businesses. Everything below describes what the website code says, which affects how much clear, consistent information the site gives a tool that tries to describe the business. A problem in the code does not prove that an AI engine leaves a business out of its answers, and a clean site does not guarantee that it gets named.

These 50 are also not a random sample. I was looking for sites with something worth fixing, and I set aside at least 14 other sites that looked fine. The counts below are the problems I noted on each site, so the real numbers on these 50 sites may be higher. Please read them as what came up in this check, since they can't tell you how common these problems are across the industry.

More than half had no address in the code

At least 27 of the 50 homepages gave no street address in their structured data. Seven had no structured data at all. On the other 20 the structured data was there, but the address field was missing or empty. On at least 5 of those 20 the street address was printed on the page, so only the code was missing it.

On those sites a tool that relies on the structured data gets a name and maybe a phone number, and has to work out the location from loose page text.

Two more sites had a full address in the code that differed from the address shown on the page. On one of them the code pointed to a street in a different town. From the outside I can't tell whether that came from a copied template or an old location that nobody updated.

At least 5 sites showed two or more locations on the page and gave no address for any of them in the code.

The business name in the code was often wrong

The name is the most basic fact in structured data, and 11 of the 50 sites got it wrong in some way:

2 had the name misspelled.
2 had a blank name, or no name field at all.
1 used two people's names instead of the business name.
1 used the words "Medical Spa" as the name, with nothing else.
1 still had what looks like a working name from when the site was built.
1 had a stray number added to the end of the name.
1 used a different name in the code from the one in the page title.
2 had page text attached to the name, in one case the words "Privacy Policy" and in the other the whole homepage headline.

Two sites also labelled the business in the code as both a person and an organisation, and one credited a founder in the code who was not the owner named on the About page.

Page titles that say "Home"

The title tag is the text in the browser tab, and Google often uses it as the blue link in its results. On 6 of the 50 sites it started with the word "Home", followed by the business name or the site's web address, and none of those 6 named the town or a treatment. Counting those 6, at least 10 of the titles I read named neither the town nor a treatment. One title had the treatments and the town but no business name, and another left out both the name and the town.

A title like "Botox and fillers in [town] | [business name]" tells a search engine in one line what the page is about and where the business is.

Missing descriptions, empty headings and thin pages

9 sites had no meta description, or an empty one. That is the short summary search engines often show under the title.
10 sites had no main heading (H1) on the homepage, or an empty one. Two more had "Home" as the first main heading, on one the first two main headings were just the names of two towns, and one had dozens of H1 tags on the same page, several containing nothing but a "|" character.
4 homepages had fewer than 300 words of visible text. The shortest had about 145 words, which leaves very little for any tool to quote or summarise.

Placeholder pages that went live

Two sites were publishing template pages. One had eight live pages titled "Service title", "Service title 2" and so on up to 8, all listed in the sitemap and all loading normally. The other listed placeholder blog post addresses in its sitemap and had a live page called "New Page". Search engines can find pages like these through the sitemap and index them like any other page on the site.

What I did not count as a problem

Many of these sites have no llms.txt file, and I did not count that against them. Google's own guidance says its AI features need no special schema, and that llms.txt can be ignored for Google Search.

I also looked at robots.txt on several sites to see whether they block AI crawlers. On the Squarespace sites I checked, the AI bots are listed but grouped under the general rule, so they are not blocked. Of the sites where I read robots.txt, only one blocked an AI-related crawler (Amazonbot).

What you can check on your own site

None of these fixes needs a new website, and most are small edits for whoever looks after the site. You can check the basics yourself in a few minutes:

Open your homepage, right click, choose "View page source" and search for "ld+json". If nothing comes up, the page has no structured data of the kind I looked at.
If it is there, check that the name, street address, phone number and opening hours match what your site and your Google Business Profile show, word for word.
Look at the text in your browser tab. If it says "Home", change it to your main treatments, your town and your business name.
Open yoursite.com/sitemap.xml and look for pages you never meant to publish.

I wrote a longer walkthrough of free checks like these in Can AI engines read your website? A 15-minute check, and how AI engines choose which businesses to recommend is covered in GEO for small businesses.

If you want this done for your business

The checks above cover only the website code. In my AI Visibility Audit I also run live questions about your kind of business in AI engines, record which businesses get named and how yours is described, and give you a prioritised list of fixes.

You can see what is included, the packages and the turnaround on the audit page: AI Visibility Audit for med spas and local businesses.

How to make Codex review Claude Code's commits: done means, house rules and round rules

Iliya Oblakov — Wed, 21 Oct 2026 15:04:18 +0000

In my last post I showed the basic loop: 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.

That loop has a weak spot. A reviewer that doesn't know what "done" means reviews 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.

This post fixes that 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. I've been building this since the first Codex and Claude CLIs, and these three go into every review on my own projects.

A review without a finish line is an opinion.

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.

If you want that part ready to run, the free gate is at github.com/IliyaOblakov/two-engines-gate (MIT). Everything below sits on top of it, or on top of your own scripts.

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 stay exactly as it is
- 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. "Export works well" isn't a line. "A customer email with a comma is escaped" is.

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.

Where the brief lives matters. Commit it with the change, or keep it under .ai/. The free gate refuses to review a checkout with uncommitted changes or untracked files anywhere else, and it skips .ai/ for exactly this kind of working file. 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. The things you'd otherwise repeat in every review.

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, 32 KiB by default.

Write the rule once. Check it every time.

Step 3: make the reviewer answer every line

Now change what you ask for. 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: exactly one line, Verdict: ACCEPT or
Verdict: CHANGES REQUIRED. ACCEPT only when every line above is met.

With the free gate, add this to review-prompt.md, which exists to be edited with your project rules. With your own scripts, append it to whatever prompt you send Codex.

The reviewer now checks a list instead of free-styling. And 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. 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 still says CHANGES REQUIRED, stop sending fixes. The verdict stays CHANGES REQUIRED, so the merge stays blocked, and 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"

Then feed the count into the prompt. With the free gate, a short wrapper does it. Save it as review-round.sh in the root of your repository, in the same folder as rounds.sh, and run it from that root:

#!/usr/bin/env bash
# review-round.sh <change-name>: one counted review round with the free gate
round="$(bash rounds.sh "$1")" || exit
{ cat path/to/two-engines-gate/review-prompt.md; printf '\nThis is %s.\n' "$round"; } > .ai/prompt.md
REVIEW_PROMPT=.ai/prompt.md path/to/two-engines-gate/bin/review.sh

Commit both scripts, or list them in .gitignore and commit that change, so the gate does not 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 still uses up a round. Delete the last line of the .rounds file before you rerun it.

The cap never turns into an ACCEPT. It only stops the loop and hands the decision to you.

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. 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's one short question to you, not another round.

Evidence wins. Opinions wait.

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. What you get is a review that checks the things you said mattered, and a loop that ends.

Try it

The free gate has the read-only review, the verdict named after the commit, the test pass record, and a merge check that refuses without both, plus an offline demo that needs neither CLI. It runs in both directions: BUILDER=codex makes Claude Code the reviewer. Add the "Done means" section, the house rules and the round rules to its review-prompt.md, put rounds.sh and the wrapper in your repository root, and you have everything in this post.

If you want the full workflow I use, the Two Engines Kit is a paid kit I made. It adds one rulebook both engines load, hooks and settings for both engines, a GitHub merge script that merges exactly the commit that was checked, and an installer that previews every change and can be undone byte for byte. $29 for the first 30 sales, then $39: https://rayastats.com/en/two-engines-kit

How I make Claude Code and Codex review each other's work

Iliya Oblakov — Tue, 20 Oct 2026 20:19:43 +0000

I build software for paying clients with Claude Code and Codex. Both are good at writing code. Neither is good at judging its own work, because the session that wrote a change is the worst place to decide whether that change is finished. It already believes it is.

So I split the jobs. Claude Code writes. Codex reviews, read-only. My own tests run on the same commit. A small script decides whether anything merges, and it only looks at evidence saved to disk.

Here is how to set it up. You need git, the Claude Code CLI, the Codex CLI and a test command.

Step 1: one rulebook, two readers

If the writer and the reviewer follow different rules, the reviewer flags things the writer was never told, and you end up arbitrating between two models.

Keep one file, say rules/RULES.md, with your real standards. Then point both engines at it:

Claude Code reads CLAUDE.md, which can import other files with an @ line. Put @rules/RULES.md in it and you are done.
Codex reads AGENTS.md. Generate it from the same source rather than editing it by hand:

#!/usr/bin/env bash
# sync-rules.sh: build AGENTS.md from the shared rulebook
set -euo pipefail
{
  echo "<!-- generated from rules/RULES.md, do not edit -->"
  cat rules/RULES.md
  [ -f rules/codex-extra.md ] && cat rules/codex-extra.md
} > AGENTS.md

Keep engine specific lines few. Everything that defines "good work" belongs in the shared file.

Step 2: write rules a reviewer can check

This is where most setups go wrong. "Write clean, maintainable code" sounds sensible, but a reviewer cannot check a diff against it, so you get opinions instead of findings.

A good rule names something visible in a diff, says what to do instead, and says how to tell it was done. Here is one example rule you can copy into your own rulebook. I wrote it for this post:

## Public signatures

When a change renames, removes or reorders the parameters of an
exported function, class or API route:

1. Update every caller in the repository in the same commit.
2. Add a line to the commit message body starting with
   "Signature change:" that names the old and new signature.
3. If a caller lives outside this repository, do not make the change.
   Add a new function next to the old one and mark the old one
   deprecated in a comment.

Reviewer check: search the diff for changed exported signatures.
For each one, confirm the callers were updated and the
"Signature change:" line exists. If either is missing, the verdict
is CHANGES REQUIRED and the finding quotes this rule.

Notice the last paragraph. Each rule tells the reviewer what to look for. That turns review from taste into a checklist.

Step 3: let Claude Code work in its own worktree

Never let the writing agent touch your main checkout. A git worktree gives it a separate directory on a separate branch, sharing the same repository:

git worktree add ../task-login-fix -b task-login-fix
cd ../task-login-fix
claude

Give Claude Code the task there. If it goes wrong, git worktree remove throws the whole attempt away and your main branch never saw it.

Step 4: Codex reviews read-only, with a forced verdict

The reviewer must not be able to edit files. A reviewer that can fix what it finds is a second author, and nobody reviewed that second author. Run Codex with a read-only sandbox.

Give it three things: the rulebook (it already has it through AGENTS.md), the diff against the base branch, and a prompt that ends with a strict output format. A minimal version:

#!/usr/bin/env bash
# review.sh: ask Codex for a verdict on the current commit
set -euo pipefail
base="${1:-main}"
sha="$(git rev-parse HEAD)"
mkdir -p .ai/reviews
git diff "$base...HEAD" > ".ai/reviews/$sha.diff"

codex exec --sandbox read-only "Review the diff in .ai/reviews/$sha.diff
against the rules in AGENTS.md. List each problem with the rule it
breaks, quoted. Do not edit any file. The last line of your answer
must be exactly ACCEPT or exactly CHANGES REQUIRED." \
  > ".ai/reviews/$sha.md"

tail -n 1 ".ai/reviews/$sha.md"

Two details matter here.

First, the verdict file is named after the commit hash. If Claude Code adds one more commit after the review, the hash changes and the old ACCEPT no longer applies. You cannot accidentally merge code nobody reviewed.

Second, the verdict is a fixed word on the last line. Scripts can read that. They cannot read "mostly looks good, a few small things".

If the verdict is CHANGES REQUIRED, hand the review file back to Claude Code in the worktree, let it fix the findings, commit, and review again.

Step 5: run your tests on the same commit

The review checks the rules. Your tests check the behaviour. Run them on the exact commit that was reviewed and record a pass only when they pass cleanly:

sha="$(git rev-parse HEAD)"
mkdir -p .ai/tests
if npm test; then
  echo "pass $(date -u +%FT%TZ)" > ".ai/tests/$sha.pass"
fi

Swap npm test for whatever your project uses. Add .ai/ to your git ignore so none of this ends up in the repository.

Step 6: a dumb gate decides the merge

The final step should involve no judgement at all. A script checks that both pieces of evidence exist for the current commit, and refuses otherwise:

#!/usr/bin/env bash
# gate.sh: refuse to merge without a review and a test pass for HEAD
set -euo pipefail
sha="$(git rev-parse HEAD)"
review=".ai/reviews/$sha.md"
tests=".ai/tests/$sha.pass"

[ -f "$tests" ] || { echo "No test pass for $sha"; exit 1; }
[ -f "$review" ] || { echo "No review for $sha"; exit 1; }
[ "$(tail -n 1 "$review")" = "ACCEPT" ] || { echo "Review did not accept $sha"; exit 1; }
[ -z "$(git status --porcelain)" ] || { echo "Working tree not clean"; exit 1; }

echo "Gate passed for $sha"

Run it before every merge. "Reviewed and tested" stops being something you remember and becomes something a script checks.

What this does not do

It does not make the code correct. Codex can miss things, and so can your tests. The gate only proves the steps happened on the commit you are about to merge. That is still a big improvement over trusting the same session that wrote the code to tell you it is done.

A few habits that help:

Send routine work to cheaper models and keep the expensive reasoning for design, hard debugging and the review itself.
When a review keeps flagging the same thing, turn it into a rule with a reviewer check.
Read the review, even when it says ACCEPT. The gate is a floor, not a replacement for you.

If you want the full version

Everything above is enough to start. If you would rather install a finished setup, I packaged the workflow I use on client work as the Two Engines Kit: a shared rulebook for both engines, cross review, gate and merge scripts (the merge script can be set to refuse without a saved ACCEPT), hooks and settings for both engines, a skill for long tasks, an optional shared memory module, and GUIDE.md on why each piece exists. The installer previews each change and asks before applying it, and uninstall.sh restores your old files byte for byte. It needs both Claude Code and Codex, and runs on WSL2, Linux or macOS (tested on WSL2 with Ubuntu 24.04).

It is $29 for the first 30 sales, then $39: https://rayastats.com/en/two-engines-kit