codex-seo: a Codex skill suite that routes SEO audits into deterministic artifacts

The problem: SEO answers that vanish when the chat session ends

Most SEO work done through a chat interface produces prose. You get a list of recommendations, you paste them into a ticket, and the underlying evidence (the fetched HTML, the parsed schema graph, the Core Web Vitals numbers) is gone. codex-seo addresses that by separating routing from execution. The README describes it as a Codex-native port of AgriciDaniel/claude-seo, synchronized to upstream main at commit a9cf338, and adapted for Codex skills, Codex plugins, TOML agents, and shared cache artifacts. The audience is narrow and specific: engineers or technical marketers who already use the Codex CLI and want the audit trail to be a file rather than a transcript. It is not a hosted SEO platform and it does not crawl for you in the way a dedicated crawler does. It is a routing layer plus a set of runners that call external data providers.

How the routing layer works: SKILL.md, specialist workflows, and .seo-cache

The architecture diagram in the README shows a single entry point: skills/seo/SKILL.md acts as the main orchestrator. A user prompt arrives in natural language or as a /seo command, and the orchestrator dispatches to one of 26 specialist workflows. Those workflows can fan out to 24 TOML agent profiles, described as parallel analysis slices, and to scripts/ which the README calls deterministic runners. The runners write to output/ in Markdown, JSON, HTML and PDF. A .seo-cache directory sits between the orchestrator and the workflows and is described as shared evidence. That cache is the interesting design choice: it implies fetched pages and API responses are reused across workflows rather than re-requested per skill. Whether the cache is invalidated per run or persists across runs is not stated in the material available, and that matters for anyone auditing a site that changes during a long session. The 26 workflows cover technical SEO, on-page analysis, content quality, E-E-A-T, schema markup, image optimization, sitemap architecture, Core Web Vitals, GEO/AEO for AI search, backlinks, local SEO, maps intelligence, Google APIs, semantic clustering, SXO, drift monitoring, e-commerce SEO, hreflang and FLOW prompts.

Installing it: what install.sh writes and which variables override it

The one-line install is a curl pipe into bash, pinned to a tag rather than a branch: curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.5/install.sh | bash. Windows uses irm against install.ps1 with iex. The README also offers a review-before-install path: git clone the repository, cd into it, then run bash install.sh or powershell -ExecutionPolicy Bypass -File .\install.ps1. According to the README, the installer copies the skill suite into ~/.codex/skills/, installs TOML agents into ~/.codex/agents/, creates a Python virtualenv at ~/.codex/skills/seo/.venv/, installs core runtime dependencies, attempts optional capability groups, and verifies the runtime. Four environment variables override behaviour: CODEX_HOME for an alternate Codex home, CODEX_SEO_REPO for a fork URL or local path, CODEX_SEO_REF for branch, tag or commit, and CODEX_SEO_SKIP_PLAYWRIGHT_BROWSER=1 to skip the Chromium install used by visual and PDF workflows. CODEX_SEO_PLAYWRIGHT_WITH_DEPS=1 asks Playwright to install system dependencies. Codex must be restarted after installation. Prompts then work in natural language, for example asking for a full SEO check on a URL, or in command form such as /seo audit <url>, /seo technical <url>, /seo schema <url>, and /seo dataforseo serp followed by a query string.

The dependency surface is the real cost of ownership

codex-seo is not self-contained. The topic list and README name DataForSEO, Firecrawl, Gemini, Google APIs and Google Search Console as integrations, and the /seo dataforseo serp command routes a SERP query through a paid API. The README states that runtime credentials stay outside the repo under Codex/local config paths, which is the right default, but it also means every machine that runs the suite needs its own credential setup before most workflows produce anything. Python 3.10 or later is required per the pyproject badge. The optional capability groups the installer attempts are where the friction lives: if Playwright is skipped, the visual and PDF report paths are unavailable, and the premium report generation advertised in the description degrades to whatever the non-browser runners produce. There is no stated offline mode. If your environment blocks outbound calls to DataForSEO or Firecrawl, the workflows that depend on them will fail rather than fall back, and the README does not document a fallback path.

