TL;DR
Point the Codex CLI at both your sitemap source (src/pages/sitemap-*.ts, next-sitemap.config.js, or a CMS config) and your built dist/sitemap-index.xml, then run one focused audit prompt. Codex checks for drafts that leaked in, broken trailing-slash consistency, stale lastmod dates, and missing hreflang pairs — citing the exact source file and line for each finding. Fix in source, rebuild, re-run, then resubmit to Search Console. A first audit on a year-old site usually surfaces 10-30 anomalies. This guide gives you the exact prompt and the protocol limits Codex should enforce.
Why a sitemap drifts (and why a human misses it)
After any meaningful site change — a URL restructure, a language addition, a content migration — your sitemap quietly desyncs from reality. Draft pages sneak in, lastmod dates stop reflecting actual edits, trailing-slash conventions split between sections, and Search Console raises “Submitted URL marked noindex” or “Submitted URL not found (404)” a week later, after Google has already wasted crawl budget.
The reason this slips past manual review: the sitemap is generated, so nobody reads it. You read the source that produces it and assume the output is correct. Codex closes that gap by reading the build artifact and the source together, then telling you where they disagree.
Who this is for
Owners of any generated sitemap.xml: Astro, Next.js, Hugo, WordPress with a sitemap plugin, or a custom generator. It is most valuable on bilingual or multi-language sites, where hreflang annotations and language-split sitemaps multiply the failure modes. (On this site, every English article pairs with a Chinese twin via a shared translationKey, so a missing pair is a real ranking bug, not a cosmetic one.)
What Codex actually is here
Codex is OpenAI’s terminal coding agent. As of June 2026 it runs GPT-5.5 by default (switchable with /model to GPT-5.4 or GPT-5.3-Codex), can read and run code in the selected directory, and has built-in web search. Two features make it a good sitemap auditor specifically:
/reviewruns a separate review agent over your working tree — useful once Codex proposes source fixes.codex execruns a prompt non-interactively, so the same audit can live in CI.
Codex is not a crawler. It reasons over your files; it does not fetch your live URLs. That is a feature here — you want it checking generation logic, not your server’s HTTP responses.
The protocol limits Codex should enforce
These numbers come from the sitemaps.org protocol and Google’s sitemap docs, and they are stable as of June 2026. Bake them into the prompt so Codex flags violations instead of guessing:
| Rule | Limit / requirement | What Codex should flag |
|---|---|---|
| URLs per sitemap file | 50,000 max | A single file over the cap that should be split |
| Uncompressed file size | 50 MB (52,428,800 bytes) max | A file approaching the byte cap |
| Sitemaps per index file | 50,000 max | An index that needs nesting |
lastmod format | W3C datetime (YYYY-MM-DD or full ISO 8601) | Malformed or invented dates |
lastmod accuracy | Only on real main-content changes | Every URL sharing one date, or “today” everywhere |
hreflang cluster | Canonical must be inside its own alternate cluster | Translation pairs where one side is missing |
| Trailing slash | One convention site-wide | Mixed /page and /page/ |
Two of these deserve emphasis. Google’s John Mueller has confirmed that alternate-language URLs declared via hreflang do not count separately toward the 50,000-URL limit. And Google has stated that if lastmod is set to today for every page every day, it learns the field is meaningless and stops trusting it — bumping a footer copyright year does not count as a content change.
Step by step
- Open Codex in your repo root. Run a fresh build (
npm run buildhere) sodist/sitemap-index.xmlreflects current source. Codex must read the output, not just the source. - Send the audit prompt below. Note how it names exact files, the protocol limits, and a hard rule that every finding cites a source location:
Read src/pages/sitemap-*.ts and dist/sitemap-index.xml (after build).
Verify and report findings:
- Every category page is included for every language.
- Every article URL ends with a trailing slash (project convention).
- No draft URLs appear (drafts have frontmatter draft: true).
- lastmod uses YYYY-MM-DD and is NOT identical across all URLs.
- hreflang pairs exist between en/zh entries that share a translationKey.
- No file exceeds 50,000 URLs or 50 MB uncompressed.
- Sample 10 random URLs; confirm a matching source file exists for each.
For each finding, cite the source file and line, never a dist/ path.
Suggest the source change, not a dist edit.- Codex returns an anomaly list. Read every finding; some
hreflangheuristics produce false positives when a page is intentionally single-language. - Fix in source — the generation logic, frontmatter, or your content-audit script — never in
dist/. Edits todist/are overwritten on the next build. - Re-run the build, then re-run the same prompt. Findings should shrink to zero or a documented set of intentional exceptions.
- Commit the source fixes with a clear message, e.g.
fix(sitemap): drop drafts, normalize trailing slashes. - Resubmit the sitemap in Google Search Console. Google does not recrawl on your schedule.
Trial run before the full sweep
Don’t trust a 30-item report you haven’t sanity-checked. First, scope the prompt to two URLs you know cold — your homepage and one well-understood section — and confirm Codex reads your source structure correctly. Then run the full prompt, count the findings, fix the top three highest-impact items (drafts and 404s before cosmetic date drift), and re-run. Watching the count drop tells you the fixes were real; a flat count means Codex was reading stale dist/ from before your rebuild.
Verifying Codex got it right
- Did every finding cite a source file, not just a
distURL? If not, Codex did not understand the build pipeline — re-prompt with the source path spelled out. - Are the suggested fixes idempotent? Applying them to an already-correct file should change nothing. If a fix would break a correct file, refine it.
- Open 5 random sitemap URLs in a browser. A 404, a redirect, or a wrong-language page is a red flag Codex’s static read can miss.
- After the next crawl, check the hreflang report in Search Console. Codex catches structural issues; Search Console confirms search-engine behavior.
Make it a recurring check
Save the prompt as a snippet with named placeholders for project paths, and run it quarterly, after any URL change, and after any content cleanup. Then promote the cheap parts into CI with codex exec, which runs the prompt headless and can fail the build on a regression:
codex exec "Read dist/sitemap-index.xml. Fail if any URL lacks a trailing slash, any draft URL appears, or lastmod is identical across all entries. Print a one-line PASS or the failing URLs."A sitemap-conventions.md documenting your trailing-slash rule, draft policy, and hreflang setup also helps — Codex reads it and stops re-flagging intentional choices. Re-test after major Astro / Next.js / CMS upgrades, since sitemap generation often shifts between versions.
Common mistakes
- Editing
dist/sitemap.xmldirectly. The next build overwrites your fix. Always change source. - Not declaring the trailing-slash convention. Codex reports mixed conventions but can’t tell which side is canonical until you say so.
- Shipping draft or
noindexpages. Search engines crawl them, then complain when they 404 or carrynoindex. - Identical
lastmodon every URL. Google stops trusting the field. See sitemap lastmod always today for the exact fix. - Missing
hreflangpairs for translated content. Search Console flags these late; Codex catches them at build time. - Forgetting to resubmit after a fix. If pages still don’t appear, see sitemap submitted but not indexed.
FAQ
- What if my site has tens of thousands of URLs?: Sample. Ask Codex to verify the rules against a random 100 URLs and report patterns rather than every line. If a single file is near the 50,000-URL or 50 MB cap, split it into a sitemap index — Codex can scaffold that split in source.
- Can Codex actually fix the sitemap, not just report?: Yes. Let it edit the source generator and run
/reviewover the diff, then open a PR you review like any other. - Does Codex check robots.txt and meta noindex too?: Those are adjacent concerns. Keep them in a separate prompt; a
noindexpage that’s correctly excluded from the sitemap is fine, and mixing the audits muddies the findings. See robots meta vs sitemap conflict. - My sitemap comes from a CMS plugin — can Codex still help?: Yes. It reviews the generated output and the plugin config. Source fixes go in the config, never in the generated XML.
- Which Codex model should I use?: GPT-5.5 (the June 2026 default) is fine for this. The task is reasoning over text files, not heavy code generation, so a lower reasoning level keeps it fast.
Related
Tags: #Tutorial #SEO #AI coding #Codex #Sitemap