DEV Community: Iliya Oblakov

Codex keeps returning CHANGES REQUIRED: sort the finding before Claude Code edits again

Iliya Oblakov — Mon, 09 Nov 2026 19:59:08 +0000

One more Claude Code edit won't end a Codex review that keeps returning CHANGES REQUIRED. Each speculative patch gives the reviewer new code to comment on, so every pass comes back with new comments. Sort the finding before anyone touches the code.

How to make Codex review Claude Code's commits covers the hooks, the worktrees and the loop itself. This one starts after setup, with a loop that runs and won't reach ACCEPT.

Sort every finding into one of five classes

My reviewer answers every line of the brief and every house rule with met, not met or not checkable. A finding outside that list needs a concrete failure: the input or steps, plus what goes wrong.

Each finding gets a class and a response before Claude Code sees another edit request:

Finding class	Response
Brief or house-rule violation	Fix it, or ask a person when the requirement itself is disputed
Failure outside the brief	Block only with concrete reproduction details
Reviewer preference	Move to follow-ups unless a written rule requires it
Unverifiable claim	Ask for evidence before patching anything
Missing, duplicate or malformed verdict	Operational failure: rerun on purpose and don't count it as a review round

When the review itself breaks

A crash, an empty final message, or a missing, duplicate or malformed verdict leaves no saved verdict, and with no saved verdict my gate refuses the merge.

review.sh exits 0 for a saved ACCEPT, 2 for a saved CHANGES REQUIRED and 1 when nothing was saved. Exit 1 says nothing about the code, so Claude Code has nothing to fix. The gate doesn't retry on its own. Read the log, then rerun the review on purpose. What the gate does when a review crashes or returns no verdict covers that case.

A blocker needs a failure you can reproduce

In my setup, a finding stands when it comes with a reproducible failure. Without one, it goes to follow-ups. The rule exists because a reviewer can be wrong, and tests only check what they test.

For a blocker, ask Codex for three things:

The input or steps that trigger it
The expected behavior
The actual behavior

With those, Claude Code fixes a demonstrated failure. Without them, it patches toward a review that grows with every pass.

Tests get the same treatment. In the weakened-test example, add(2, 3) returns 6 and the weakened assertion accepts it, so the suite passes with the bug in place. A new test should fail on the old behavior. A loosened assertion with no stated reason can draw CHANGES REQUIRED, and a review can miss it too, so a passing review doesn't guarantee correct code.

Brief violations and reviewer preferences

A brief violation is a required change. A preference is a technically plausible alternative to code that already meets the brief. The per-line check keeps Codex anchored to that difference: once every brief line and house rule is met, a remaining comment needs a reproducible failure to block.

In a made-up example, Codex suggests renaming get_rows to fetch_rows. Every brief line is met, nothing fails and no house rule covers the name, so the comment goes to follow-ups. If a house rule did set the naming pattern, the same comment would be a not met line, and Claude Code would fix it in this round.

Later rounds get a narrower packet

Early rounds can raise anything relevant. Later rounds raise only merge blockers, and smaller points go on the follow-ups list.

Every round reviews the current commit. My verdicts are saved under the exact commit that was reviewed, so a new commit needs a new review, and an ACCEPT for an old commit can't cover changed code (why the verdict is saved under the commit hash). The narrowing happens in the packet Codex gets for each later round:

The unresolved findings
What changed since the previous review
The exact current commit and its diff

A compact prompt for that packet:

Review the current commit. Recheck the unresolved findings and the changes since the previous review. Do not reopen settled preferences or unrelated code. A new blocker outside that scope needs concrete reproduction details.

A new blocker stays valid in any round when Codex identifies the failure and reproduces it, so narrowing doesn't hide regressions.

Pick a hard stop before round one

Write the cap down before the first round. Tell Codex which round it's in, so it knows when the later-round rules apply.

If the last allowed round returns CHANGES REQUIRED, stop sending fixes. The verdict stays CHANGES REQUIRED and the merge stays blocked, because a cap never turns the result into acceptance. A person then picks the next step: change the approach, split the change, or allow another round on purpose. Non-blockers wait in follow-ups and don't hold up the merge.

Count only substantive rounds, so a rerun after an operational failure leaves the count alone. A new commit doesn't reset the count for the same change, or every fix would buy a fresh set of rounds.

What the official Codex plugin already covers

OpenAI publishes a Codex plugin for Claude Code with an optional review gate. The gate is a Stop hook: when a targeted Codex review of Claude Code's response finds issues, it blocks the stop so Claude Code can address them.

The stop-gate prompt limits the review to the previous Claude Code turn that produced edits, requires blocking claims to be grounded in repository context or inspected tool output, and returns ALLOW or BLOCK. The prompt behind /codex:adversarial-review asks for material findings and excludes style feedback, naming feedback, low-value cleanup and speculative concerns without evidence. Both prompts already apply the evidence bar from the sections above. The README warns that the gate can create a long-running loop between Claude Code and Codex, can drain usage limits quickly, and should be on only while you're monitoring the session.

The documentation leaves the stopping policy to you: a cap on substantive rounds, how to resolve a disputed brief, how to narrow later rounds across repeated fix commits and where non-blockers go.

Disputed requirements and scope go to a person

When Claude Code and Codex read an acceptance criterion two ways, each round repeats the disagreement in a new commit. The loop is missing product intent that nobody wrote down, and extra passes can't supply it.

Keep the unresolved verdict and send the owner of the change one short question. Scope questions and anything a user will see go the same way. Codex supplies the evidence, the owner chooses the requirement, Claude Code implements that decision, and Codex reviews against it.

The loop ends in one of two states: an ACCEPT for the current commit, or a recorded blocked verdict plus a human decision about the next step.

Run these rules on your own repository

The Two Engines Kit has the review prompts, round rules and commit-specific verdict records. Built on information gathered since the first Codex and Claude CLIs.

Get the Two Engines Kit

If you want the loop set up for you instead, I set up Codex to review your Claude Code commits before they merge. The review setup is written from scratch for your repository, its stack and its conventions, and the first review runs on one of your real branches. Nothing is copied from a template or from the Two Engines Kit.

See the AI code review setup

AGENTS.md ignored in a monorepo? Claude Code and Codex walk the tree in opposite directions

Iliya Oblakov — Mon, 09 Nov 2026 19:58:29 +0000

Start Codex at the root of a monorepo and the AGENTS.md in your package stays out of that run. Leave a CLAUDE.md in any folder above your working directory and Claude Code, under its default setting, reads that file instead of AGENTS.md. In both cases the AGENTS.md sits where you put it.

So when an AGENTS.md looks ignored, check the path around it before you edit the file. Three things decide what loads: the folder you launched from, a file higher up that takes its place, and a size cap.

The same problem shows up on Stack Overflow for other setups. A question about GitHub Copilot reporting no instructions while AGENTS.md is in the repository had 1,584 views on 5 November 2026, and one about AGENTS.md in a Gradle multi-module project had 149. This post covers Claude Code and Codex, the two I use, per their official docs as of 5 November 2026. For a file-by-file comparison of the two formats, see CLAUDE.md vs AGENTS.md.

How Claude Code and Codex build the chain

Take this monorepo, with the session started in packages/api/src:

repo/
  AGENTS.md
  packages/
    api/
      AGENTS.md
      src/
    web/
      AGENTS.md
      CLAUDE.md

Codex, per its AGENTS.md guide, first reads one global file from its home folder (~/.codex unless you set CODEX_HOME): AGENTS.override.md if it exists, otherwise AGENTS.md. Then it starts at the project root, typically the Git root, and walks down to the folder you launched from. In each folder it takes at most one file, checking AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. It joins the files root first, so the file closest to your folder comes last and overrides earlier guidance.

Claude Code, per its memory docs, walks the other way: from your working directory up through every folder above it. If no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits on that path, it reads every AGENTS.md and .claude/AGENTS.md it finds there at session start. An AGENTS.md below your working directory loads later, when Claude Code opens a file in that subfolder with the Read tool, and only if the subfolder has no CLAUDE.md of its own. Reading AGENTS.md directly needs Claude Code v2.1.277 or later.

The agents.md site recommends nested files for monorepos and says the file closest to the edited file takes precedence. Claude Code and Codex both follow that layering and differ in when each file enters the session. With both started at the root of the example repo, Claude Code reads packages/api/AGENTS.md once it opens a file in that package with the Read tool, and Codex leaves it out of the run.

Three files that hide an AGENTS.md

AGENTS.override.md. Codex checks it first in each folder and reads only one file there, so an override hides the AGENTS.md beside it. Claude Code doesn't read override files at all. If Codex follows rules you can't find, look for an override higher in the tree or in ~/.codex.
A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. Under the default setting, Claude Code reads those instead of AGENTS.md, even when the file sits in a parent folder above the repo. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count: they load alongside AGENTS.md.
A package CLAUDE.md. In the example, packages/web/CLAUDE.md makes Claude Code skip packages/web/AGENTS.md when it works in that package. Codex reads packages/web/AGENTS.md and ignores the CLAUDE.md.

The Codex troubleshooting list adds two causes. Codex skips empty files. A non-default CODEX_HOME points it at a different home folder from the one you edited, so run echo $CODEX_HOME before you debug the global file.

Where root rules and package rules go

Put rules every package follows in the root AGENTS.md and rules for one package in that package's AGENTS.md.

If a package needs a CLAUDE.md for lines only Claude Code should see, start that file with a bare @AGENTS.md import. Claude Code reads the imported file first, then the lines below it, so Claude Code and Codex both get the package AGENTS.md.

In a large monorepo, Claude Code's claudeMdExcludes setting skips other teams' files by path or glob, and the docs say it covers the AGENTS.md files Claude Code reads too. Put it in .claude/settings.local.json to keep the exclusion on your machine.

Keep the Codex chain under 32 KiB

Codex stops adding files once the combined size of the chain reaches project_doc_max_bytes, 32 KiB by default. Root files load first, so in a deep package the root file can use most of the budget and the package file, which loads last, gets cut. Raise the limit in ~/.codex/config.toml or move rules out of the root file:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Claude Code's docs target under 200 lines per CLAUDE.md, and a file over 4 MiB is skipped. A subfolder CLAUDE.md that loads on demand has a per-file character limit tied to the context window, and Claude Code receives only the start of a longer file.

Check what loaded, from the root and from a package

This script only reads files. It prints the Codex chain with its combined size, any file that stops Claude Code reading AGENTS.md, and the nested files below you. It doesn't cover names in project_doc_fallback_filenames.

#!/usr/bin/env bash
# Run from the folder you start Claude Code and Codex in.
root=$(git rev-parse --show-toplevel) || exit 1
here=$(pwd -P)
home=${CODEX_HOME:-$HOME/.codex}

echo "Codex chain (global, then root down to here):"
for f in "$home/AGENTS.override.md" "$home/AGENTS.md"; do
  [ -s "$f" ] && { echo "  $f"; total=$(wc -c < "$f"); break; }
