AI AI Tools Guidebook
Indie Dev & Website Building

SEO Review of Your Site With Codex: Exact Prompts

Run a technical SEO review with Codex using copy-paste prompts for canonical, hreflang, title/meta, sitemap, and JSON-LD checks — plus shell commands that verify every finding.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

Codex reads your repo and spots SEO bugs you would otherwise find six months later in Search Console. The trick is asking it to check specific things, not “review my SEO.” Below are the exact prompts to send, plus the shell commands that verify what the agent reports — because agents hallucinate file counts, and a verified worklist beats a confident-sounding summary.

TL;DR

Build locally, point Codex at dist/ (not source), and ask one narrow prompt per SEO concern: canonical, hreflang, title/meta, sitemap, JSON-LD. Cross-check a sample of each finding with grep, xmllint, or jq. Spot-check 5 findings — if 5/5 are real, trust the rest as a worklist. Track one issue per category, not per file.

What Codex is, and why it fits this job

Codex is OpenAI’s terminal coding agent, powered by GPT-5.5 (as of June 2026). It runs locally, reads and runs code in the directory you point it at, and chains hundreds of tool calls without hand-holding — which is exactly what a recursive dist/ walk needs. It is included with any paid ChatGPT plan: Plus ($20/mo), Pro ($100 or $200/mo with higher five-hour usage windows), and Business ($30/seat). Since the April 2026 pricing change, Codex usage on these plans is metered against token consumption inside rolling five-hour windows rather than per-message, so a full SEO sweep of a few thousand HTML files is comfortably within a single Plus window.

The work splits cleanly. An agent scans build output in minutes and flags the systematic, mechanical mistakes — inconsistent canonicals, missing alt text, wrong sitemap entries — that a human reviewer skims past. What it cannot do is judge intent: whether your H1 actually matches the query a reader typed. So the workflow is: agent finds the mechanical issues, you make the judgment calls. Claude Code (running Claude Opus 4.7 / Sonnet 4.6) works identically here; the prompts below are tool-agnostic.

When to run this

  • Your site has more than 20 pages and you have never done a formal technical SEO audit.
  • Indexed pages drop in Search Console without an obvious cause.
  • You launched recently and want to catch issues before they compound.
  • You migrated stacks or restructured routes and want to verify nothing broke.

Before you start

  • A local dist/ build that matches production output (npm run build).
  • Codex (or Claude Code) with file-read access to the repo.
  • grep, xmllint (from libxml2), and jq installed for verification.

The five prompts

  1. Build locally and aim Codex at dist/, not source:
npm run build
ls dist/                       # confirm pages exist
du -sh dist/                   # sanity check size
  1. Canonical tag audit. Prompt:
[CONTEXT] Astro static site; build output is in dist/. Each page is index.html under a slug directory.
[TASK] Walk dist/ recursively. For every *.html, find <link rel="canonical">. Report:
  - any file MISSING the tag
  - any file with a canonical href that does NOT match its own URL path
  - any file with MULTIPLE canonical tags
Output as CSV: file,issue,detail
[CONSTRAINTS] Do not modify any files. Read only.

Verify the report with grep:

# count pages without canonical
grep -L 'rel="canonical"' $(find dist -name '*.html') | wc -l
# files whose canonical does not contain "yourdomain.com"
grep -ROIL '<link rel="canonical" href="https://yourdomain.com' dist | head
  1. hreflang audit. Prompt:
[TASK] For every dist/**/index.html that has hreflang tags, verify:
  - the page references its own URL via hreflang="<its-lang>"
  - the page references its translation via hreflang="<other-lang>"
  - the other-lang URL actually exists in dist/
Report mismatches as CSV: file,expected_other,actual_other_or_missing
  1. Title / meta description audit. Prompt:
[TASK] For every dist/**/index.html, extract <title> and <meta name="description">.
Report pages where:
  - title is missing or empty
  - description is missing or empty
  - title length < 25 or > 60 characters (Google truncates titles near 600px / ~60 chars)
  - description length < 110 or > 158 characters (Google shows ~920px / ~158 chars on desktop)
  - duplicate title or description appears on more than one page
Output: file,issue,title,desc_len

Those character thresholds track Google’s mid-2026 SERP rendering: titles get cut near 600 pixels (about 60 characters), and desktop descriptions render to roughly 920 pixels (about 158 characters), dropping to ~680 pixels (~120 characters) on mobile. Character counts are a proxy — wide characters truncate sooner — so treat near-boundary titles as a manual review, not a hard fail.

Sanity check:

# duplicate titles
grep -hr '<title>' dist | sort | uniq -c | awk '$1 > 1' | head
  1. Sitemap diff. Prompt:
[TASK] Parse dist/sitemap-index.xml (and any referenced sitemap files).
Compare URLs in the sitemap against the set of *.html files actually present in dist/.
Report:
  - URLs in sitemap with no corresponding file
  - HTML files NOT in any sitemap (potential indexing leak)

You can cross-check with:

xmllint --xpath '//*[local-name()="loc"]/text()' dist/sitemap*.xml \
  | sort > /tmp/sitemap-urls.txt
find dist -name 'index.html' | sed 's|dist|https://yourdomain.com|' | sed 's|/index.html|/|' \
  | sort > /tmp/file-urls.txt
diff /tmp/sitemap-urls.txt /tmp/file-urls.txt
  1. Structured-data validator. Prompt:
[TASK] Find every <script type="application/ld+json"> block in dist/**/*.html.
For each, parse the JSON. Validate against the fields Google requires for rich results:
  Article: @context, @type, headline, image, datePublished, author (with author.name)
  BreadcrumbList: @context, @type, itemListElement (array)
Report any parse errors or missing required fields.
Output: file, ld_type, problem

Verify a sample:

# extract first JSON-LD block from a page and pretty-print
sed -n '/<script type="application\/ld+json">/,/<\/script>/p' \
  dist/en/articles/some-slug/index.html \
  | sed '1d;$d' | jq .

The agent catches parse errors and missing fields at scale, but it cannot tell you whether Google will actually grant a rich result. Confirm the winners in a browser with two official tools: Google’s Rich Results Test (does this markup qualify for a Google rich result?) and the Schema Markup Validator (is the markup valid schema.org regardless of Google?). For Article, Google’s minimum is headline, image, datePublished, and author.name; dates must be ISO 8601. Once live, monitor aggregate status under Search Console’s Enhancements reports.

  1. Spot-check 5 findings. If 5/5 are real bugs, trust the rest as a worklist; if 2/5, narrow the prompt and rerun.

  2. Open one tracked issue per category, not per file — keeps the cleanup focused:

Issue: 23 articles missing canonical tag in dist/
- See attached CSV
- Fix in ArticleLayout.astro and rebuild
- Re-run audit prompt 2 to verify zero remaining

Implementation checklist

  • Build output (dist/) is what gets reviewed, not source.
  • Each prompt asks about one specific SEO concern, not “everything”.
  • Findings cross-checked with grep, xmllint, or jq before treating as truth.
  • Findings are tracked as issues, not fixed inline.
  • The same prompts are saved for re-running after each major change.

After-launch verification

  • Re-running the same prompts after fixes returns an empty (or much shorter) list.
  • Search Console URL Inspection on samples shows canonical, hreflang as expected.
  • Lighthouse SEO score = 100 on at least 3 sample articles.

Common pitfalls

  • Asking “is my SEO good?” — generic answer that misses your actual bugs. Always ask about a specific tag, file, or route.
  • Trusting the agent on search intent or keyword strategy. It does not see your Search Console data and will make plausible-but-wrong suggestions.
  • Running it on source code instead of built HTML. Many SEO issues only appear post-build (e.g., empty meta tags from undefined frontmatter).
  • Letting it auto-fix issues without a diff. Have it propose patches; review and apply manually.
  • Skipping the grep/xmllint verification step — agents do hallucinate, especially on file counts.

FAQ

  • Codex or Claude Code — does it matter?: For this job, no. Codex (GPT-5.5) and Claude Code (Opus 4.7 / Sonnet 4.6) both read the repo and chain the tool calls a recursive dist/ walk needs. The prompts above are tool-agnostic. For pure HTML inspection of a handful of pages, even ChatGPT with file uploads can do a one-shot review.
  • Will this fit inside my ChatGPT Plus limits?: Almost always. Since April 2026 Codex is metered against token usage in rolling five-hour windows, not per message. A full sweep of a few thousand HTML files is mostly cheap file reads, so a Plus ($20/mo) window absorbs it. Pro ($100/$200) only matters if you run several agents in parallel all day.
  • Can it replace tools like Screaming Frog?: No. Crawlers follow links and redirects across the live site systematically; an agent finds template-level bugs in your build output. They catch different classes of problem — use both.
  • What about Core Web Vitals?: Agents are weak at performance audits. Use PageSpeed Insights and real Lighthouse runs. Code review can flag obvious offenders (huge unoptimized images, render-blocking scripts) but cannot replace runtime measurement.
  • How often should I rerun this?: After any structural change (new layout, new route pattern, content schema update), and otherwise quarterly. Save the prompts so a rerun is one paste.
  • Can the agent generate the fix as well?: Yes, but ask for a diff, not direct file edits, so you can review before applying. The fix usually belongs in one layout component, not in 23 individual files.

Tags: #Indie dev #AI-assisted build #Codex #SEO #Technical SEO

Related Articles