DEV Community: Iliya Oblakov

My GEO for small business guide in Search Console: 215 impressions and an average position of 29.8

Iliya Oblakov — Thu, 12 Nov 2026 11:54:07 +0000

Google Search Console recorded 215 impressions, an average position of 29.8 and 0 clicks for the GEO for small business guide I published on 16 October 2026. That's the 28-day read from 12 November. These snapshots show search visibility for one guide. They don't establish how long GEO takes or whether AI engines recommend my business, and I haven't checked yet whether ChatGPT or any other AI engine names it.

GEO is the work of getting a business found and recommended by AI engines. I practise it on rayastats.com, which I run alone, with modest traffic.

Search Console numbers for the guide

I read Google Search Console for the guide three times in November. Each read covers 28 days, so the windows overlap.

6 November (7 October to 3 November): 93 impressions, 0 clicks, average position 41.6.
10 November (28 days to 8 November): 185 impressions, 0 clicks, average position 31.8.
12 November (last 28 days): 215 impressions, 0 clicks, average position 29.8.

The guide's average position was 29.8 in the latest read. These figures don't establish why it received no clicks.

The first window starts on 7 October, nine days before the guide existed. Part of the rise from 93 to 185 is the later window covering more days the page was live.

The query reports cover the whole site, with no breakdown by page. They recorded 41 and then 85 impressions for "geo for small business", and 21 and then 52 for "geo for small businesses". The 12 November read lists 97 and 66, but it doesn't record which query filter was applied. These records don't establish each query's share of the guide's impressions.

Across the whole site, the 28 days read on 10 November show 447 impressions and 6 clicks. The 28 days before that show 39 impressions and 0 clicks. The guide accounts for none of those clicks.

Two long queries recorded average position 8

In the 10 November read, the site recorded an average position of 8 for two long questions: "what should a small business look for in a geo platform?" (4 impressions) and "how to check if ai search bots can crawl and parse text on decision-stage pages?" (9 impressions). The short head term "geo for small business" recorded an average position of 34.3 in the same read.

Those two queries totalled 13 impressions, too few to establish a ranking pattern.

What I did on the site

16 October 2026: I published the GEO guide, about 2,200 words with a 10-step checklist.
16 October 2026: I fixed a crawler problem I found while checking how crawlers see the site. English blog posts were also reachable under Bulgarian URLs and marked as Bulgarian, so search engines saw duplicate pages in the wrong language. Each post now has one address, and the other language redirects to it. Two posts also had two H1 headings, so their body headings became H2.
19 October 2026: I published a second guide built on my own crawler data, Can AI engines read your website? I linked it from the GEO guide and added a Guides section to the site's llms.txt.

The GEO guide's HTML snapshot from 12 November contains one structured data graph, including the BlogPosting, BreadcrumbList, OnlineBusiness, Person and Service types. The business is described as an online business with no street address, because I work fully online.

I'm not claiming llms.txt or structured data moved any number in this post. The GEO guide itself says you don't need special files. I also can't tell you which of these changes, if any, moved impressions.

Crawlers were visiting before any of this

In the four weeks to 16 October 2026, my server logs showed 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. Googlebot made 26 visits, verified against Google's published IP ranges. The AI crawler counts go by user agent only, so they're indicative.

Those logs show crawlers fetching pages. They don't show what any engine says about the site.

What hasn't happened yet

Clicks. The guide has 0 clicks from Google in every read. I'm not claiming a lead or a sale from it.
An AI engine check of rayastats.com. I haven't tested whether ChatGPT or any other AI engine names my site. It's the next thing I'll run, and I'll publish it.
Enough data. This is one small site and a few weeks of numbers, and Search Console impressions aren't visitors.

The check I'll run on my own business

The method is the same 10 questions on 3 days in ChatGPT and Google AI Overviews. I tested it on one anonymous med spa in Dallas that isn't a client, from 23 to 25 October 2026. Nobody commissioned the sample. ChatGPT named the business in 3, 1 and 4 of 8 general answers on the three days. Google's AI Overview named it in 1 of 8 each day and gave the wrong Saturday hours all three days.

A mention counts a name on the answer's map as well, and the 23 October ChatGPT count of 3 includes one map-only mention. One of the 8 general prompts left out Dallas and produced answers about Illinois in all three ChatGPT runs and in Google's first two runs. I kept it in the 8.

A single day of ChatGPT would have given me 3, 1 or 4, depending on the day. There's a separate post on how to check if ChatGPT names your local business.

What I'm doing next

These are plans. None of them is done.

A new title for the guide, aimed at the exact searches in the query reports, and more links to it from related posts.
A set of shorter posts around it, each built on one real check: wrong business facts in AI answers, the 3-day run, and what 50 med spa websites tell AI engines.
The same 3-day question method on my own business. I'll publish the numbers.

For local businesses in the US and UK

The AI Visibility Audit shows whether ChatGPT and Google AI Overviews name and recommend your business, with screenshots, repeated tests and a ranked fix list. Every prompt runs 3 times in each engine, on 3 different days, with your city written into every prompt. The Full Audit takes 3 business days and the Audit + Fix Kit takes 5, counted from the day after your intake answers arrive. Business days exclude weekends and bank holidays in England and Wales. Nobody can guarantee a place in an AI answer, and the audit doesn't promise one.

See what the AI Visibility Audit covers.

Google AI Overview showed the wrong business hours for a Dallas med spa, 3 days out of 3

Iliya Oblakov — Thu, 12 Nov 2026 11:53:39 +0000