done
dirs=() d=$here
while :; do dirs=("$d" "${dirs[@]}"); [ "$d" = "$root" ] && break; d=$(dirname "$d"); done
for d in "${dirs[@]}"; do
  for f in AGENTS.override.md AGENTS.md; do
    [ -s "$d/$f" ] && { echo "  $d/$f"; total=$(( ${total:-0} + $(wc -c < "$d/$f") )); break; }
  done
done
echo "  combined bytes: ${total:-0} of 32768 default"

echo "Files that stop Claude Code reading AGENTS.md (here and above):"
d=$here
while :; do
  for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do
    [ -e "$d/$f" ] && [ "$d/$f" != "$HOME/.claude/CLAUDE.md" ] && echo "  $d/$f"
  done
  [ "$d" = / ] && break; d=$(dirname "$d")
done

echo "Nested files below here (load later or only from their folder):"
find . -mindepth 2 \( -name 'AGENTS*.md' -o -name 'CLAUDE*.md' \) -not -path '*/node_modules/*' -not -path './.git/*'

Then ask Codex directly. Its guide gives one command for the root and one for a package. Both turn approval prompts off, so run them only in a repo you trust:

codex --ask-for-approval never "Summarize the current instructions."
codex --cd packages/api --ask-for-approval never "Show which instruction files are active."

For a record, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log. Codex rebuilds the chain on every run, so restart it in the target folder after an edit.

In Claude Code, an interactive session with no CLAUDE.md on the path shows a line starting no CLAUDE.md found; AGENTS.md loaded: followed by the file's path. Run /memory and look for that path, or run /context all and check the list under Memory files. Before v2.1.280 neither one listed an AGENTS.md read directly, so on older versions ask Claude Code what its project instructions say. A nested CLAUDE.md that loads on demand prints a Loaded line with its path when it enters the session. If /config has no Project instructions setting, your session can't read AGENTS.md directly, and a CLAUDE.md with @AGENTS.md is the way in.

The checklist for one package:

Start in the package folder and run the script.
Remove or rename any AGENTS.override.md you didn't mean to keep.
Remove stray CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md files on the path, or set Project instructions to claude-md-and-agents-md in /config.
Keep the Codex combined size under 32 KiB, or raise project_doc_max_bytes.
Run both Codex commands above and confirm the package file comes last.
In Claude Code, look for the AGENTS.md loaded line or the path in /memory.

If the script turns up a file you didn't write, my post on the planted AGENTS.md in Downloads has commands to check where it came from and what it changed.

One global rulebook for Claude Code and Codex

The global layer sits at the top of every chain above, so I keep mine in one place. In the Two Engines Kit, RULES.md holds the rules Claude Code and Codex share, and claude.md and codex.md hold the few lines that differ. The installer points ~/.claude/CLAUDE.md at the shared rules and builds ~/.codex/AGENTS.md from them with sync.sh. It previews each change, asks first and backs up what it replaces, and uninstall.sh restores it. The kit is built on information gathered since the first Codex and Claude CLIs.

Project and package AGENTS.md files stay in your repo, so every check in this post applies with the kit installed too. If you run Claude Code and Codex on one machine, get the Two Engines Kit at https://rayastats.com/en/two-engines-kit and keep one global rulebook for both.

Shared API key or per-user OAuth: how to put an MCP server over your existing API

Iliya Oblakov — Mon, 09 Nov 2026 19:56:43 +0000

On 5 November 2026, a Stack Overflow question asking whether Claude Desktop can open an authorization URL and accept a token without OAuth 2.0/PKCE had 749 views. Another, on how to pass an API key to tool calls in a Cloudflare remote MCP server, had 605. Authentication is where builders get stuck first when they put an MCP server over an existing API.

I checked the MCP specification and the Claude and ChatGPT connector docs the same day.

Your MCP server handles two credentials

The client presents one to your MCP server. Your MCP server presents the other to your API. Keep them separate.

Your API keeps its authentication, permissions and business logic, and the MCP server enforces them on every call. The MCP server can hold its own API key for those calls. If each user needs their own API permissions, give them a separate grant with your API instead of forwarding their MCP access token.

How the client authenticates to your MCP server

Claude and ChatGPT connectors reach a remote server over Streamable HTTP, one of the two transports in the MCP transports specification. A stdio server, which the client launches as a subprocess, fits local development and takes its credentials from the environment.

Authorization is optional in MCP. When you protect an HTTP server, the MCP authorization specification uses OAuth 2.1, and your MCP server acts as a resource server:

It answers an unauthenticated request with 401 and a WWW-Authenticate header pointing at its Protected Resource Metadata document.
The client discovers the authorization server from that document.
Your server validates that each token was issued for it, and never accepts or forwards a token issued for another resource.
Tokens never go in the URL query string.

For a shared credential, Claude and ChatGPT each document a static-key path:

Claude supports static_headers. An organization Owner enters an API key or bearer token when adding the connector, and Claude sends it in a request header on every call. Anthropic's authentication page marks it beta and limits it to a set of organizations. Standard header names such as authorization, x-api-key and x-auth-token work, and other names need Anthropic's approval.
ChatGPT plugins declare API key authentication in mcp.json under extensions["com.openai"].auth, with headerScheme set to bearer, basic or custom_header. OpenAI's packaging reference notes that the submission portal's connection form doesn't support these declarations.

For the first Stack Overflow question, the static-key route in Anthropic's docs is static_headers, with the limits above, and a shared key can't identify an individual user. For the second, both static-key paths carry the key in a request header. Keep it out of tool arguments, because a model that can see a key in a parameter can repeat it or send it somewhere else.

Choose OAuth when a tool reads one user's data or acts in their name. A static key fits a service account where everyone shares the same permissions. For a static key, document the header name and key source, and keep keys out of URLs and logs.

Map operations to focused tools

Start with a few read operations and one workflow you can test end to end, then add writes once the reads hold up.

Give each user goal its own tool, such as list_invoices, get_invoice and create_invoice. One generic api_request tool with a method parameter gives the model no useful guidance and fails directory review. Anthropic's connector review criteria require separate read and write tools and recommend splitting create, update and delete.

Each tool needs a name, a description that says when to use it, an explicit JSON Schema for its input (inputSchema in the MCP tools specification), and annotations that match its behavior. Annotations guide client confirmations but don't replace your own authorization.

For the Claude directory, the same criteria require a title, accurate readOnlyHint and destructiveHint annotations, and names of 64 characters or fewer. Descriptions have to match what the tool does, and they can't contain behavioral instructions or pull instructions from external sources.

Return the fields the next step needs, cap lists, and pass a continuation value for the next page. Anthropic's connector build guide caps a tool result at about 150,000 characters on claude.ai and Desktop, and at 25,000 tokens by default in Claude Code. OpenAI's build guide says to keep secrets and unnecessary personal data out of results.

For a workflow that spans calls, like a draft order, return an explicit handle from the creation tool and accept it on later calls. Check on every call that the handle belongs to the caller.

Write errors the model can act on

Use one input object for path, query and body fields, enums for fixed values, and formats in the parameter descriptions. If the caller can say "Acme" instead of a UUID, resolve the name inside the tool.

Return structuredContent for later tool calls and a text content block that says what happened. Stable IDs let the next call refer to the same record.

Return execution errors with isError: true and text the model can act on. Turn an upstream 404 into a message like this one:

No invoice with ID 123. Call list_invoices to find a valid ID.

Give validation failures the expected format and rate limits a retry delay. Don't pass through stack traces or raw upstream bodies.

For rules that span tools, OpenAI supports server-wide instructions and advises putting the most important material in the first 512 characters. ChatGPT uses readOnlyHint to decide which calls need confirmation, and it treats any tool without it as a write action.

Test in the Inspector, then in Claude and ChatGPT

Run the MCP Inspector first:

npx @modelcontextprotocol/inspector

Check initialization, the tool list, every tool with valid and invalid inputs, and the errors that come back. Then connect both clients:

In Claude, add the server as a custom connector by URL and run through the auth flow.
In ChatGPT, go to Plugins, choose Add custom MCP server, enter the HTTPS /mcp URL and set up authentication. OpenAI's quickstart includes a tunnel for local development.

Test prompts that should pick each tool, prompts that should pick none, wrong IDs, expired credentials and a write that needs confirmation. Refresh the connection after you change tool metadata.

Plan a review round for Claude's directory

Anthropic's criteria require testing every tool through the Inspector and as a custom connector before you submit. The review also requires a populated test account, public documentation by your publish date, actionable error messages, and first-party APIs or APIs you legitimately proxy.

If your connector already exists, my AI connector review checks it before you submit. It's an independent review of an existing MCP connector against Anthropic's connector pre-submission checklist, and every finding comes with reproduction steps.

What to prepare before an MCP build

Bring these to the first conversation:

Your OpenAPI document, or a list of the operations with their request and response shapes.
Three to five user requests the server should handle, written the way a user would type them.
The operations to leave out, including admin, irreversible and billing actions.
The auth decision: shared API key or per-user OAuth, and who issues each credential.
A test account with realistic data and a way to reset it.
The deployment target for an HTTPS endpoint and where its secrets live.

I build MCP servers over existing APIs for Claude and ChatGPT. The scope starts from that list: the tool map, the auth path, the error behavior and a tested connection to the client you use. If you want me to build yours, start on the AI connector build page with that list ready.

Four unreviewed commits, one already merged: how my Claude Code and Codex setup got its rules

Iliya Oblakov — Mon, 09 Nov 2026 18:16:04 +0000

One night in October I found four test-only commits in my own projects that no reviewer had ever read. One was already merged. The other three were waiting in the merge queue.

Nothing broke. Codex confirmed all four before the queue resumed. That night is the reason the rules in my setup now live in scripts instead of in my head.

This is how the setup came together, one failure at a time, and what you can copy from it today.

Why one engine can't sign off its own work

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 the code, and Codex reviews it read-only. I picked a reviewer from a different company because it has different blind spots. On one pull request in October the first Codex review came back with 2 blockers and 8 should-fix findings. That single review is why the loop exists.

The reviewer has to be read-only. A reviewer that can fix what it finds is a second author, and nobody reviewed that second author. Codex runs in a read-only sandbox, so every fix, small ones too, goes back to Claude Code as a fail list, and the new commit gets reviewed again.

What a second engine catches

Four findings from Codex reviews of my own pull requests, with project details removed. Each came with the file, the line and a way to make it fail.

1) A CI step turned screenshot capture errors into report rows but never counted them as problems. A timeout could finish with every report written, zero problems and a green build.
2) A guard meant to keep a publishing script away from the wrong database read only one shell variable. A target chosen through the environment file got past it.
3) A new exemption for media links ran before the scheme and host checks, so links to a local dev server and ftp addresses passed an audit built to reject them.
4) A stricter validation step crashed on one malformed field in an API response that the old code had reported cleanly, which would have stopped the rest of the audit run.

The first two were blockers.

The night the review became a file

Since that night, the review script saves the Codex verdict in a file named after the exact commit it reviewed. A new commit has no verdict until it's reviewed, so an ACCEPT from an earlier commit can't cover code nobody read. With REQUIRE_REVIEW=1 the merge script refuses any commit without its own ACCEPT file.

