Codex SEO: A Codex-First SEO Skill Suite With 26 Workflows and Deterministic Runners

What Codex SEO Actually Replaces

The project describes itself as a Codex-native port of AgriciDaniel/claude-seo, synchronized to upstream main at a9cf338 and adapted for Codex skills, Codex plugins, TOML agents, shared cache artifacts, and repeatable local/API execution. That sentence is the whole pitch. If you have been running SEO prompts inside a chat window and copy-pasting the output into a document, this suite is aimed at you. The README states that a /seo command is not required: you can ask naturally, and an orchestrator skill decides which specialist workflow to run.

The scope is deliberately broad. The README lists 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, FLOW prompts, DataForSEO, Firecrawl, and Gemini/nanobanana image workflows. Twenty-six workflows and 24 TOML agent profiles back that list.

Who it is for: engineers and technical marketers who already have Codex CLI installed and are comfortable with a terminal, environment variables and a Python virtualenv. Who it is not for: anyone who wants a dashboard. There is no hosted UI described in the README, and the installer writes into ~/.codex/skills/ and ~/.codex/agents/ rather than standing up a service.

How the Orchestrator Routes a Request to 26 Workflows

The README includes a flowchart that lays out the data flow plainly. A user prompt, either natural language or a /seo command, enters skills/seo/SKILL.md, described as the main orchestrator. From there the request branches three ways: to a .seo-cache directory holding shared evidence, to the 26 specialist SEO workflows, and onward to 24 TOML agents that the README calls parallel analysis slices. The specialist workflows also call into scripts/, which the README labels deterministic runners. Those runners write to output/ in Markdown, JSON, HTML and PDF.

The cache is the part worth noticing. It sits between the orchestrator and the skills, and the flowchart shows skills reading back from it. That implies repeated prompts against the same site reuse fetched evidence instead of refetching, which matters when your evidence source is a paid API. The README does not document cache invalidation or TTL, so treat the cache as an implementation detail you will have to inspect yourself.

The second design choice is the split between agents and runners. Agents are TOML profiles, which suggests declarative configuration rather than code. Runners are Python scripts under scripts/. The README frames the point of runners as writing repeatable artifacts instead of relying on invisible chat-only output. That is the strongest argument in the repository: an SEO audit you can diff against last month's audit is more useful than one you have to re-read from scrollback.

Installing Codex SEO and Running a First Audit

The README gives a one-line installer pinned to the release tag v1.9.6-codex.5. On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.5/install.sh | bash

On Windows the README uses PowerShell:

irm https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.5/install.ps1 | iex

If you would rather read the installer before running it, the README offers the clone path instead:

git clone https://github.com/AgriciDaniel/codex-seo.git
cd codex-seo
bash install.sh

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. Python 3.10 or newer is required per pyproject.toml.

The installer accepts overrides, which is how you point it at a fork or a local checkout:

CODEX_HOME=~/.codex \
CODEX_SEO_REPO=https://github.com/AgriciDaniel/codex-seo \
CODEX_SEO_REF=v1.9.6-codex.5 \
bash install.sh

Two more variables are documented for the visual and PDF path: CODEX_SEO_SKIP_PLAYWRIGHT_BROWSER=1 skips the Chromium install, and CODEX_SEO_PLAYWRIGHT_WITH_DEPS=1 asks Playwright to install system dependencies where supported. If you only need text output, the first one saves a large download.

After installation the README says to restart Codex. Then you can prompt in plain language, for example: Do a full SEO check on https://example.com following best practices. Command-style prompts work too, including /seo audit https://example.com, /seo technical https://example.com, /seo schema https://example.com, and /seo dataforseo serp "best seo tools". What you should see, per the architecture description, is artifacts appearing under output/ rather than only a chat reply.

The Dependency Surface Is the Real Cost of Admission

requirements.txt is a thin file that pulls in five groups: requirements-core.txt, requirements-visual.txt, requirements-report.txt, requirements-google.txt and requirements-ocr.txt. The comment at the top explains the strategy: the installer bootstraps core requirements first, then installs optional capability groups best-effort so wheel lag does not block core workflows.

That is a reasonable engineering decision and an awkward user experience. Best-effort installation means a workflow can appear available while its backing group failed to resolve. The README does not say which workflows degrade when requirements-visual.txt or requirements-ocr.txt fails, and it does not document a command to report which groups succeeded. The installer verifies the runtime, per the README, but the granularity of that verification is not described.