If Google's AI Overview shows the wrong hours for your business, ask it the same question on 3 different days and compare the answer with every place your hours are published. A listing that repeats the same disputed hours is worth checking, but the match doesn't show where the engine got them. I ran that test on a Dallas med spa. The Overview included a Saturday 11:00 AM to 4:00 PM window in all three runs, and a third-party directory listing showed the same window. The med spa's homepage listed Saturday as by appointment only. The first fix I recommended was to make the Saturday hours identical everywhere they appear, then ask that directory to correct its listing.

This is one narrow case of GEO for small businesses: an engine names you and gets a fact wrong.

What I tested

The sample audit covered one real med spa in Dallas, Texas. It isn't a client and nobody commissioned the audit, so it stays anonymous.

I asked the same 10 questions on Friday 23, Saturday 24 and Sunday 25 October 2026, typed the same way each day, in a new chat or search, with no follow-up questions. Eight were general questions a new client might ask. Two asked about the med spa by name: what it's known for, and its address, phone number and opening hours.

ChatGPT and Google AI Overviews ran in signed-out browser sessions and answered on all 3 days. Claude ran once, on 25 October, through a signed-in Claude Code account in command line mode with web search on, from a PC in Bulgaria. That setup may differ from the Claude app. Perplexity and Gemini couldn't be used signed out, so they have no results.

I checked the facts in the by-name answers against the med spa's own website. I didn't open the Google Business Profile itself.

What each engine got right by name

All three engines that returned answers named the med spa on every by-name question.

These scores cover the facts I checked against the business website, mostly using the 23 October check as the baseline. Details I couldn't verify were left out, so a passing answer wasn't necessarily verified in full.

ChatGPT: 6 of 6 answers matched the website on the facts checked.
Google AI Overviews: 3 of 6. "Known for" matched on 3 of 3 runs. For address, phone and hours, 0 of 3 answers fully matched the website, because Saturday differed.
Claude: 2 of 2 on its single run, counting the facts that could be checked.

The AI Overview's wrong hours were on Saturday

Google's AI Overview included a Saturday window of 11:00 AM to 4:00 PM in all three runs. The answer from the 24 October run also said "or by appointment only". The address, the phone number and the weekday hours matched the website. The homepage baseline listed Saturday as by appointment only.

The same 11:00 AM to 4:00 PM window appeared on a third-party directory listing. That match doesn't show where the Overview got it. On Friday, the Overview's source card for the hours answer was the Google business listing plus an inline link to the business website. Google's search snippet for the med spa's own contact page showed a third Saturday time. So the business's own web presence wasn't consistent either.

ChatGPT gave Saturday as by appointment only in all three runs. Friday's answer cited the contact page. My notes for the Saturday and Sunday runs record links to the business website. Claude's single answer said "by appointment only" and pointed out, without being asked, that two directory listings say Saturday 11 to 4.

What the site's own code said

Structured data is a block of code that hands search engines and AI tools the business name, address, phone and hours in a fixed format. On 22 October 2026 the med spa's homepage had this:

Type: LocalBusiness.
Business name: misspelled, with the words run together.
Address: street, city, state and ZIP present, suite number missing.
Phone: missing.
Opening hours: missing.
A second block, WebSite: name shortened to one word.

The 22 October robots.txt check found a sitemap declaration and no explicit block for the AI crawlers the sample looked at. One unrelated search crawler was blocked.

One place the engine could have read the right hours was empty. This sample didn't prove that the gap caused the wrong Overview answer. A code-only check of 50 Texas med spa homepages is in What 50 med spa websites tell AI engines about themselves.

Directory pages showed up as sources

In three of Claude's linked answers, the links went to directory or booking pages about the med spa instead of its own website. For "best med spas in Dallas", ChatGPT's sources on Friday were directory sites and Google.

The fix list from the report

Seven recommendations from the sample report, in the report's order. The last one is reworded as a check, because the team page already named both co-owners.

Owner: make the Saturday hours the same on the homepage, the contact page, the Google Business Profile and the directory listings. Then ask the directory showing 11:00 AM to 4:00 PM to correct it.
Developer: correct the business name in the LocalBusiness structured data so it matches the sign and the Google profile letter for letter.
Developer: add the phone number, the opening hours (matching fix 1) and the suite number to the LocalBusiness structured data.
Developer: change the WebSite structured data name from the one-word short form to the full business name.
Owner: check the listing on each directory ChatGPT used as a source for "best med spas in Dallas", and add or correct it.
Owner: check how Google's Overview describes the ownership. I couldn't find that description on the pages I checked. If it's right, say it on the team page. If it's wrong, check the cited pages and other public listings, and correct any inaccurate ownership description you find.
Content: check whether both co-owners' names and roles are on the site as text a crawler can read. ChatGPT described only one of them as a co-owner.

I didn't apply these recommendations or run an after-fix check, so I can't report whether the Overview changed.

How to check AI answers about your own business

Ask each engine, logged out, in a new chat or search: "What is the address, phone number and opening hours of [business] in [city]?" and "What is [business] in [city] known for?"
Do it on 3 different days. Write down every fact and the source the answer shows.
Compare what you wrote down with your website, your Google Business Profile and your directory listings. Mark every value that conflicts, next to the sources the answer cited.
Check that your structured data carries the same name, address, phone and hours. Google's Rich Results Test or the page's source shows the LocalBusiness block.

The post on how to check whether ChatGPT and Google AI Overviews name your local business has a weekly routine.

Limits

One med spa, one city, three days, with one Claude run and no Perplexity or Gemini results. The sample doesn't show why an engine picked a source. "Wrong" means the answer didn't match the website baseline, which mostly came from the 23 October check. Details I couldn't verify aren't in the scores. Google didn't consistently show Dallas as its location: two Saturday searches showed a town in Bulgaria, and another showed Illinois.

The AI Visibility Audit