The script is strict about what counts as a verdict. It reads only the reviewer's final message, and it accepts the result only when Codex exited 0, the checkout didn't change during the review and the final message has a single Verdict: line. A crash, a cut-off answer and a checkout that moved mid-review all end with exit 1 and no verdict file. Two Verdict: lines count as none, because the script has no way to know which one the reviewer meant.

The bill that moved CI onto my machine

One private repository spent about 2,100 GitHub Actions minutes in its first five days of hosted CI, on a free tier of 2,000 minutes a month. Since then every check runs on my machine first, and work is pushed only after it passes there.

The local gate runs your tests on the same commit Codex reviewed. It writes a pass record only after a full pass on a tree that was clean before and after the run. It refuses a dirty tree because a check could pass on a file that isn't in the commit. The merge script refuses to push without that record for the exact commit, then merges with GitHub's sha parameter, so GitHub refuses the merge if the branch head moved in between.

My own gate runs 40 to 43 checks. Run one group after another, a full pass took 35 to 40 minutes. Split into five parallel lanes, it takes about 11 minutes on that machine.

The test that changed which model does what

On 12 October I gave both engines the same task: a Tetris implementation against 44 hidden tests, three runs each. Claude Code with Opus 5.5 at xhigh and Codex with GPT-6.1-Sol at xhigh both passed 44/44 in all three runs. The median times were 21:17 and 18:13. Opus cost 8.9 times as much.

So work goes by what a mistake costs. Bounded implementation with a clear brief goes to Sonnet. Haiku gets search, extraction and listing, where a wrong answer is cheap to spot. xhigh and max effort go to design-heavy slices, the first review of a pull request and hard debugging. The Tetris run is one task, so those last rows keep xhigh until they get their own rerun.

What the setup can't do

These checks cannot make the code correct. If Claude Code weakens a test in the same commit that breaks the code, the test gate passes that commit, and catching it falls to the reviewer. The review prompt says new tests must fail on the old behaviour and nothing gets weakened without a stated reason, and Codex checks the diff against that rule. A review can miss things.

A wrong ACCEPT looks the same as a right one. That's why ACCEPT only unblocks the pull request in my setup, and I do the merge myself.

The recorded demo of the kit 1.0.2 scripts on 23 October shows the refusing side. It ran on a throwaway project with real Codex reviews and DRY_RUN merges, and the merge script refused all seven attempts because the gate log was missing, the gate had not passed, or the verdict was missing or not ACCEPT. The demo never reached ACCEPT and nothing was merged.

Copy this into your own repo

1) Keep one rules file both engines load. Claude Code imports it into CLAUDE.md with an @ line, and a small script builds AGENTS.md for Codex from the same source.
2) Run Claude Code in its own git worktree, away from your main branch.
3) Run Codex with a read-only sandbox, and make its final message carry a single verdict line, Verdict: ACCEPT or Verdict: CHANGES REQUIRED.
4) Save that verdict in a file named after the commit hash.
5) Run your tests on the same commit, on a clean tree, and record a pass only after a full pass.
6) Let a script refuse the merge when the current commit lacks either file.

Get the full loop

The Two Engines Kit is this loop packed so one script installs it. You get one rulebook both engines load, the cross-review and gate scripts, a merge script that refuses without a pass record for the exact commit (and, with REQUIRE_REVIEW=1, without the saved ACCEPT), and GUIDE.md, which explains each piece and the mistake that produced it. The installer previews every change and asks y/N, and uninstall.sh puts your old files back byte for byte. It needs both Claude Code and Codex, supports WSL2, Linux and macOS, and is tested on WSL2 with Ubuntu 24.04.

I've been building it since the first Codex and Claude CLIs. Get the Two Engines Kit at https://rayastats.com/en/two-engines-kit

A 7-point checklist before you let Codex review Claude Code commits

Iliya Oblakov — Thu, 05 Nov 2026 14:17:24 +0000

Claude Code writes, Codex reviews, a gate decides what merges. Here's the short version I check before trusting that loop on a repo. The full walkthrough, with the prompts, is in How to make Codex review Claude Code's commits.

1. Codex runs read-only.
codex exec -s read-only --color never --output-last-message <file> -, with the prompt on stdin. The reviewer can read files and run git diff, but it can't write or hand back a patch.

2. One verdict line, saved under the commit hash.
Verdict: ACCEPT or Verdict: CHANGES REQUIRED, read only from the --output-last-message file. A crash, an empty answer or two Verdict lines leave no saved verdict, so the commit can't merge.

3. A brief exists before the code.
Every line under "Done means" is something a reviewer can confirm from the diff or a test. Write "a customer email with a comma is escaped", never "export works well".

4. Each new test failed on the base commit.
The engine that writes the code often writes the tests too. A test that already passes on the old code proves nothing about the change.

5. House rules live where both engines read them.
CLAUDE.md for Claude Code, AGENTS.md for Codex. Keep the AGENTS.md part short: Codex stops adding instruction files once their combined size reaches project_doc_max_bytes, 32 KiB by default.

6. The reviewer answers every line.
Met with a file:line, not met with what's missing, or not checkable with the evidence it would need. Findings outside the brief need a concrete failure. Style preferences aren't findings.

7. Rounds have a hard cap.
Later rounds raise only what blocks the merge. If the last allowed round says CHANGES REQUIRED, the merge stays blocked and a person decides.

The merge is refused unless that exact commit has a test pass and a saved ACCEPT. A test pass alone won't catch a test Claude Code weakened in the same commit, so that falls to the reviewer: what my review gate does with weakened and deleted tests.

If you want the whole setup prebuilt, the Two Engines Kit for Claude Code and Codex is a paid kit I made, built on information gathered since the first Codex and Claude CLIs.

Custom website vs website builder: which one does your small business need?

Iliya Oblakov — Wed, 04 Nov 2026 15:22:26 +0000

The short answer: if you need a simple site that says who you are and how to reach you, and you have more time than budget, a website builder such as Wix or Squarespace is a sensible choice. If your website has to do a specific job for the business, such as taking bookings your way, selling with your own rules, winning searches in a crowded market or growing with you for years, a custom website is usually worth the extra cost. This guide compares a custom website vs a website builder on cost, ownership, speed and search, so you can tell which side you're on.

I'm Iliya Oblakov, a software engineer. I build custom websites for small businesses, so I have an obvious bias. That's why this guide also says plainly when a builder is the better buy.

Custom website vs website builder: the quick decision table

Your situation	Better fit
You're testing an idea and may change direction in six months	Website builder
You need three to five pages of information and a contact form, and you enjoy doing it yourself	Website builder
Most of your customers find you through search, and competitors already have strong sites	Custom website
You take bookings, quotes or orders with rules that builder apps don't quite fit	Custom website
You sell in two languages or two countries	Custom website
You'd rather spend your hours running the business than editing a website	Custom website with a care plan

What a website builder is good at

A website builder is a hosted service: you pick a template, drag in your text and photos, and pay a monthly or yearly fee that covers hosting, security and the editor itself. For many small businesses that's a reasonable deal.

Fast start. You can publish a decent page in a weekend.
Low first cost. There's no build invoice, only the plan.
No technical upkeep. The platform handles servers and security updates.
You're in control of small changes. New opening hours or a new photo take a minute.

The trade-off is that you rent the whole thing. You get the features the platform offers, in the way the platform offers them, at the price the platform sets.

What "custom website" means here

People use "custom" for very different things, so let me be precise. In this guide a custom website is one written in code for your business: no template, no page builder and no plugin collection. The design is made for your brand, the pages are built for what your customers need to do, and you own the code.

That's different from a premium theme with your logo on it. It's also different from WordPress, which deserves its own comparison. This guide is about hosted builders versus a site built from scratch.

Is a custom website worth it? Cost over three years

A sound way to compare is total cost over the life of the site, including your own time. Builder prices change and depend on the plan, so the builder figures below are assumptions you should replace with the current price of the plan you'd actually need.

Over three years	Website builder (example)	Custom website (my prices)
Build	Your own time: say 30 hours to choose a template, write, design and fix the mobile view	From Â£1,200 in the UK or â‚¬1,000 in Bulgaria for up to five pages, from â‚¬2,500 with bookings or a shop. Fixed in writing before work starts.
Running costs	Assume Â£30 a month for the plan, a booking or shop feature and one or two paid apps: about Â£1,080	Care plan from â‚¬49 a month for hosting, updates, backups and small edits: about â‚¬1,764
Changes	Your time, every time	Small edits included in the care plan, bigger changes quoted first
What you own at the end	Your text and images. The site itself stays on the platform.	The domain, the content and the code

So which is cheaper? In cash terms, the builder usually is, especially for a very small site. The gap closes once you put a price on your own hours, add the paid apps a growing business tends to need, and count the enquiries a slow or generic site quietly loses. That last item is the one that decides it, and it's different for every business. A cafÃ© that gets most customers from walk-ins can live happily on a builder. A guest house, a clinic or a trades business that gets most of its work from search often can't afford to.

Six differences that actually matter

1. Ownership and the cost of leaving

Hosted builders generally don't let you move your site's design and code to another host. If you outgrow the platform or its prices go up, you can take your words and photos with you, but the site itself is rebuilt somewhere else. With a custom site you own the code, so you can change hosting or hand it to another developer without starting again.

2. Speed on a phone

Builders have to support every possible layout, so each page tends to ship code for features you don't use. A custom site ships only what that page needs. Speed matters because people leave slow pages and because Google measures real-world loading speed. Don't take my word for it: run your current site through Google PageSpeed Insights on mobile and look at the field data, which comes from real visitors (a very quiet site may not have enough to show).

3. Search and AI engines

Builders cover the basics: titles, descriptions and a sitemap. Where they can get awkward is the detail: clean URLs that match how people search, proper language versions for a bilingual site, and structured data that describes your business accurately. On a custom site all of that is under your control, down to the exact HTML that search crawlers and AI engines receive. I cover the AI side in GEO for small businesses.

4. Features that fit how you actually work

This is the most common reason my clients switch. A builder's booking app works the builder's way. If your business has its own rules, such as seasonal prices, deposits, minimum stays, bundles, a quote form that calculates a price, or an enquiry that should land in your CRM, you end up stacking apps and workarounds, many with their own monthly fee. A custom site builds that logic once, in the way you already work.

Two examples from my own projects: A property agency in Plovdiv needed bilingual listings, natural-language search and a built-in CRM for leads. A handmade gifts shop needed a live chat the owner answers from Slack and paid courses with access control. Neither fits neatly into a builder template.

5. Who does the work: you or a web developer

With a builder, you're the web team. That's fine if you enjoy it. If you don't, the site slowly falls behind: old prices, a broken form nobody noticed, a blog last updated two years ago. With a custom site and a care plan, someone else keeps it working and you send changes by email.

6. Risk

Both options carry risk, just different kinds. With a builder, the risk is the platform: price rises, changed features or a plan you're forced onto. With a custom site, the risk is the developer. Reduce it by insisting on three things: you own the domain and the code, the site uses mainstream technology another developer can pick up, and the price and scope are fixed in writing before work starts.

When I'd tell you to use a builder