Playwright is the heaviest item. It is needed for visual and PDF workflows, and the README's own skip variable exists because the Chromium download is large enough that people want to avoid it. If you skip it, expect the visual and PDF report paths to be unavailable.

There is also a credentials dimension. The README states that runtime credentials stay outside the repo under Codex/local config paths, and the suite integrates with DataForSEO, Gemini, Google APIs and Firecrawl. Those are external services with their own keys, quotas and billing. The README does not document what happens when a key is missing or a quota is exhausted mid-run.

Where Codex SEO Is the Wrong Tool

The licence situation deserves a direct statement. The repository's LICENSE entry is classified as NOASSERTION by the hosting platform, while pyproject.toml declares license = "MIT" and the README badge links to a LICENSE file labelled MIT. Those signals disagree. Before you ship this inside a commercial pipeline, read the LICENSE file itself and get your own answer. This is not legal advice, and the discrepancy is exactly the kind of thing a legal reviewer will ask about.

The second limitation is coupling. This is a Codex-first suite. The README's install target is ~/.codex/skills/, the agents are Codex TOML profiles, and the quick start tells you to restart Codex. If your team standardizes on a different agent runtime, the porting work is yours; the README does not describe a runtime-agnostic mode.

Third, this is a beta. pyproject.toml carries the classifier Development Status :: 4 - Beta. The three most recent releases, v1.9.6-codex.3, v1.9.6-codex.4 and v1.9.6-codex.5, were all published on 2026-04-28, which is three builds in a single day. That pattern is normal for a release-day fix cycle, but it also means the version you pin today may be superseded quickly. The README does not document rollback, so an upgrade that breaks a runner leaves you reverting by hand.

Finally, the maintenance signal is mixed. The repository is not archived, but the last push was on 2026-07-20. That is roughly two months before the date of this article. The README does not publish a support policy or a release cadence, so plan on pinning CODEX_SEO_REF rather than tracking main.

Codex SEO Versus the claude-seo Suite It Was Ported From

The obvious alternative is AgriciDaniel/claude-seo, the upstream project this repository is ported from. The README states the port is synchronized to upstream main at a9cf338 and adapted for Codex skills, Codex plugins, TOML agents, shared cache artifacts, and repeatable local/API execution. The difference is therefore not the SEO methodology, which is shared, but the runtime: claude-seo targets Claude Code, while this project targets Codex and reorganizes the same material into TOML agent profiles and a Codex skill layout.

That makes the choice straightforward. If your team already runs Claude Code, the upstream project is the shorter path, and this port adds a translation layer you do not need. If you run Codex, this is the version whose installer writes to ~/.codex/skills/ and whose agents load from ~/.codex/agents/.

The wider alternative is a hosted SEO platform with a crawler, a dashboard and historical charts. Those handle scheduling, alerting and multi-user access out of the box. Codex SEO does not, based on the README: it is a local skill suite that produces files. The trade is control and cost transparency against operational convenience. You own the runs, the credentials and the artifacts, and nobody sends you a monthly invoice for seats.

Upgrades, Pinning and What the Repo Does Not Document

Because the installer defaults to a specific ref, v1.9.6-codex.5, the cleanest upgrade path is to re-run the installer with CODEX_SEO_REF set to the tag you want. The README shows exactly that pattern in its overrides example, and it is the only upgrade mechanism the documentation describes.

What the README does not document: rollback, a migration path between versions, or whether re-running the installer over an existing ~/.codex/skills/seo/.venv/ preserves or rebuilds the virtualenv. It also does not say whether your existing .seo-cache survives an upgrade. If you depend on cached evidence for month-over-month comparisons, snapshot the cache directory before you upgrade.

On licence implications, treat the NOASSERTION classification as a to-do, not a blocker. The metadata says MIT, which is permissive and typical for a tool of this kind, but the discrepancy between the repository classification and pyproject.toml is unresolved in what the repository publishes. Anyone embedding this in a product should resolve it with the LICENSE file and, if needed, the maintainer, rather than relying on a badge.

One practical note on pinning: since three releases landed on 2026-04-28, pinning to a branch rather than a tag would expose you to that churn directly. Pin the tag.

Editorial conclusion

Adopt Codex SEO if you already run Codex CLI and want SEO work to land as repeatable files in output/ rather than as chat text. Skip it if you want a hosted crawler, a GUI, or a tool that works without Codex installed. Before installing, check the LICENSE file against the MIT claim in pyproject.toml, confirm which optional requirement groups resolve on your Python version, and decide whether you are willing to supply DataForSEO, Google and Firecrawl credentials.

Frequently asked questions

Official sources

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