If you run a local business in the US or UK, the AI Visibility Audit shows whether ChatGPT and Google AI Overviews name and recommend it, with screenshots, repeated tests and a ranked fix list. It runs every prompt 3 times in each engine, on 3 different days, with your city written into every prompt. The Full Audit includes a prioritized fix list split into owner, developer and content tasks. Nobody can guarantee a place in an AI answer, and the audit doesn't promise one. The Full Audit takes 3 business days and the Audit + Fix Kit takes 5, counted from the day after your intake answers arrive. Business days exclude weekends and bank holidays in England and Wales.

I rechecked 23 public MCP issues on GitHub. OAuth sign-in and docs mismatches came up most.

Iliya Oblakov — Wed, 11 Nov 2026 06:58:18 +0000

On 10 November 2026 I went through public GitHub issues on MCP servers that were already in that week's research notes, and rechecked each issue the same day through the public GitHub Issues API. The set is 23 issues, and two classes came up more than any other: OAuth sign-in that fails before the server is usable, and docs that don't match the live server.

At the recheck, about 16:00 Europe/Sofia, 21 issues were open and 2 had been closed as completed earlier that day. 5 of the 23 are feature requests, and I list them separately near the end. Some of the open issues were opened in October.

I didn't file these issues and I didn't reproduce them, so everything below is what the issue itself says. I don't name the projects. Each section gives the failure class, then what to check on your own connector.

1. OAuth sign-in fails before the server is usable

Five open issues describe a client that can't finish sign-in, or that signs in and then gets an expired-session or invalid-client error.

Dynamic client registration accepts a loopback redirect URI such as http://127.0.0.1:53682/, then the authorize endpoint answers invalid_redirect for that same URI. Repeating the flow with http://localhost:53682/ works, and registering with application_type: "native" doesn't change the result.
A hosted server can't be connected from the Claude.ai connector because OAuth fails at dynamic client registration. The quoted error begins "Couldn't register with" and then names the vendor's sign-in service.
A second server fails the same way when it's added as a remote connector in Claude Desktop with automatic registration. This issue was opened in October and was still open on 10 November.
VS Code's MCP client registers through POST /register and persists the client_id it's issued. After the server evicts or expires that id, /authorize fails with "Invalid client_id".
initialize succeeds, then every tools/call returns a session-expired message or a 401 for a dynamically registered client. The issue says a fresh authorization and a brand-new client registration still fail within two minutes of the token being issued, while the same account works at the same time through the Claude connector.

Check on your connector:

Register a client dynamically, then send the redirect URI that registration accepted to the authorize endpoint. Do it once with 127.0.0.1 and once with localhost.
Add the server as a connector in each client your users run, with automatic registration, and watch whether registration completes.
Remove a registered client_id on the server, start sign-in again from the client that still holds it, and read the error the client gets.
After initialize, call a tool with a token issued a few seconds earlier to a dynamically registered client.

2. Docs, skills or the listed schema don't match the live server

Five issues fall here. Two of them were closed as completed on 10 November, so I describe those two in the past tense.

Closed as completed:

A documented Claude Desktop setup put a remote server in claude_desktop_config.json with only url and headers. The issue says that file only accepts local stdio servers, where each entry needs a command, so Claude Desktop rejected the entry and the server never loaded. The docs also said 6 or 7 tools depending on the page, while the server registers 8 core tools plus 6 more on API-key connections. The issue was closed 25 minutes after it was opened. A comment on it says the production docs were updated and verified live the same day: the Claude Desktop pages now give an mcp-remote command entry, and the API reference says 8 core tools.
A config class had a fluent instructions() method, but filters was only a public property, so ->filters([]) threw an unknown-method error. The issue was closed as completed the same day.

Open on 10 November:

A hosted tools/list marks a parameter as required on two tools. The issue says calls without it succeed, sending it doesn't change the output, and the main branch has no such parameter on either tool.
A README's Claude Code install command uses npx -y @anthropic-ai/mcp-remote. The issue says that npm package doesn't exist and the registry returns 404.
Two skills call MCP actions that the live tool reference doesn't list. The reporter checked the public tool reference on 9 November 2026.

Check on your connector:

Run every documented install command, and paste every documented config block into the client it names, on a machine that has never had your server on it.
Count the tools tools/list returns, then compare that number with every page that states one.
Diff the hosted tools/list against the tool definitions on your main branch, required parameters included.
For each skill you ship, look up every action it calls in the live tool list.

3. Tool annotations a directory checklist flags

One issue, opened in October and still open on 10 November, says none of a server's 39 registered tools passes a title. It states that Anthropic's Connectors Directory requires a title plus readOnlyHint or destructiveHint on every tool. It also says two tools that overwrite an existing object at the same key are marked destructiveHint: false.

Check on your connector:

Confirm every tool has a title and carries readOnlyHint or destructiveHint.
Call each write tool against a target that already exists. If the call replaces what was there, the tool modifies data and destructiveHint: false is the wrong annotation.

4. Install, runtime and argument coercion

Three open issues fall here.

A fresh install exits on startup with ImportError: cannot import name 'eval_type_backport' from 'pydantic._internal._typing_extra'. The issue attributes it to a pin on mcp[cli]==1.6.0 with pydantic left unpinned, after pydantic 2.14.0 removed that private name.
Number(null) and Number("") are both 0, so an optional max-age parameter sent as null becomes 0, and 0 forces a live crawl.
A tool call ended with MCP call failed: TimeoutError: MCP call timed out after 300.0s (configured timeout: 300.0s) and no result. The issue records one attempt, so it says nothing about how often this happens or why.

Check on your connector:

Install into an empty environment, with no lockfile and no cached image, and start the server.
Send null and "" for every optional number, and compare the result with leaving the field out.
Make the upstream API hang, then look at what the client receives and how long it waits.