You're validating a new idea and don't know yet what the business will look like.
Your site is an online business card: what you do, where you are, how to contact you.
Customers mostly come from referrals or walk-ins, not from search.
Your budget for the next year is under a few hundred pounds, and you have the time to do it well yourself.

In those cases, spend the money on good photos and clear copy instead. You can always move later.

Signs you've outgrown a builder

You pay for three or more apps to make the site do what the business needs.
Customers phone or message to ask things the website should answer.
Competitors appear above you in Google for the services you actually sell.
Your booking or order process has a step you handle by hand every single time.
You need a second language and the builder's version of it feels bolted on.
Your mobile PageSpeed score is in the red and you can't do much about it.

If two or more of these sound familiar, a custom site is worth pricing up.

Moving from a builder without losing your Google rankings

If you switch, the move itself is where rankings get lost, so plan it:

List every URL on the old site, including blog posts and images that get traffic. Search Console shows which pages have impressions.
Keep the same URLs where you can. Where you can't, set up a permanent (301 or 308) redirect from each old URL to the closest new page.
Keep or improve the titles, headings and text of pages that already rank.
Launch, submit the new sitemap in Google Search Console, and watch the Pages report for errors over the next few weeks.

Done this way, any dip in rankings is usually small and short-lived, and a faster, clearer site often gains ground.

What a custom website from me costs

A business website of up to five pages starts from Â£1,200 in the UK, or from â‚¬1,000 for businesses in Bulgaria. Booking sites and online shops start from â‚¬2,500. Most projects take 3 to 8 weeks. You get a fixed price in writing before any work starts, the site launches on your own domain, and you own the code. After launch, a care plan from â‚¬49 a month covers hosting, updates, backups and small edits.

I work fully online with clients in the UK, the EU and the US as well as Bulgaria. Alongside client projects I work remotely for Cisco through SoftServe, so the same engineering habits (tests, reviews, careful releases) go into small-business sites too. See website development: prices, process and projects.

Frequently asked questions

Is a custom website better for SEO than Wix or Squarespace?

No, not automatically. A builder site with great content can outrank a badly made custom one. What a custom site gives you is control: speed, clean URLs, correct language versions and accurate structured data. On a competitive search, that control is often the difference.

Can I edit a custom website myself?

Yes, if you want to. I add a simple admin panel for the things you change often, such as prices, listings, opening hours or blog posts. For changes you make twice a year, it's usually quicker to send them over; small edits are included in the care plan.

Who owns a custom website?

You should: the domain, the content and the code. Make sure that's written into the contract. With me it is, and if we ever stop working together you keep everything.

How long does a custom website take?

About 3 weeks for a simple site, 5 weeks for a bilingual site with a blog, and 7 to 8 weeks for a site with bookings or a shop. You get a plan with a date for each step before work starts.

Can I start on a builder and move to custom later?

Yes, and it's often the smart order: prove the business first, then invest in the site. Keep a list of your URLs from day one and the move will be painless.

Not sure which side you're on? Send me your current site, or a few lines about your business, and I'll tell you whether a builder will do. If custom is the better fit, you'll get a fixed quote within 24 hours. Get in touch.

GEO for small businesses: how to get found and recommended by AI engines

Iliya Oblakov — Wed, 04 Nov 2026 15:22:16 +0000

The short answer: GEO, or generative engine optimisation, means making it easy for AI engines to find your business, understand what you do and mention or recommend you in their answers. That covers Google's AI Overviews and AI Mode, Gemini, Copilot, Perplexity, Claude and the rest. GEO for small businesses is mostly good SEO done properly, plus a reputation that exists outside your own website. You don't need special files, special markup or an agency that promises to "rank you in AI".

Below is what actually helps, what is hype, and a checklist you can work through this month. Where a claim comes from a study, I link to it. Where it comes from my own site, I say so.

What GEO means, in plain words

When someone asks an AI engine "who can build a booking website for my guest house?" or "best accountant for freelancers near me", the engine doesn't consult a secret list. It usually runs one or more web searches, reads a handful of pages, and writes an answer that names some businesses and links to some sources. GEO is about being one of the pages it reads and one of the names it trusts.

The term comes from a 2023 research paper by researchers at Princeton, IIT Delhi and other institutions. They found that adding statistics, quotations and cited sources to a page made it more visible in AI-generated answers, by as much as 40% in their test setup. That was a lab benchmark, not a live search engine, but the direction matches what Bing now recommends to site owners.

How AI engines find businesses

Different engines use different indexes, and that matters more than any trick:

AI engine	Where its sources come from	What that means for you
Google AI Overviews and AI Mode, Gemini	Google's search index. Google runs several related searches across subtopics (it calls this "query fan-out") and picks supporting pages from them.	Classic Google SEO is the way in.
Microsoft Copilot	Bing's index	Make sure Bing has crawled you. Many small businesses never check.
Perplexity	Its own crawler (PerplexityBot) and index	Don't block its crawler.
Claude	Web search results that independent tests have closely matched to Brave Search	Check how you appear on Brave Search too.
OpenAI's search	Its own search crawler (OAI-SearchBot); independent tests suggest it also draws on other search providers	Don't block its search crawler.

Google is explicit that there is nothing separate to do for its AI features. A page can appear as a supporting link if it is "indexed and eligible to be shown in Google Search with a snippet", and there are no extra technical requirements beyond that.

Ranking well still matters, but it isn't the whole story. In an Ahrefs study published in March 2026, only about 38% of the pages cited in AI Overviews ranked in Google's top 10 for the original question. Ahrefs puts most of the rest down to the related searches the engine runs on its own. A page that answers one specific question well can be cited even when it doesn't rank for the broad term.

What I see on my own small site

AI engines are not waiting for you to become a big brand. In the four weeks to 16 October 2026, my own site, which gets modest traffic, logged 99 visits from OpenAI's search crawler (OAI-SearchBot), 62 from ClaudeBot (Anthropic's training crawler), 18 from PerplexityBot and 14 from Brave's crawler. Over the same weeks Googlebot made 26 visits that I could verify against Google's published IP ranges. The AI crawler numbers are identified by user agent only, so treat them as indicative, but the pattern is clear: AI crawlers are already reading small sites like mine. The question is whether what they read is clear, current and worth citing.

Checking how crawlers see my site also caught a real mistake. My English blog posts were reachable under Bulgarian URLs too, marked as Bulgarian, so search engines saw duplicate pages in the wrong language. Each post now has one address only. That's the unglamorous side of GEO: a lot of the early work is removing things that confuse crawlers.

What actually helps

1. Let the crawlers in and give them real text

Your important pages should arrive as plain HTML with the full text, not as an empty shell that only fills in when JavaScript runs. Several AI crawlers don't run JavaScript at all. Then check you aren't blocking them: since July 2025, Cloudflare blocks AI crawlers by default on new sites unless you change the setting. Decide on purpose which crawlers you allow. Blocking training crawlers is a reasonable choice; blocking search crawlers keeps you out of the answers.

2. One clear page for each thing you sell

"Services" as a single page with six bullet points gives an AI engine nothing to quote. A page per service that says who it's for, what it costs (a "from" price is enough), how long it takes, where you work and how the process goes gives it a self-contained answer. In Whitespark's 2026 survey of 47 local search experts, a dedicated page for each service was rated the second most important factor for AI search visibility.

3. Lead with the answer, then prove it

Start each page and each section with a plain sentence that answers the question, then back it up: real prices, real timelines, named projects, numbers you've measured and links to sources. That proof is what the GEO paper found helps, and it's what Bing recommends too: clear headings, tables and FAQ sections, with claims supported by examples and data.

4. Get mentioned by name on other sites

This is the part most small businesses skip, and it may be the biggest lever. An Ahrefs analysis of 75,000 brands found that mentions of a brand across the web lined up with AI visibility far more closely than backlinks or Ahrefs' Domain Rating did. That's a correlation, not proof, and their sample was bigger brands, but it fits what the expert survey above found: being listed on expert-curated "best of" lists was rated the top factor, and prominence on sites that matter in your industry came third. In practice that means complete profiles on the directories your customers use, a local press mention, a talk at a trade association, a useful answer in a community forum, and a partner or supplier who mentions you by name.

5. Collect reviews on more than one platform

Reviews are both a trust signal for people and a source AI engines read. In BrightLocal's 2026 survey of US consumers, 47% said they wouldn't use a business with fewer than 20 reviews, and people used an average of six review sites. Ask every happy customer, and spread the requests across Google and one or two platforms that matter in your industry. Never pay for reviews or offer a discount in exchange for one.

6. Keep your business facts identical everywhere