The licence metadata does not agree with itself

The repository metadata reports NOASSERTION for the licence. The README carries a shields.io badge reading License: MIT, and the Contents list links to a LICENSE file. One of those two signals is wrong, or the licence file contains text GitHub's classifier cannot map to a standard identifier. This is not a hypothetical concern for a suite that installs itself into your home directory and shells out to paid APIs. Read the LICENSE file in the repository before you build anything on top of it. Nothing here is legal advice, and the discrepancy may be trivial, but you cannot resolve it from the repository description alone.

Where it is the wrong tool, and what to use instead

codex-seo is the wrong choice when you need control over crawl behaviour. It does not present itself as a crawler with configurable politeness, crawl depth, robots.txt handling or JavaScript rendering budget. For that job, Screaming Frog SEO Spider is the direct alternative, and the difference in approach is fundamental: Screaming Frog is a desktop crawler that fetches and renders pages itself and stores results in a local database you can query and re-export, while codex-seo is an orchestration layer that delegates fetching to Firecrawl, data to DataForSEO, and generation to Gemini, then writes the assembled report to output/. If your audit must run inside a network boundary with no third-party API egress, Screaming Frog works and codex-seo largely does not. Conversely, if you want the audit reasoning to happen inside an agent session alongside your code, Screaming Frog gives you a CSV and codex-seo gives you a workflow the model can call. The two are not substitutes so much as different points in the pipeline, and picking one means giving up what the other does.

Maintenance, upgrades, and what the release cadence tells you

The project is a downstream port, not an original codebase. The README states it is synchronized to upstream claude-seo main at a specific commit, a9cf338. That means every upstream change creates a porting obligation, and the release history supports the reading that this is active work: three releases landed on 2026-04-28 within roughly eleven hours, v1.9.6-codex.3, .4 and .5, and the last push to the repository is dated 2026-07-20. Rapid patch releases in a single day usually indicate installer or packaging fixes rather than feature work. The installer defaults to the pinned tag v1.9.6-codex.5 rather than a branch, which is the safer default and means upgrades are deliberate rather than automatic. Budget for re-reading install.sh on each bump, because it writes into ~/.codex/skills/ and ~/.codex/agents/ and creates a virtualenv under your home directory. Uninstall instructions exist as a README section, but the material available does not describe what they remove. The README reports 52 tests passing and a full installed smoke suite passing as of the latest local validation; that is a claim from the project, not an independent measurement, and it does not tell you how the workflows behave against a live site with rate limits or partial failures.

The drift monitoring workflow is the one worth scrutinising

Among the 26 workflows, drift monitoring stands out because it implies state across runs. A drift check only means something if there is a baseline to compare against, and the only persistent store visible in the architecture is .seo-cache. If drift detection reads from that cache, then the cache is not merely a performance optimisation, it is the source of truth for change detection, and its retention policy becomes a correctness concern rather than a tuning knob. The README does not document cache retention, eviction or invalidation. Anyone relying on drift monitoring should verify that behaviour directly against the installed scripts/ directory before trusting a change report. The same caution applies to the Google Search Console integration: GSC data lags, and a drift alert built on a lagging data source will report movement that reflects Google's reporting window rather than a change you made.

Editorial conclusion

Adopt codex-seo if you already run Codex CLI, want SEO audit output written to output/ as Markdown, JSON, HTML or PDF, and are prepared to hold DataForSEO, Firecrawl and Gemini credentials. Do not adopt it if you need a crawl budget you control, a permissive licence you can verify from the repository metadata alone, or a tool that works without a paid third-party API. Before installing, read install.sh and confirm what it writes into ~/.codex/skills/ and ~/.codex/agents/, then check the LICENSE file directly, because the repository reports NOASSERTION while the README badge says MIT.

Official sources

1. AgriciDaniel/codex-seo on GitHub
2. Issues
3. Project website
4. README
5. Releases