5. The connection reports connected and the agent has zero tools

One open issue reports a regression after a version upgrade: tools/list returns 403 and the agent sees zero tools, while the connection is still reported as connected.

Check on your connector: after every upgrade, call tools/list with the credentials an agent uses and count the tools that come back. The connected status in that report didn't show the failure.

6. A cache keyed on the raw caller URL, with no size bound

One issue, opened in October and still open on 10 November, says a docs client keys its cache on the caller's raw URL, has no size bound and no eviction, and removes an expired entry only when the same key is read again. It adds that the live docs site returns 200 for query-variant URLs, so each variant is cacheable.

Check on your connector: for every cache in the server, write down the key, the size bound and the moment an expired entry is removed. If the key is caller input, count how many distinct keys one caller can create.

7. The documented remote URL doesn't accept the connection

One issue, opened in October and still open on 10 November, says adding the documented remote MCP URL as a Claude.ai custom connector fails at the first step with "Couldn't reach this address". After "Continue anyway" the connector saves, but it stays in a "needs reconnect" state with no tools exposed.

Check on your connector: add the URL from your docs as a custom connector in the client the docs name, and confirm the tools appear.

8. Link-formatted values that don't open

One open issue says link-formatted values in an MCP view don't open in Claude on the web, and that the view should use ui/open-link.

Check on your connector: click every link your views render, in the web client.

The five feature requests

Five of the 23 issues ask for something new, and I don't count them as failures:

OAuth support in an MCP client toward MCP servers (RFC 9728 discovery and PKCE).
Per-user SQL identity through JWT passthrough on a shared HTTP deployment.
MCP management of public sharing.
Create-environment and delete-variables tools on a hosted MCP server.
Native Streamable HTTP and/or SSE transport, so a server can be hosted remotely instead of only as local stdio. This request was opened in October and was still open on 10 November.

MCP connector review

If you want an outside review before your connector goes to customers or the Claude directory, I do an MCP connector review: an independent review of your existing MCP connector against Anthropic's connector pre-submission checklist.

Every tool goes through the MCP Inspector, and through Claude as a custom connector where hosting allows it.
Every tool is tested with valid input, bad input, denied access and an upstream error.
The permission boundary is checked with two users.
You get a checklist report where each finding has severity, impact, reproduction steps and a proposed fix.
You get one retest after you fix the findings.

I don't claim the review would have caught every class in this article. Anthropic doesn't run, approve or certify it, and it can't guarantee a Community or Verified listing.

The scope is on the MCP connector review page.

If the server isn't built yet, the MCP build is an MCP server over your existing API: four to six read-only tools, one sign-in flow and deployment to your infrastructure. Following the checklist doesn't mean Anthropic approves or certifies the connector.

Read-only Codex starts your MCP servers too. Disable them before the review.

Iliya Oblakov — Wed, 11 Nov 2026 06:57:40 +0000

A codex exec -s read-only review can't write files, and the MCP servers in your ~/.codex/config.toml start for it anyway. A server that can change things outside the sandbox works against a read-only review, so the Codex notes in my review gate say to set enabled = false on that server while the review runs.

Hooks come along too. A Stop hook that asks Codex to continue after its review can replace the final message with an empty one, and an empty final message leaves the gate with no verdict to save.

I listed both in my setup lessons post. This post follows one review through the gate and puts each fix next to what the official Codex docs say.

One review, in order

My gate calls Codex like this:

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

Around that call, in order:

review.sh deletes any verdict already saved for the commit, so a failed rerun can't leave an old ACCEPT behind.
It sends review-prompt.md, the commits and the full diff from the base to HEAD to Codex on stdin.
Without REVIEW_MODEL, Codex takes the model and reasoning effort from ~/.codex/config.toml, and the MCP servers configured there start too.
The sandbox lets Codex read files and run read-only commands such as git diff. It can't write.
Codex writes the review. Hooks set up for Codex run under codex exec as well, a Stop hook included.
--output-last-message saves the final message to a file, and review.sh reads the verdict from that file only.
merge-check.sh refuses any commit that has no saved verdict.

The official non-interactive docs (checked 10 Nov 2026) cover the flags: codex exec runs in a read-only sandbox by default, --sandbox workspace-write allows edits, -o is the short form of --output-last-message, and codex exec - takes the prompt from stdin. The two leaks come in at steps 3 and 5.

MCP servers from config.toml start for the review

The official MCP page says Codex keeps MCP configuration in config.toml, by default ~/.codex/config.toml, and that a trusted project can scope its own servers in .codex/config.toml. Before a review, go through both files for servers that can change things outside the sandbox and switch each one off:

[mcp_servers.<name>]
enabled = false

The page describes enabled as optional: "Set false to disable a server without deleting it." The entry stays in the file, so switching the server back on after the review is a one-line change.

The official page documents the switch. It doesn't say, on its own, that a read-only codex exec starts MCP servers. That behaviour comes from the Codex notes in my gate, the same notes the setup lessons post draws on.

Three more settings from the same docs affect a review:

required = true makes startup fail "if this enabled server isn't ready". The non-interactive page adds that when such a server fails to initialize, codex exec exits with an error instead of continuing without it. My gate treats any reviewer exit other than 0 as REVIEW FAILED and saves no verdict, so a required server that won't start costs you the review.
--ignore-user-config is for "a run that doesn't load $CODEX_HOME/config.toml". My gate's call doesn't pass it, and the gate takes the model and reasoning effort from ~/.codex/config.toml unless REVIEW_MODEL is set. The docs describe the flag in terms of that one file, and project-scoped servers sit in the repo's .codex/config.toml, so check the repo under review as well.
enabled_tools and disabled_tools are tool allow and deny lists for a single server. The fix in my gate notes turns off the whole server.