Same business name, same description of what you do, same service area, same prices on your site, your Google Business Profile (if you're eligible for one), directories and social profiles. When sources disagree, an AI engine may repeat the wrong version or leave you out.

7. Update the pages that matter, for real

AI engines lean towards fresher sources: an Ahrefs study of about 17 million citations found that pages cited by AI engines were about 25% fresher on average than pages in Google's normal results (1,064 days old against 1,432). Review your pricing, service and "how it works" pages every three to six months and change the facts that changed. Changing the date without changing the content doesn't count.

What doesn't help (or barely does)

llms.txt files. Google says "You don't need to create new machine readable files, AI text files, markup, or Markdown to appear in Google Search." An Ahrefs study of 137,210 domains found 97% of llms.txt files received no requests at all in May 2026. Harmless if it's generated automatically, not worth an afternoon.
"AI schema". Structured data helps search engines understand who you are, so keep it accurate. But Google says there is "no special schema.org structured data that you need to add" for its AI features.
FAQ rich results. Google stopped showing FAQ rich results in May 2026. FAQ sections are still worth having for readers; the markup no longer earns a special listing.
Keyword stuffing. In the GEO paper it made pages less visible, not more.
Dozens of near-identical city or industry pages. Google treats them as doorway pages, which is spam.
Bought mentions and fake reviews. Google's guidance warns that manufactured mentions aren't effective, and fake reviews break platform rules and, in many countries, consumer law.

How to measure it without paying for a tool

No third-party tool can see inside Google's ranking or AI systems, as Google says plainly in its AI optimisation guide. What you can do for free:

Keep a prompt panel. Write down 10 questions a customer would ask, such as "who does X in Y" or "how much does X cost". Once a week, ask them in three or four AI engines and note whether you're named and which page is cited. Answers vary from day to day, so look at the trend over a month rather than a single check.
Use Search Console. Traffic from Google's AI features is counted in the normal Performance report, and since June 2026 there is also a Generative AI performance report. Watch which queries and pages grow.
Use Bing Webmaster Tools. Its AI Performance report shows when Copilot and Bing's AI answers cite your pages.
Check your server logs or analytics for visits from search and AI crawlers. If they never visit, start with step 1 of the checklist below, or run the 15-minute check of whether AI engines can read your site.

A 10-step GEO checklist for small businesses

Open your three most important pages with JavaScript turned off. Is the main text there?
Check robots.txt and your CDN or firewall settings. Are Googlebot, Bingbot and the AI search crawlers allowed?
Verify your site in Google Search Console and Bing Webmaster Tools, and submit your sitemap to both.
Make sure each service has its own page with who it's for, a starting price, timeline, area and process.
Rewrite the first paragraph of each of those pages so it answers the main question in one or two sentences.
Add one piece of proof per page: a named project, a measured result or a client quote you have permission to use.
Make your business name, description, area and contact details identical on your site and every profile.
Claim or complete two directory profiles that matter in your industry.
Ask your last five happy customers for a review.
Write your 10-question prompt panel and run it for the first time, so you have a baseline.

How I build this into client websites

Every site I build is server-rendered, so crawlers get the full text on the first request. Each service gets its own page with real prices and a plain-language answer at the top, the structured data describes the business accurately, and bilingual sites get one clean URL per language. At launch I connect Search Console and set up the basics for measuring results. None of that is a separate "GEO package". It's how a small business website should be built in 2026.

Custom business websites start from Â£1,200 in the UK, or from â‚¬1,000 for businesses in Bulgaria. Booking sites and online shops start from â‚¬2,500, and a care plan from â‚¬49 a month keeps the site updated afterwards. I'm a software engineer and I also work remotely for Cisco through SoftServe, which is where the habits of testing and measuring everything come from. If you're weighing up a website builder first, read custom website vs website builder.

Frequently asked questions

Is GEO different from SEO?

Mostly no. AI engines rely on search indexes, so the foundations are the same: crawlable pages, clear content, a good reputation. GEO adds more weight to two things: answers that stand on their own, and mentions of your business on other sites.

Do I need an llms.txt file?

No. Google says you don't need one to appear in its search features, and almost no AI crawler requests it. If your platform creates one automatically, leave it; otherwise spend the time on your service pages.

How long before AI engines mention my business?

There's no fixed timeline. Pages have to be crawled and indexed before they can be cited, so fixing crawl problems can show results within weeks. Building mentions and reviews takes months. Anyone promising a guaranteed AI recommendation by a date is guessing.

Can I pay to be recommended by an AI engine?

No, not in the organic answer. Some AI products show clearly labelled ads, which is advertising, not GEO. The organic recommendation has to be earned with clear pages and a real reputation.

Does GEO work for a local business?

Yes, and local businesses have an advantage: fewer, more specific competitors. Keep your Google Business Profile current if you meet customers in person, since Google says it uses that information in AI responses too. Then make sure your site and your reviews tell the same story.

Want to know how your business looks to AI engines? Send me your website and the service you most want customers to find, and I'll tell you what is most likely holding it back. Get in touch, or see website development prices and projects. For a local business that wants the full picture, the AI Visibility Audit checks what AI engines say about you and lists the fixes in order.

Can AI engines read your website? A 15-minute check for small businesses

Iliya Oblakov — Wed, 04 Nov 2026 15:21:42 +0000

The short answer: probably, but don't assume it: a robots.txt line, a firewall setting or text that only appears through JavaScript can hide a site from AI engines without anyone noticing. You can check all of it in about 15 minutes, for free. Look at your robots.txt, check your firewall or CDN settings, look at the page source with JavaScript out of the picture, fetch the page the way a crawler would, ask Google and Bing what they see, and check your logs for crawler visits. If all six checks pass, AI engines can read you. Whether they recommend you is a separate question, and I cover that at the end.

I ran every check below on my own site while writing this, and I quote its real crawler numbers. It's a small business site with modest traffic, so the numbers are closer to yours than anything a big publisher will show you.

Why "can they read it?" comes first

An AI engine can only mention a page it has fetched, or a page that sits in a search index it uses. Google's AI Overviews and AI Mode use Google's index, Copilot uses Bing's, and OpenAI, Perplexity and Anthropic run their own search crawlers. Google says there are no extra technical requirements for its AI features beyond being indexed and eligible for a snippet. So the first job is boring and mechanical: make sure nothing stops these crawlers at the door, and that the text is there when they arrive.

It's more common to fail this than you'd think. A security setting switched on by a host, a builder option ticked years ago, or a site that only fills in its text with JavaScript can each make a business invisible to some engines without anyone noticing.

The crawlers you need to know

Most AI companies run more than one crawler, and they do different jobs. This matters, because you can block training without blocking search:

Crawler (robots.txt name)	Company	What it does
OAI-SearchBot	OpenAI	Finds pages to show in its search answers. Block it and you won't appear there.
GPTBot	OpenAI	Collects content that may be used to train its models.
Claude-SearchBot	Anthropic	Indexes pages to improve search answers.
ClaudeBot	Anthropic	Collects content that may be used for model training.
PerplexityBot	Perplexity	Finds and links pages in its search results. Perplexity says it's not used for training.
Googlebot	Google	Google Search, including AI Overviews and AI Mode.
Google-Extended	Google	Not a crawler but a robots.txt switch: it controls whether your content may train Gemini models. Google says it has no effect on Google Search.
Bingbot	Microsoft	Bing Search, which Copilot relies on.

Sources: OpenAI's crawler page, Anthropic's crawler page, Perplexity's crawler page and Google's list of common crawlers. There are also "user" fetchers that visit a page when someone asks an AI engine about it right now. Perplexity notes that its user fetcher generally ignores robots.txt, because a person asked for the page.

Check 1: read your robots.txt (2 minutes)

Open yourdomain.com/robots.txt in a browser. It's a short text file. Look for two things:

A line Disallow: / under User-agent: *. That tells every crawler to stay away from the whole site. It's sometimes left over from when a site was being built, and it's the single most damaging line a small business site can carry.
A group naming one of the search crawlers in the table above (OAI-SearchBot, Claude-SearchBot, PerplexityBot, Bingbot, Googlebot) with Disallow: / under it.

Blocking the training crawlers (GPTBot, ClaudeBot, Google-Extended) is a reasonable business decision and doesn't remove you from search answers, while blocking the search crawlers does. If you don't have a robots.txt at all, crawlers treat the whole site as allowed, which is fine.

Mine is six lines long: everything is allowed except the admin, API and Rails system paths, plus a link to the sitemap.

Check 2: look at your CDN, firewall and builder settings (3 minutes)

robots.txt is a polite request. A firewall is a locked door, and it can block crawlers that your robots.txt welcomes. Since July 2025, Cloudflare blocks AI crawlers by default on new sites unless the owner changes the setting. If your site sits behind Cloudflare, open the dashboard, find the bot and AI crawler settings and decide what you allow, crawler by crawler.

Some hosts and website builders have their own switch for AI crawlers, often in the SEO or privacy settings. If you didn't set up the site yourself, ask whoever did. You want to know what is blocked and why, not to discover it a year later.

Check 3: look at the page without JavaScript (3 minutes)

Open one of your important pages, such as a service page, press Ctrl+U (or Cmd+Option+U on a Mac) to see the page source, and search for a sentence you can see on the page. If the sentence is in the source, the text arrives with the first response. If the source is mostly scripts and an empty container, the text only appears after JavaScript runs.

Google renders JavaScript before indexing, so a script-built page can still do fine in Google. You can't assume the same of every AI crawler, and none of the crawler documentation I linked above promises it. Your prices, your service area and your answers to common questions should be in the HTML itself. Every site I build is server-rendered for this reason.

Check 4: fetch the page the way a crawler does (2 minutes)

This one needs a terminal, but it's a single command. On a Mac or Linux, or in Windows PowerShell with curl.exe, run:

curl -s -o /dev/null -w "%{http_code}\n" -A "Mozilla/5.0 (compatible; OAI-SearchBot/1.4; +https://openai.com/searchbot)" https://yourdomain.com/

Swap in PerplexityBot/1.0 or Claude-SearchBot to test the others. On Windows, write NUL instead of /dev/null. A result of 200 means the page was served. 403 or 503 usually means a firewall or bot filter stopped the request. Some firewalls also check where a request comes from, not just its name, so a 200 here is a good sign rather than proof.

One side effect: your own test shows up in your analytics as a crawler visit. I found that out the hard way when my own checks added more than a hundred fake "Googlebot" visits to my stats in one afternoon. I left those out of the numbers below. Note the time you ran the test so you can leave it out later.

Check 5: ask Google and Bing what they see (3 minutes)

Both search engines will show you the page as their crawler received it, for free:

Google Search Console: paste your page into the URL Inspection bar. It tells you whether the page is indexed, and "Test live URL" then "View tested page" shows the HTML Google got. If the status is "Crawled, currently not indexed", Google can read the page but didn't think it was worth keeping. That's usually a content problem rather than a technical one.
Bing Webmaster Tools: its URL Inspection does the same for Bing. Because Copilot relies on Bing, this is the closest thing to a direct check for Copilot. Many small businesses have never verified their site in Bing at all. If that's you, it's the most useful 10 minutes you can spend this week.

Check 6: check who is actually visiting (2 minutes)

The final check is whether crawlers come at all. If your host gives you access logs, or your analytics records bots, filter by the crawler names above. Here is what my own site recorded in the four weeks from 21 September to 18 October 2026:

Crawler name in the request	Requests	Requests for real pages, or IP check
OAI-SearchBot	100	89
ClaudeBot	65	28
Googlebot	50	38 came from Google's published IP ranges, 12 did not
GPTBot	42	35
PerplexityBot	19	1
Bingbot	12	12, all from Bing's IP ranges

For scale: in the same four weeks, people viewed pages on the site 141 times. Three things stand out.

AI search crawlers already read small sites. OpenAI's search crawler made more than twice as many requests as genuine Googlebot. You don't need to be a famous brand for AI engines to look at you. What they find when they arrive is up to you.

The name in a request is only a claim. Most of the "ClaudeBot" and "PerplexityBot" requests asked for things like /proc/self/environ and /wp-json. Those are probes looking for server secrets and WordPress weak spots, and nothing on my site links to them, so they almost certainly came from scanners borrowing a well-known name. The same goes for the 12 "Googlebot" requests from outside Google's addresses. Google and Bing publish ways to verify Googlebot and verify Bingbot, and OpenAI and Perplexity publish their IP ranges. Before you conclude "an AI crawler visited my site 300 times", check how many of those visits were real.

No visits at all is a finding too. If a search crawler never shows up over a month, go back to checks 1, 2 and 5. The usual causes are a block you didn't know about, or a site no search engine has been told about, with no sitemap submitted and no links pointing to it.

What to do with the results

What you found	What to do
`Disallow: /` for all crawlers or for a search crawler	Remove it today, unless you blocked that crawler on purpose. Keep training-crawler blocks if you want them.
403 or 503 for a crawler name in check 4	Review the bot settings in your CDN, firewall or host. Allow the search crawlers you want.
The text isn't in the page source	Ask your developer about server-side rendering, or move the key facts (services, prices, area, contact) into the HTML.
"Crawled, currently not indexed" in Search Console	Make the page more useful and more distinct: a direct answer at the top, real prices, a named project, fewer near-duplicate pages.
Site not in Bing Webmaster Tools	Verify it (you can import from Search Console) and submit your sitemap.
No crawler visits in a month	Submit your sitemap to Google and Bing, and get linked from a few profiles and directories you control.

What this test can't tell you

Passing all six checks means AI engines can read your site. It doesn't mean they will recommend you. That depends on whether your pages answer the questions customers ask, and on what the rest of the web says about you: reviews, directory listings, mentions by name on other sites. I wrote a separate guide on that part: GEO for small businesses, with a 10-step checklist.

The easiest way to see where you stand is to ask. Write down five questions a customer would type, such as "who builds booking websites for guest houses?" or "best accountant for freelancers in Leeds", put them to three or four AI engines and note whether you're named and which page gets cited. Repeat it monthly, because the answers change.

If you'd rather have it done for you, my AI Visibility Audit runs these checks and the customer questions for a local business and turns the results into a prioritised fix list. If your site itself is the problem, I build hand-coded, server-rendered business websites from Â£1,200 in the UK, or from â‚¬1,000 for businesses in Bulgaria; see website development prices and projects. I'm a software engineer and I also work remotely for Cisco through SoftServe, so testing before trusting is a habit.

Frequently asked questions

Should I block GPTBot and ClaudeBot?

It's your choice, and it doesn't affect whether you appear in search answers. Those two collect content for model training. The search crawlers (OAI-SearchBot, Claude-SearchBot, PerplexityBot) are separate, and you can allow them while blocking training.

Will blocking Google-Extended hurt my Google rankings?

No. Google says Google-Extended only controls whether your content may be used to train Gemini models and has no effect on Google Search, which includes AI Overviews.

My site is on Wix or Squarespace. Can AI engines read it?

The big builders generally send page text in the HTML, but don't assume: run checks 3 and 4 on your own pages, and look for any AI crawler setting in the builder's SEO options. Builder or not, the six checks work the same way.

How often should I repeat these checks?

After any change of host, CDN, builder or security plugin, and otherwise every three months. The prompt test with real customer questions is worth doing monthly.

Do I need an llms.txt file?

No. Google says you don't need special AI files to appear in its search features. If your site generates one automatically, it does no harm. Spend the time on checks 1 to 6 instead.

Ran the checks and found something you're not sure about? Send me your website address and what you found, and I'll tell you what it means and what I'd fix first. Get in touch.

How to use Claude Code and Codex together: setup lessons from my review gate

Iliya Oblakov — Wed, 04 Nov 2026 15:21:31 +0000

If you want to use Claude Code and Codex together, the first decision is who does what. In my setup Claude Code writes the code and Codex reviews it read-only, and a small set of bash scripts refuses the merge unless the exact commit has a test pass and an ACCEPT. Most guides stop at shared instructions and separate worktrees. This post is about the part after that: what I had to set up so a review and a test run actually mean something, and the places where the setup surprised me.

Use Claude Code and Codex together by giving each one job

Claude Code writes in its own git worktree. Codex reviews the result and ends its final message with a section that starts with one single Verdict: ACCEPT or Verdict: CHANGES REQUIRED line, followed by the findings. I give the writing to Claude Code because writing is where context piles up: the plan, the briefs, the worktrees and the gate logs. Review needs much less, mostly the diff, the rules and what the change was meant to do.

The reviewer never fixes anything. The review prompt in my gate says "You review; you never fix" and asks for each problem to be described so the author can fix it in a new commit. That keeps every change on one side of the table, and the fix gets its own review.

The roles can be swapped. In my gate, BUILDER=codex makes Codex the writer and Claude Code the reviewer.

Make read-only actually read-only

For Codex the review call is:

codex exec -s read-only --color never --output-last-message <file> -

The sandbox lets Codex read files and run read-only commands such as git diff, and it cannot write. Two things in your Codex config still come along for the ride:

MCP servers configured in ~/.codex/config.toml start for the review too. A server that can change things outside the sandbox works against a read-only review, so set enabled = false on it while reviewing.
Hooks also run under codex exec. A Stop hook that asks Codex to continue after its review can replace the final message with an empty one. The gate then finds no verdict and exits 1. It keeps the diagnostic log but saves no verdict, so a hook meant to keep Codex working ends up with a review that says nothing at all.

When Claude Code is the reviewer, it gets Read, Grep and Glob as its only tools. It cannot run git, so the script puts the commits and the full diff into the prompt.

Keep the shared rules short

Both engines need the same house rules. My gate has two short snippets, one for the project's CLAUDE.md and one for its AGENTS.md. They tell the writer to commit one change and stop, to leave the .ai/ folder alone and never to merge, and they tell the reviewer to stay read-only.

Keep the Codex part short. Codex stops adding instruction files once their combined size reaches project_doc_max_bytes, which is 32 KiB by default, so rules at the end of a long AGENTS.md may never reach it.

The same files are also a way in: both engines follow whatever instruction file they load, including one you did not write. A planted AGENTS.md in Downloads shows how to check which files Claude Code and Codex load on your machine.

Tie every review and test run to a commit

In my setup this is the core of the loop. Each piece of evidence is named after the commit it covers:

gate.sh runs your test command on a clean checkout and writes a pass record named after the commit.
review.sh sends the commits and the diff to the other engine and saves the verdict under the commit it reviewed.
merge-check.sh refuses unless the commit you are on has both, and the ACCEPT came from a reviewer that is not the builder.

A new commit starts with no evidence, so an ACCEPT for an older commit cannot cover code nobody reviewed. In a walkthrough with a stand-in reviewer, where no model is called, the staged bug is a sum.sh that skips the first argument, and the test only checks sum 0 4, which is the one kind of input where skipping a zero gives the right answer. The tests pass, the review asks for changes, and the fix commit has to earn its own pass and its own ACCEPT.

Commit before you check anything

All three scripts refuse a checkout with uncommitted or untracked files, because a test can pass on a file missing from the commit. The setup asks you to add .ai/ to the project's .gitignore. Try it on a scratch repository and the edited .gitignore is itself an uncommitted change, so the first thing the gate refuses is the .ai/ line you added to .gitignore for the gate itself.

gate: REFUSED: uncommitted changes, untracked files or flagged files (or git failed); commit, remove or unflag them first

The check also runs after the tests. A test command that leaves a file behind fails the run even when every test passed:

gate: the run left changed, untracked or flagged files (or git failed)

If your suite writes snapshots or build output into the repo, point it at a folder git ignores and commit that .gitignore change.

The pitfall: a narrowed test command still passes

The gate records a pass when the test command exits 0 on a clean checkout and the test count check accepts the output. It does not know which tests the project has. Here is the case, with Node 20.19: a scratch repository where add() returns the wrong result, a test for add() in test/add.test.js and a test for another function in test/format.test.js.

GATE_CMD="node --test test/" gave gate: FAIL (exit 1) and no pass record.
GATE_CMD="node --test test/format.test.js" gave gate: PASS on <sha> and wrote a pass record for the commit, with add() still wrong.

With default settings the built-in count check only fails a run with empty output or test summaries that add up to zero, and here one test ran. The pass record keeps the command on its Command: line, and merge-check.sh does not compare it with anything.

Two settings reduce the risk. Set GATE_COUNT_RE and set GATE_MIN_TESTS to the number of tests the project has. With GATE_CMD="node --test test/format.test.js", GATE_COUNT_RE='^# pass ([0-9]+)$' and GATE_MIN_TESTS=2, the run fails:

gate: the output reports 1 tests, fewer than GATE_MIN_TESTS=2; set GATE_COUNT_RE or GATE_MIN_TESTS (README)

You have to raise that number when you add tests, and it compares the total the output reports, so it does not show which tests ran. The second layer is the review: the prompt asks the reviewer to check anything that weakens an existing check, which covers a test script narrowed in a commit. A command typed on the command line never appears in the diff, so the count check is the only thing that sees it, and a review can miss things anyway. Before you trust a pass record, read its Command: line.

What the gate does not do, and the kit

The gate does not make the code correct, and it does not push or merge.

If you later want the merge itself handled, the paid Two Engines Kit adds a merge script pinned to the gated commit, a queue merge, one rulebook that both engines load and an installer with backups that uninstall.sh restores byte for byte. It is built on information gathered since the first Codex and Claude CLIs.

A planted AGENTS.md in Downloads: how to check your Claude Code and Codex setup

Iliya Oblakov — Wed, 04 Nov 2026 15:20:55 +0000

AGENTS.md and CLAUDE.md files are instructions that AI engines read at startup and follow. A security report published on 22 October 2026 shows what happens when one of those files lands somewhere you did not expect, and the folder it landed in was ~/Downloads.

This post covers what was reported, how to check where Claude Code and Codex load instruction files from on your own machine, and a short checklist.

What happened

On 22 October 2026, Forever Security published "Markdown Is the New Executable", by Gal Weizman and Omer Samet (report). The company says it stopped a coding agent on a customer's machine from installing function-color, a known malicious npm package. It traced the install back to an AGENTS.md file in the customer's ~/Downloads folder, written to look like ordinary engineering notes. The report says nobody knew how the file got there.

BleepingComputer covered it on 25 October (article), and The Hacker News on 26 October (article).

The researchers point at two behaviours that are each normal on their own. AI engines read and follow the instruction file in the folder they start in, and a web page can save a file into Downloads, often without a prompt. Forever built a proof-of-concept page that downloads an AGENTS.md silently. The Hacker News notes it is not known whether a real attacker used that route against the customer. BleepingComputer adds that in its own test Brave asked before saving the file, and that Chrome, Edge and Firefox show a download notification by default.

Codex. The planted file told Codex to append a [mcp_servers.project-tools] block to ~/.codex/config.toml and then start a child codex exec with --dangerously-bypass-approvals-and-sandbox, framed as routine setup. Forever says Codex ran the malware in more than 90% of its attempts. Most of that testing used a harmless stand-in that only opens a calculator, which is how BleepingComputer describes its 90% figure, and Forever ran the real malicious package once, inside an isolated VM. Forever also notes that Codex only obeys an AGENTS.md in a project it trusts, and that Downloads qualifies once you have worked there. Because ~/.codex/config.toml is machine-wide, the added server loads in every later Codex session, in any folder.

Claude Code. Forever wrote its own test CLAUDE.md, modelled on the attacker's file. It asked Claude Code to save ANTHROPIC_BASE_URL, pointing at a server Forever controlled, into .claude/settings.json. Forever says the write got through about half the time, and that once it is written the OAuth token goes to that server, which can then answer as the model and send back tool calls. Code execution inside the same first session worked about a fifth of the time.

Forever's position, quoted by both outlets, is that "There is nothing here for OpenAI or Anthropic to patch", because the AI engine is doing what it was built to do. In Forever's telemetry about half of its customers run a coding agent inside their Downloads folder. Weizman told BleepingComputer that Claude Code alone launched more than 1,300 sessions from that location. According to Forever, npm has since removed function-color.

How to check your own Claude Code and Codex setup

The steps below follow the official docs for Claude Code and Codex, which I read on 29 October 2026.

Know where each AI engine looks

Codex, per its AGENTS.md guide:

Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md (under CODEX_HOME instead, if you set it).
Project: every directory from the project root (usually the Git root) down to the folder you launched from. In each one it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. When there is no project root, it checks only the current directory, which is the usual Downloads case.

Claude Code, per its memory docs:

~/.claude/CLAUDE.md, plus CLAUDE.md and CLAUDE.local.md in the folder you launch from and every folder above it.
AGENTS.md: the docs say that by default Claude Code reads it only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it, and that reading AGENTS.md directly needs v2.1.277 or later. Your own ~/.claude/CLAUDE.md does not count, so it does not stop an AGENTS.md from loading. In an interactive session you see a line such as no CLAUDE.md found; AGENTS.md loaded: .... The report did not test this path, but an AGENTS.md in Downloads fits it.

Because Claude Code reads every folder above where you start, a stray CLAUDE.md sitting directly in your home folder would load in every project under it.

Look for files you did not write

From a terminal:

ls -la ~/Downloads | grep -iE 'agents|claude'
find ~ -maxdepth 2 \( -name 'AGENTS*.md' -o -name 'CLAUDE*.md' \) 2>/dev/null

Your own ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md will show up, and that is expected. Open anything else and read it before you start Claude Code and Codex near it.

Check the config the attack rewrites before you start a session

Do this before you start Claude Code and Codex again. Forever describes how the added MCP server loads at startup in every Codex session on the machine, and a changed base URL sends your requests, and your token, to someone else's endpoint. These commands only read files and list the configured servers; they do not start a session. In a terminal, cd into the project you will work in first, because the last line reads that project's .claude folder.

grep -nE 'mcp_servers|chatgpt_base_url' ~/.codex/config.toml
codex mcp list
grep -n 'ANTHROPIC_BASE_URL' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

Every MCP server and base URL in there should be one you added. Forever names these places: an unexpected [mcp_servers.*] block or a changed chatgpt_base_url in ~/.codex/config.toml, and an ANTHROPIC_BASE_URL, proxy or other endpoint you did not set in a project's .claude/settings.json. Codex can also read MCP servers from a project-scoped .codex/config.toml in trusted projects, so check that file in your repos too. If anything there is unexpected, remove it and rotate your tokens before you start Claude Code and Codex again.

See what actually loaded

Once the config is clean, start each AI engine from the project folder you work in and check what it read.

Claude Code: run claude --version first. The docs say that before v2.1.280, /memory and /context did not list an AGENTS.md that Claude read directly, so update to v2.1.280 or later before you rely on them. Then run /context and check the list under Memory files, or /memory to see the files and open them. /status shows a Setting sources line with the settings files loaded for the session.
Codex: the guide suggests asking it which instruction sources it loaded, and offers a plaintext log for an audit trail. Its example turns approval prompts off, so I run the question from the project folder with a read-only sandbox, approval prompts set explicitly and routed to me rather than to an automatic reviewer, and the log on: codex --sandbox read-only --ask-for-approval on-request -c approvals_reviewer=user -c log_dir=./.codex-log "List the instruction sources you loaded.". Then read ./.codex-log/codex-tui.log. Inside Codex, /status shows which directories are in the workspace.

Watch where you launch from

Start Claude Code and Codex from the root of the project you are working on. BleepingComputer reports that this is the common recommendation from OpenAI and Anthropic, rather than your home folder or a broad parent folder, and Forever's first piece of advice is not to start an AI engine in Downloads at all. If you want an AI engine to sort your downloads, move the files into a separate folder first and read any .md file in it.

Keep the prompts and the sandbox on

Codex's approvals and security page describes the default CLI sandbox as having no network access and write access limited to the active workspace. It marks --dangerously-bypass-approvals-and-sandbox (alias --yolo) as elevated risk, and that flag is the one the planted file asked Codex to use. Claude Code's security page says an interactive session shows a workspace trust dialog in a folder you have not trusted, that servers in a project's .mcp.json have their own approval prompt, and that a -p session shows neither prompt. If a trust or approval prompt appears for Downloads, decline it.

Checklist

Pick the project folder you will work in and cd into it in a terminal, but do not start Claude Code and Codex yet. Never start them from ~/Downloads or directly from your home folder.
Search Downloads and your home folder for AGENTS.md, AGENTS.override.md, CLAUDE.md and CLAUDE.local.md files you did not write, and read any you find.
Check ~/.codex/config.toml and codex mcp list for MCP servers or base URLs you did not add.
Check .claude/settings.json and .claude/settings.local.json for an ANTHROPIC_BASE_URL you did not set. Remove anything unexpected and rotate your tokens first.
Only then start Claude Code and Codex from the project folder. Run /context in Claude Code (v2.1.280 or later, since earlier versions left a directly read AGENTS.md off that list), ask Codex with a read-only sandbox and approval prompts on to list its instruction sources, and compare both lists with the files you expect.
Keep approval prompts and the sandbox on, and treat any instruction to bypass them as a red flag.
If you find a planted file, assume the token leaked and rotate it, as Forever advises.

Why I keep my rules files readable

I think this report is a good reason to keep instruction files small enough to read in one sitting. Forever says the attacker's file was a 13 KB "Engineering Work Guidelines" document, and that the long, ordinary framing is what got it through. A file that size is hard to check line by line.

That is how I set up the Two Engines Kit. It gives Claude Code and Codex one rulebook: the installer points ~/.claude/CLAUDE.md at the shared rules and builds ~/.codex/AGENTS.md from them, previews each change and asks before it makes it. The hooks are plain text you can read, and Codex reviews read-only. It does not stop a planted file, so the checks above still apply. It is built on information gathered since the first Codex and Claude CLIs. If you want the workflow behind it, I wrote it up in How to use Claude Code and Codex together.

CLAUDE.md vs AGENTS.md: one rules file for Claude Code and Codex

Iliya Oblakov — Wed, 04 Nov 2026 15:20:44 +0000

Put the shared rules in AGENTS.md. By default, Claude Code reads that file directly from v2.1.277 when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or any folder above it, and Codex reads it out of the box. If you keep a CLAUDE.md for lines only Claude Code needs, start it with an import of that file: @AGENTS.md in a CLAUDE.md next to it. Then check what loaded in both AI engines, because one stray file can split them without a word.

How each engine finds its rules

Claude Code starts at the working directory and looks up. Codex starts at the project root, typically the Git root, and walks down to the current directory. The Claude Code memory docs and the Codex AGENTS.md guide each cover one side. This table puts them next to each other, as checked on 30 Oct 2026.

	Claude Code	Codex
Files it reads	`CLAUDE.md`, `.claude/CLAUDE.md` and `CLAUDE.local.md` in the working directory and above. `AGENTS.md` from v2.1.277, by default only when none of those exist.	`AGENTS.override.md` or `AGENTS.md` in the Codex home (`~/.codex` by default). Then, from the project root down: `AGENTS.override.md`, `AGENTS.md`, then names in `project_doc_fallback_filenames`. At most one file per directory.
Files it ignores	`AGENTS.local.md`, `AGENTS.override.md` and anything under `.agents/`.	Empty files, plus `CLAUDE.md` and any other name missing from the fallback list.
Order and precedence	By default a `CLAUDE.md` takes the place of `AGENTS.md`. With `claude-md-and-agents-md`, each directory's `CLAUDE.md` files come first and its `AGENTS.md` after. An `@AGENTS.md` import comes before the lines below it.	Codex home first, then root down, joined with blank lines. Files closer to the current directory come later and override earlier guidance.
Size limits	Target under 200 lines per `CLAUDE.md`. A file over 4 MiB is skipped. Imports don't reduce context.	Stops adding files once the combined size reaches `project_doc_max_bytes`, 32 KiB by default.
How to check what loaded	`/context` (under Memory files), `/memory`, and the `no CLAUDE.md found; AGENTS.md loaded` line.	Ask with `codex --ask-for-approval never "Summarize the current instructions."`, or read the TUI log.
Where review rules go	`CLAUDE.md` for `/code-review` and the Code Review service. `REVIEW.md` for the service only.	A `## Code Review Rules` section in the `AGENTS.md` closest to the code, for Codex code review in GitHub.

Set up one rules file in 6 steps

1. Write the rules in `AGENTS.md`

Put every rule both AI engines must follow in AGENTS.md at the repo root, in the file's own text. Keep it short. Codex stops adding files at 32 KiB by default, and the Claude Code docs target under 200 lines per CLAUDE.md. Splitting the file with imports won't buy you room in Claude Code, because imported files load with the file that imports them.

2. Decide if you need a `CLAUDE.md` at all

With only AGENTS.md, and no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere up the path, both AI engines read the same file. Start there. Your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files don't count for that check, and they keep loading alongside AGENTS.md.

Lines only Claude Code should see don't need one: put them in .claude/rules/, which keeps loading next to AGENTS.md. A project CLAUDE.md is still an option if you'd rather keep those lines in one file. It's also the fallback for a session that reads CLAUDE.md files only. Before v2.1.281 that included some Amazon Bedrock sessions and sessions with telemetry disabled.

3. If you keep one, import `AGENTS.md` at the top

@AGENTS.md

## Claude Code only

Use plan mode for changes under `src/billing/`.

Claude Code reads the imported file first, then the lines below it. Keeping the import never makes it read AGENTS.md twice.

Three details:

The path resolves from the file holding the import, so this line means the AGENTS.md next to that CLAUDE.md. In .claude/CLAUDE.md, write @../AGENTS.md to reach the one at the repo root.
An import that resolves outside the working directory triggers a one-time approval dialog per project. Decline it and the imports stay disabled.
Write the line bare. Import parsing skips code spans and fenced code blocks, so an @ path in backticks stays literal.

A CLAUDE.md that only says "read AGENTS.md" in words is weak. Claude Code sees the file only if it decides to open it. Replace the sentence with the import, or delete that CLAUDE.md.

4. Symlink only if it fits

ln -s AGENTS.md CLAUDE.md

This works when you need no lines just for Claude Code and nobody on the repo uses Windows. Claude Code's Edit and Write tools refuse to write through the link and point it to the target, so edits land in AGENTS.md. With any Windows user on the repo, use the import.

5. Leave `AGENTS.override.md` alone unless you mean it

In each directory Codex checks AGENTS.override.md first and reads at most one file, so an override hides the AGENTS.md beside it from Codex. Claude Code doesn't read overrides at all. Create one only for a rule you want in Codex and nowhere else.

6. Verify both AI engines

In Claude Code, start a new session:

With a CLAUDE.md (import or symlink), run /context and confirm CLAUDE.md appears under Memory files.
With AGENTS.md alone, an interactive session shows a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. From v2.1.280 you can also run /memory and look for the file's path. Older versions leave an AGENTS.md read this way off that list, so rely on the startup line there.

In Codex, run these only in a repo you already trust. The first goes in the repo root and the second checks a nested folder:

codex --ask-for-approval never "Summarize the current instructions."
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

For a record of what loaded, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log. Codex builds its chain once per run, so restart it in the target directory after an edit. There's no cache to clear.

Traps that split the two AI engines

`CLAUDE.local.md`

Add a CLAUDE.local.md for your personal, uncommitted notes in a project that relies on AGENTS.md, and Claude Code stops reading AGENTS.md. Codex keeps reading it. That's a lot of power for a file nobody commits. To keep both, run /config and set Project instructions to claude-md-and-agents-md.

A `CLAUDE.md` in a parent folder

The check covers the working directory and every folder above it. A CLAUDE.md above the repo silently turns off the direct AGENTS.md read under the default setting, and Codex carries on with AGENTS.md. ~/.claude/CLAUDE.md is exempt. If the no CLAUDE.md found line is missing from a new session, look up the path first.

`AGENTS.override.md`

Rules placed here reach Codex only. If Codex follows guidance you can't find, look for an override higher in the tree or in the Codex home.

The 32 KiB Codex cap

The cap applies to the combined size of the chain, and Codex stops adding files once it reaches project_doc_max_bytes. A file that's fine in Claude Code can still run past it. Raise the limit or split the rules across nested directories.

`@` lines in `AGENTS.md`

Claude Code expands @path imports inside an AGENTS.md it reads. The Codex guide describes no import syntax, so don't count on an @ line in AGENTS.md reaching Codex. Put rules Codex must follow in the file's own text.

A `SessionStart` hook that prints `AGENTS.md`

This is an old workaround. Remove it once Claude Code reads AGENTS.md directly, because it adds a second copy to the context.

`/import`

/import appends a one-time copy of AGENTS.md into the matching CLAUDE.md. Later edits to AGENTS.md don't reach that copy. The @AGENTS.md line pulls in the live file instead.

Windows symlinks

Creating a symlink on Windows needs Administrator privileges or Developer Mode. Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves a one-line CLAUDE.md in place of your instructions.

Where review rules go

Codex code review in GitHub reads a ## Code Review Rules section in the AGENTS.md closest to the code. Put repo-wide checks at the root and service checks in nested files.

Claude Code has two review tools, and they read different files. The local /code-review command reads CLAUDE.md files and not REVIEW.md. The managed Code Review service on GitHub pull requests reads CLAUDE.md and REVIEW.md, and it takes REVIEW.md from the base or default branch, never from the pull request's own changes. Guidance you want in both goes in CLAUDE.md.

None of this blocks anything. In Claude Code, CLAUDE.md and AGENTS.md are context, not enforced configuration. To block an action whatever Claude Code decides, use a PreToolUse hook.

Checklist

AGENTS.md holds every rule both AI engines must follow, in its own text.
Claude Code is on v2.1.277 or later.
No CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or above it, unless you meant it.
Any CLAUDE.md you keep is either a symlink to AGENTS.md or a regular file that starts with a bare import of it (@AGENTS.md next to it, @../AGENTS.md from .claude/CLAUDE.md), with lines only Claude Code needs below it.
No CLAUDE.md tells Claude Code in words to read AGENTS.md.
No CLAUDE.md symlink exists if anyone on the repo uses Windows.
No AGENTS.override.md exists in the tree or the Codex home, unless you want Codex to differ.
The combined Codex instructions fit under 32 KiB, or you raised project_doc_max_bytes.
No SessionStart hook prints AGENTS.md.
A new Claude Code session shows CLAUDE.md under Memory files in /context, or the AGENTS.md loaded line at startup.
codex --ask-for-approval never "Summarize the current instructions." from the repo root gives back your rules.
Codex review rules sit under ## Code Review Rules in AGENTS.md, and Claude Code review rules sit in CLAUDE.md.

How I keep one set of rules across repos

I use the same split for the rules that follow me across repos. In my Two Engines Kit for Claude Code and Codex, RULES.md holds the shared rules, and claude.md and codex.md hold the few lines that differ. Claude Code imports the live files and sync.sh builds the Codex copy. The installer points ~/.claude/CLAUDE.md at the shared rules, builds ~/.codex/AGENTS.md from them, previews each change and asks, and backs up what it replaces. uninstall.sh restores it.

FAQ

Does Claude Code read AGENTS.md?

It does, from v2.1.277. By default it reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it.

Should I symlink CLAUDE.md to AGENTS.md?

Only if you need no lines just for Claude Code and nobody on the repo uses Windows. In every other case, use the @AGENTS.md import.

Why is my AGENTS.md not loading in Claude Code?

Check these in order:

Your version: reading AGENTS.md directly needs v2.1.277.
A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it.
The Project instructions value in /config: the claude-md and managed-only values don't give you the direct read.
The session type: before v2.1.281, some sessions read CLAUDE.md files only, so import AGENTS.md from a CLAUDE.md there.
The list itself: before v2.1.280, /memory and /context didn't show an AGENTS.md read directly, so the file can load and stay off the list.

Does Codex read CLAUDE.md?

No, not by default. It reads AGENTS.override.md, AGENTS.md and any names in project_doc_fallback_filenames in ~/.codex/config.toml. Fallback names come last and Codex reads at most one file per directory, so a directory's AGENTS.md still wins over a fallback.

How big can AGENTS.md be?

Codex stops adding files once the combined size reaches 32 KiB by default. Raise project_doc_max_bytes or split the rules across nested directories. On the Claude Code side, the docs target under 200 lines per CLAUDE.md and Claude Code skips a file over 4 MiB.

What is in my Two Engines Kit for Claude Code and Codex, and the numbers behind each part

Iliya Oblakov — Sun, 25 Oct 2026 07:05:36 +0000

If you use Claude Code and Codex on the same projects, you probably keep two rule files, review by hand and push more often than you want to. The Two Engines Kit is the set of files I run both engines with, packed so one script installs them. I've been building it since the first Codex and Claude CLIs, and every number below comes from my own logs on my own projects. This post walks through each part, what it does and the measurement that made me add it.

Who does what

In my setup Claude Code writes and Codex reviews. An orchestrator session in Claude Code plans the work, writes the briefs, starts workers in their own git worktrees, reads their diffs, runs the local gate and merges. Workers never push. For every pull request that is ready, a Codex session reads the diff in a read-only sandbox and has to end with a verdict.

I picked a reviewer from a different company because it has different blind spots. On one pull request this month the first Codex review came back with 2 blockers and 8 should-fix findings. That is one data point, and it is the reason the loop exists. Nothing in the kit stops you from swapping the roles.

Which model gets which job

I ran the same task on both engines: a Tetris implementation against 44 hidden tests, three runs each, on 12 October.

Engine and model	Score	Median time	Median cost, API-equivalent
Claude Code, Opus 5.5 at xhigh	44/44 in all three runs	21:17	$4.47
Codex, GPT-6.1-Sol at xhigh	44/44 in all three runs	18:13	$0.50

Same score, and Opus cost 8.9 times as much. Inside Claude Code at effort high, Opus 5.5 and Sonnet 5.5 both passed 44/44 in every run, and Haiku 5.5 passed in two of three. The median cost was $1.61 for Opus, $0.72 for Sonnet and $0.19 for Haiku.

So the kit routes work by what a mistake costs. Bounded implementation with a clear brief goes to Sonnet. Haiku gets search, extraction and listing, where a wrong answer is cheap to spot. xhigh and max effort go to design-heavy slices, the first review of a pull request and hard debugging. The routing lives in config/efforts.md as tables you can edit, and every model name is plain text, so you can change it when the names change.

One rulebook for both engines

Two engines with two rule files means every rule change gets made twice, or more often once. In the kit you edit one file, rules/RULES.md. Claude Code reads it through @ imports in ~/.claude/CLAUDE.md, and sync.sh builds ~/.codex/AGENTS.md for Codex from the same source. The first rule sets the order when two rules disagree: your current message, then the project's rule file, then the global rules, then memory notes.

The installer also turns off Claude Code's commit and PR attribution, because the rules say no AI attribution in commits. It raises Codex's project_doc_max_bytes to 64 KiB too, because an AGENTS.md past the default limit gets cut off and Codex never sees the rules at the end.

The review loop

cross-review.sh refuses a checkout with uncommitted or untracked files, runs the Codex review and reads the verdict from the reviewer's final message only. It accepts the result only when Codex exited 0, the checkout is unchanged and the final message has exactly one Verdict: line. Then it writes a verdict file named after the reviewed commit. A crash, a cut-off answer or a moved checkout gives exit 1 and no verdict file.

I added the verdict file after one night in October when I found four test-only commits that had never been reviewed. One was already merged and the other three were in the merge queue. With REQUIRE_REVIEW=1, merge-pr.sh now refuses any commit without an ACCEPT file for that exact commit.

The local gate and the GitHub Actions bill

One private repository spent about 2,100 GitHub Actions minutes in its first five days of hosted CI, on a free tier of 2,000 minutes a month. After that, every check runs on my machine first and the work is pushed only after it passes there.

workflow/bin/local-ci.example.sh is the skeleton you fill with your own test commands. It takes one machine-wide lock so two gates never share the CPU and ports, it runs with a clean environment so a stray .env can't change the result, and after a full pass on a clean tree it writes a pass record named after the commit. merge-pr.sh refuses to push without that record for the exact commit and tree. After it pushes, it merges with GitHub's sha parameter, so GitHub refuses the merge if the branch head moved in between. DRY_RUN=1 runs every local check and prints the push and API calls instead of making them.

My own gate runs 40 to 43 checks. Run one group after another, a full pass took 35 to 40 minutes, and split into five parallel lanes it takes about 11 minutes on that machine. The skeleton in the kit has no parallel lanes, and the guide says so.

The 3-agent cap and cleanup

At most three agents run at once, and that count includes the review session and any helper a worker starts. A week after I set the cap, I saw four agents running while my list showed three, because a worker had started a helper. Since then the first line of worker-rules.md forbids workers from starting helpers.

Cleanup is a hard rule in RULES.md because of two days on one machine. On 7 October one cleanup removed 29 merged worktrees (24 GB) and 31.2 GB of Docker build cache. On 17 October another removed 69 worktrees and 88 merged branches, and disk use went from 184 GB to 76 GB.

Optional memory

If you run your own MCP memory server, the memory module lets both engines save decisions and facts as short notes. A Stop hook asks once per turn for a note when the turn did real work and saved nothing. Once a week one Claude Code session proposes corrections and a second session checks each one against the original notes before anything is written. The first run, on 22 September, made 9 proposals, applied 8, and the verifier rejected 1. The recall test was 18 of 18 before and after. No server is included, and without one the installer skips the module.

What you need and how it installs

You need bash 4 or newer, python3 3.9 or newer, git, and Claude Code and Codex CLIs, both signed in. gh is needed only for the merge and chain scripts. It runs on WSL2, Linux and macOS. I tested it on WSL2 with Ubuntu 24.04, and Linux and macOS are supported by design but untested. Native Windows is not supported.

bash install.sh previews every change and asks y/N per step. Your existing CLAUDE.md and AGENTS.md rules are kept active in both engines. Every file it replaces or creates goes into a private backup, and uninstall.sh restores them byte for byte.

Try the free part first

The free, MIT licensed two-engines-gate has the core check: a read-only review saved under the commit hash, a test pass record and a merge check that wants both. Run bash demo.sh to watch one loop with a stand-in reviewer.

The paid Two Engines Kit (currently v1.0.2) adds the shared rulebook, hooks, the installer with backups, the full review loop with merge-pr.sh and chain.sh, the memory module and the guide with every number above. The Two Engines Kit is built on information gathered since the first Codex and Claude CLIs.