To see which MCP tools a Codex run calls, try the review prompt once with codex exec --json outside the gate. Stdout becomes a JSON Lines stream of the events Codex emits, and the documented item types include MCP tool calls.

A Stop hook can empty the final message

Hooks set up for Codex 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.

My gate reads the verdict from the final message and never searches the log. The prompt Codex gets contains Verdict: ACCEPT as the example of the format, so a search of anything that repeats the prompt can find an ACCEPT the reviewer never gave. An empty final message leaves nothing to read.

On 23 October I ran the no-verdict cases in a scratch repo with my gate's scripts. The empty answer came from a small fake codex I wrote for the test, and review.sh printed:

NO VERDICT: codex wrote no final message

It exited 1 and saved no verdict. A Stop hook ends the review on the same line, with the diagnostic log kept and nothing saved. merge-check.sh then stops with "no review verdict for ; run review.sh", so the commit can't pass and the review you waited for says nothing.

The gate notes give two ways out:

Switch the hook off for reviews.
Add a line to review-prompt.md asking Codex to repeat its complete review if anything asks it to continue.

The no-verdict post covers the other ways a review ends without a verdict: a crash, a cut-off answer and two Verdict lines.

When Claude Code is the reviewer

BUILDER=codex swaps the roles, and my gate calls Claude Code like this:

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

--strict-mcp-config with no MCP configuration given means no MCP servers load. Read, Grep and Glob are the only tools, so Claude Code can't run commands, git included, and can't edit or write files. That's why review.sh puts the commits and the diff into the prompt. It also refuses to start when claude --help doesn't list --restricted.

The Claude Code review shuts MCP out with a flag in the call, while the Codex review starts whatever servers config.toml leaves enabled.

The writer and reviewer post walks through the swap.

If you ship an MCP connector, get it reviewed

The enabled = false switch is for MCP servers you run. If you ship an MCP connector, sort your own tools the same way, by whether they change data: readOnlyHint: true on every read-only tool, destructiveHint: true on every tool that modifies or deletes data, and read and write tools kept separate.

Those items are on Anthropic's connector pre-submission checklist. My MCP connector review is an independent review of an existing MCP connector against that checklist, before it goes to customers or the Claude directory. Every tool goes through the MCP Inspector, and through Claude as a custom connector where hosting allows it. You get:

A checklist report.
Tests of every tool with valid input, bad input, denied access and an upstream error.
A two-user permission boundary check.
Each finding with severity, impact, reproduction steps and a proposed fix.
One retest after you fix the findings.

Anthropic doesn't run, approve or certify this review, and the review can't guarantee a Community or Verified listing. If the server isn't built yet, the MCP build puts one over your existing API.

The Two Engines Kit is a set of files for working with Claude Code and Codex the way this post does, and I've been building it since the first Codex and Claude CLIs.

ChatGPT named one Dallas med spa in 3, 1 and 4 of 8 answers on 3 days

Iliya Oblakov — Tue, 10 Nov 2026 06:10:51 +0000

Google's AI Overview gave the wrong Saturday opening time for a Dallas med spa on three days in a row. On the same three days, ChatGPT named that med spa in 3, then 1, then 4 answers to the same 8 questions.

If you check your own business by asking once, you get one day's answer and nothing to compare it to.

The setup

This was a sample audit on a real Dallas med spa in October 2026. It isn't a client of mine, so it stays anonymous.

I asked ChatGPT and Google AI Overviews the same 10 questions on Friday 23, Saturday 24 and Sunday 25 October. Every run used the same wording in a new chat or a new search, logged out, with no follow-up questions.

Eight were general questions a new client would ask, such as the best med spas in Dallas, laser hair removal packages or microneedling. Two asked about the med spa by name.

I count the two groups separately. An engine almost always finds a business when you type its name, so mixing them would make the numbers look better than they are.

ChatGPT gave a different total each day

The laser hair removal packages question held steady. ChatGPT listed the med spa first on all three days, with a link to its site.

Three other questions moved:

Microneedling: third on Friday, missing on Saturday, third again on Sunday.
Natural looking Botox: on Friday the med spa showed up only as a pin on the answer's map and was left out of the written list. It was missing on Saturday. On Sunday it was listed first, with a Yelp page as the source instead of its own website.
Chemical peel for acne scars: named only on Sunday, in second place.

Friday's total of 3 counts that map pin. On the other four general questions, ChatGPT didn't name the med spa on any of the three days.

Google AI Overviews named it on 1 of 8 each day

Google's AI Overview named the med spa on 1 of the 8 general questions each day, and it was the microneedling question every time. The position moved from 4th on Friday to 2nd on Saturday and 3rd on Sunday. The Overview linked to the med spa's site each time.

On the Botox question, the med spa was first in Google's map pack on all three days. The AI Overview at the top of the same page never named it.

The wrong Saturday hours came back on every run

I asked for the med spa's address, phone number and opening hours. Google's AI Overview gave a fixed Saturday opening time on all three days. The med spa's own website says Saturday is by appointment only, and the time Google gave matches a third-party directory listing. ChatGPT got Saturday right on all three days, from the med spa's contact page.

One run can't tell you whether a wrong answer is a one-off or something the engine keeps repeating. Three runs with the same wrong hours point at a source. So the first fix in my sample report was to make the Saturday hours match on the website, the Google Business Profile and the directory listings, and to ask the directory to correct its entry.

A question without the city got answers for Illinois

One of my questions named two Dallas neighbourhoods and left out the city. ChatGPT answered it for towns with the same names in Illinois on all three days. Google did the same on Friday and Saturday, and placed it in Texas on Sunday.

I kept the wording unchanged so the three runs stayed comparable. Every question in a real audit now has the city written into it.

What this sample can't tell you

It covers one med spa in one city over three days. Perplexity and Gemini were blocked while logged out, so they have no results. The Claude chatbot was run on only one of the three days, so it has no totals here.

The connection traced to Bulgaria on Friday and to a US exit on Saturday and Sunday, and that can change what an engine shows. "Not named" means not named in these answers. The sample doesn't show why an engine picked one business over another.

Run the check on your own business

Write 8 general questions a new client would ask, with your city in each one, plus 2 questions about your business by name.
Ask each one in a new chat or a new search, logged out and with no follow-up, on 3 different days.
For each answer, log whether you were named, your position, whether it linked to your site, which other businesses were named and whether the facts about you were right.
Count the general and the by-name questions separately, and keep each day's total next to the others, for example 3 of 8, 1 of 8 and 4 of 8.
Fix the facts that come back wrong on every run first.

How to check whether ChatGPT and Google AI Overviews name your local business has the columns and the weekly routine in more detail.

Get the audit for your business

The AI Visibility Audit uses this method on your business. Your city is written into every question, and each question runs 3 times in each engine, on 3 different days. You see all 3 results side by side, with the fixes that come out of them.

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

How I run Claude Code and Codex as writer and reviewer, with a forced verdict line

Iliya Oblakov — Tue, 10 Nov 2026 06:10:25 +0000

Codex reviews each Claude Code commit in a read-only sandbox, and any review that doesn't end on Verdict: ACCEPT or Verdict: CHANGES REQUIRED counts as failed. So does a crash. My merge check also refuses an ACCEPT that came from the engine that wrote the code.

The writer answers every finding, each new commit gets a fresh review, and later the roles swap so each engine spends time on both sides of the diff.

This is the setup I use on my own projects, with the CLI flags taken from the official Claude Code and Codex docs. The reasons I use Claude Code and Codex together are in an earlier post.

1. Give each engine one job

Claude Code is the default writer. Writing is where context piles up: the plan, the files touched, the tests run. A review needs far less, only the diff and the project rules. A reviewer trained by a different company also has different blind spots, and that's why I use two engines instead of asking one to check itself.

Start the writer in its own git worktree, so its edits never touch the checkout you review from:

claude -w feature-auth

The -w flag starts Claude Code in an isolated worktree at <repo>/.claude/worktrees/<name>. Reviews always run on a commit, never on loose edits, so tell the writer to commit each finished change and stop.

2. Run Codex as a read-only reviewer

codex exec is the non-interactive mode of the Codex CLI, and its default sandbox is read-only. I pass the sandbox flag anyway, so nobody has to remember the default:

codex exec -s read-only -c model_reasoning_effort=high \
  --color never --output-last-message .ai/last-review.md \
  - < review-prompt.md

-s read-only lets Codex read files and run read-only commands such as git diff, but not write.
-c overrides any config key for one run. Here it sets the documented model_reasoning_effort key to high. The review script in the Two Engines Kit defaults to xhigh, one level above.
The output-last-message flag saves only the final message to .ai/last-review.md, and the verdict is read from that file.
The - on the last line makes Codex read the prompt from standard input.

If an MCP server in ~/.codex/config.toml can change things outside the sandbox, set enabled = false on its table for the review run.

3. Force a verdict line

My review prompt asks Codex to end on one of two exact lines:

Verdict: ACCEPT
Verdict: CHANGES REQUIRED

It sets four more rules:

Every finding carries a severity (blocker, should-fix or nit), a file and line, and a concrete failure scenario.
Blockers and should-fixes need a concrete, reproducible failure. Style preferences stay at nit level.
Codex lists every finding in this one pass, so the next round doesn't surface old problems.
The review stays under 600 words.

The review script reads the verdict only from that saved final message, never from the log. It also checks that Codex exited with code 0 and that the checkout is unchanged afterwards. A crash or a missing verdict line counts as a failed review. The result is saved under the commit hash it reviewed, so a later commit can't borrow an old ACCEPT.

4. Make the writer answer every finding

The reviewer has no say in what gets merged beyond its findings. The writer and the person running the loop decide.

For each finding, the writer either fixes it in a new commit or disputes it with evidence: a test that passes, a file and line that shows the case is handled, or a command whose output contradicts the claim. Don't let it accept every finding by default. A reviewer can be wrong, and a fix for a problem that doesn't exist adds risk of its own.

I follow three round rules from the kit workflow:

Round 1 lists everything.
Round 2 confirms that the fixes landed.
From round 3 on, only blockers and security findings hold the merge. Nits go into a follow-ups file to handle later.

I wrote more about briefs and disagreement in how I brief Codex to review Claude Code commits.

5. Swap the roles

In my gate, setting BUILDER=codex flips the roles, so Claude Code reviews and Codex writes.

As the writer, Codex needs a sandbox that allows edits inside the workspace:

codex exec --sandbox workspace-write \
  - < task.md

As the reviewer, Claude Code runs in print mode with a short list of read-only tools. The gate makes this call:

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

With only Read, Grep and Glob available, Claude Code can't run commands, git included, and can't edit or write files. That's why the gate puts the commits and the full diff into the prompt itself. The strict MCP config flag with no MCP config loads no MCP servers, and permission mode dontAsk denies anything that would otherwise ask for approval.

The merge check I opened with refuses an ACCEPT from whichever engine wrote the code.

6. Keep one rulebook for both engines

Claude Code reads CLAUDE.md and Codex reads AGENTS.md. Put the same short section in both:

Commit each change and stop.
Never merge.
Stay read-only when reviewing.
Leave the review records folder alone.

Codex limits how many bytes of AGENTS.md it loads (the project_doc_max_bytes setting), so keep that section short and put long reference material elsewhere.

What the loop doesn't replace

Your tests have to run on the exact commit that got the ACCEPT. My gate checks for both a test pass and an ACCEPT on that commit before it allows a merge. A reviewer on high reasoning effort catches a lot, but it only reads the diff you gave it.

Running it on your own repository

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

To start from the files I use and wire it up yourself, get the Two Engines Kit. It packages the review script, the gate, the merge check, the review prompt and the workflow rules from this post, for WSL2, Linux and macOS. It's the setup I run on my own projects, built on information gathered since the first Codex and Claude CLIs.

Claude Code Review never blocks a merge: GitHub App vs Action vs /code-review vs a local gate

Iliya Oblakov — Tue, 10 Nov 2026 06:06:49 +0000

Anthropic's managed Code Review never approves or blocks a pull request. Its check run concludes as neutral or skipped, never as a failure, and the docs say you can merge without responding to a finding unless your repository's own rules require it.

So before you pick how Claude Code reviews your code, decide what the review should be able to stop. You have four paths: managed Code Review through the Claude GitHub App, the Claude Code GitHub Action, the /code-review command, and a local gate that runs your tests and saves a second engine's verdict under the commit before anything merges.

Everything below about the first three comes from Anthropic's docs as of 9 Nov 2026. The fourth is my local gate, a version of how I make Claude Code and Codex check each other on my own projects.

The four paths side by side

	Managed Code Review	GitHub Action	`/code-review`	Local gate
Started by	Pull request activity or an `@claude review` comment	`@claude` mentions, or a prompt on the GitHub events you configure	You, on your branch	You, after each commit
Runs on	Anthropic infrastructure	Your own CI runners	Your Claude Code session	Your machine
Who can use it	Team and Enterprise, once an Owner turns it on	Anyone with a Claude API key or cloud provider credentials	Anyone, on any plan	Anyone with bash 4 or newer and git, plus the Claude Code and Codex CLIs for real reviews
Changes code	Read-only, and it doesn't push commits	Can implement changes and push commits	With `--fix`, through your permission mode	The builder commits, and the reviewer runs read-only

Managed Code Review leaves the merge to your team

In managed Code Review, several agents read each change, a verification step checks what they find, and the findings arrive as inline comments ranked by severity, with a summary and a check run named Claude Code Review. By default it looks for bugs that would break production and leaves formatting preferences and missing test coverage alone. It reads the diff and the surrounding code "without building or running your code", and it follows REVIEW.md from the base or default branch, never from the pull request's own changes.

You set how thorough it is with the review level (Quick, Standard or Deep), and in Anthropic's words "a more thorough review costs more". The costs page has the details.

A finished review doesn't fail a required check. To make a finding hold a merge, the docs describe reading the check-run details in your own CI and gating the merge there.

`/code-review` runs in your own session

/code-review finds bugs in your branch's changes from inside Claude Code, and it counts toward your plan's usage or API billing the same way the rest of the session does. With no target it reviews your branch's commits ahead of its upstream plus your uncommitted changes. You can also point it at a pull request or a path, and /review is an alias.

It follows your CLAUDE.md, including in a non-interactive -p run, and doesn't read REVIEW.md. Without --fix its instructions ask for a report only. With --fix they also ask it to apply the findings to your working tree, through your permission mode.

To review a pull request without managed Code Review or a workflow file, point /code-review at it and add --comment. The findings land on the pull request as inline comments.

The GitHub Action can push commits

The Claude Code GitHub Action runs Claude Code in your GitHub Actions workflows. Mention @claude in a pull request or issue comment and it can analyze code, implement changes and push commits. Managed Code Review never pushes, and the Action's own docs send you to Code Review for automatic reviews without a workflow file.

Setup is /install-github-app, or a manual install of the Claude GitHub App, a secret and a workflow file, and you need admin access to the repository. Its review workflow posts an inline comment on the pull request for each issue, or one summary comment when it finds none.

If you run the Action in interactive mode with its default @claude trigger phrase next to managed Code Review, an @claude review comment starts both. Set the Action's trigger_phrase input to a different phrase to keep them apart.

The local gate ties tests and a verdict to one commit

The local gate saves a test pass and a second engine's verdict under one commit hash, and refuses the merge without both. In the loop, Claude Code writes the code, commits each change on a branch and stops, and Codex reviews that commit read-only. Three scripts do the checking:

gate.sh runs your test command on a clean checkout and writes .ai/tests/<sha>.pass only when the command passed, left the checkout unchanged and didn't report a run of zero tests.
review.sh sends the commits and the diff to the engine that didn't write them and saves the verdict as .ai/reviews/<sha12>.md, with a Head: line holding the full hash.
merge-check.sh refuses unless the checkout is clean and HEAD has a pass record and an ACCEPT from a reviewer that isn't the builder. It never merges.

Codex reviews through codex exec -s read-only, so it can read files and can't write them. BUILDER=codex swaps the roles, and Claude Code then reviews with Read, Grep and Glob as its only tools.

These lines are from one run of the repo's demo, where a stand-in reviewer gives canned answers and no model is called:

merge-check: REFUSED: no test pass record for 2cef9bbe04c3; run gate.sh
gate: PASS on 2cef9bbe04c3, record .ai/tests/2cef9bbe04c3dd4727d2455e07c0ec420ecec7af.pass
merge-check: REFUSED: no review verdict for 2cef9bbe04c3; run review.sh
Verdict: CHANGES REQUIRED
- blocker, sum.sh:3: the loop starts at the second argument, so 'bash sum.sh 3 4' prints 4, not 7. test.sh only checks 'sum 0 4', where the bug cannot show.
merge-check: REFUSED: the verdict for 2cef9bbe04c3 is not a single ACCEPT
merge-check: REFUSED: no test pass record for 525000aeac20; run gate.sh
merge-check: OK: 525000aeac20 has a test pass and an ACCEPT from codex (builder claude)

The tests passed on a commit with a bug in it. The review asked for changes, and the fix commit started with no evidence, so it needed its own test pass and its own ACCEPT.

All three scripts also refuse a dirty checkout, because a test can pass on a file that isn't in the commit, and a reviewer can open a file that differs from the commit it judges:

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

Why the verdict is saved under the commit hash and why the gate refuses a dirty working tree go through each check.

What the gate doesn't do

It doesn't make the code correct. A review can miss things, and tests only check what they test.
It guards against merging the wrong commit and isn't a security boundary: anything with write access to the repository can write files under .ai/.
It doesn't push, merge or talk to GitHub.

Should Claude Code and Codex review each other?

Managed Code Review chooses the Claude models it runs on, so a change Claude Code wrote gets reviewed by models from the same company. For my gate I picked a reviewer from a different company because it has different blind spots, and on one pull request the first Codex review came back with 2 blockers and 8 should-fix findings. merge-check.sh refuses a verdict whose reviewer is the same engine as the builder, so no engine approves its own commit. The prompt I send Codex is in how to make Codex review Claude Code's commits.

Which path fits

You're on Team or Enterprise and want a review on every pull request without maintaining a workflow: managed Code Review, with the merge decision left to your team.
You want a review of your branch before you push, on any plan: /code-review.
You want Claude Code to answer @claude comments, implement changes and push commits from your CI: the GitHub Action.
You want the merge refused until the commit has its own test pass and an ACCEPT from the other engine: the local gate.

The local gate never talks to GitHub, so you can run it before the push and keep managed Code Review on the pull request.

Set up a local gate

If you want the merge itself gated, the Two Engines Kit is the self-install path and the workflow I use on my own projects. Its merge-pr.sh refuses to call GitHub without a local pass record for the exact commit and tree, then pushes, opens the pull request, merges only if the head hasn't moved, and checks that the merged tree matches the tested one. With the review switch on (REQUIRE_REVIEW=1) it also refuses a commit without a saved ACCEPT. I added that switch after a night in October when I found four test-only commits that had never been reviewed, one of them already merged. The kit is built on information gathered since the first Codex and Claude CLIs.

If you'd rather have the loop configured for you, that's the Codex review setup. I set up Codex to review Claude Code's commits in up to three of your repositories, written from scratch for each one, with none of the kit's files. Your tests run before every merge, and with review enforcement on, a commit Codex rejects doesn't merge. The first review runs on one of your real branches, with a recorded walkthrough of the findings.

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.

DEV Community: Iliya Oblakov

My GEO for small business guide in Search Console: 215 impressions and an average position of 29.8

Search Console numbers for the guide

Two long queries recorded average position 8

What I did on the site

Crawlers were visiting before any of this

What hasn't happened yet

The check I'll run on my own business

What I'm doing next

For local businesses in the US and UK

Google AI Overview showed the wrong business hours for a Dallas med spa, 3 days out of 3

What I tested

What each engine got right by name

The AI Overview's wrong hours were on Saturday

What the site's own code said

Directory pages showed up as sources

The fix list from the report

How to check AI answers about your own business

Limits

The AI Visibility Audit

I rechecked 23 public MCP issues on GitHub. OAuth sign-in and docs mismatches came up most.

1. OAuth sign-in fails before the server is usable

2. Docs, skills or the listed schema don't match the live server

3. Tool annotations a directory checklist flags

4. Install, runtime and argument coercion

5. The connection reports connected and the agent has zero tools

6. A cache keyed on the raw caller URL, with no size bound

7. The documented remote URL doesn't accept the connection

8. Link-formatted values that don't open

The five feature requests

MCP connector review

Read-only Codex starts your MCP servers too. Disable them before the review.

One review, in order

MCP servers from config.toml start for the review

A Stop hook can empty the final message

When Claude Code is the reviewer

If you ship an MCP connector, get it reviewed

ChatGPT named one Dallas med spa in 3, 1 and 4 of 8 answers on 3 days

The setup

ChatGPT gave a different total each day

Google AI Overviews named it on 1 of 8 each day

The wrong Saturday hours came back on every run

A question without the city got answers for Illinois

What this sample can't tell you

Run the check on your own business

Get the audit for your business

How I run Claude Code and Codex as writer and reviewer, with a forced verdict line

1. Give each engine one job

2. Run Codex as a read-only reviewer

3. Force a verdict line

4. Make the writer answer every finding

5. Swap the roles

6. Keep one rulebook for both engines

What the loop doesn't replace

Running it on your own repository

Claude Code Review never blocks a merge: GitHub App vs Action vs /code-review vs a local gate

The four paths side by side

Managed Code Review leaves the merge to your team

/code-review runs in your own session

The GitHub Action can push commits

The local gate ties tests and a verdict to one commit

What the gate doesn't do

Should Claude Code and Codex review each other?

Which path fits

Set up a local gate

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

Sort every finding into one of five classes

When the review itself breaks

A blocker needs a failure you can reproduce

Brief violations and reviewer preferences

Later rounds get a narrower packet

Pick a hard stop before round one

What the official Codex plugin already covers

Disputed requirements and scope go to a person

Run these rules on your own repository

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

How Claude Code and Codex build the chain

Three files that hide an AGENTS.md

Where root rules and package rules go

Keep the Codex chain under 32 KiB

`/code-review` runs in your own session