Codex SEO - SEO Audit Skill Suite for Codex
Codex-first SEO analysis suite with 1 orchestrator skill, 26 specialist workflows, 24 TOML agent profiles, MCP/API extensions, deterministic headless runners, and premium audit report generation.
Codex SEO is 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.
It covers 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.
Contents
Status
-
Repository visibility: public.
-
Current release: v1.9.6-codex.5.
-
Installer default ref:
v1.9.6-codex.5. -
Latest local validation: 52 tests passing, full installed smoke suite passing, demo readiness passing.
-
Runtime credentials stay outside the repo under Codex/local config paths.
-
Discovery topics:
codex,codex-cli,codex-skills,seo,ai-seo,ai-search,technical-seo,generative-engine-optimization,core-web-vitals,schema-markup,local-seo,ecommerce-seo,content-strategy,google-search-console,dataforseo,mcp,python,automation,marketing-automation,open-source.
Install
One-Line Install
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.5/install.sh | bash
Windows:
irm https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.5/install.ps1 | iex
Review Before Installing
git clone https://github.com/AgriciDaniel/codex-seo.git
cd codex-seo
bash install.sh
Windows:
git clone https://github.com/AgriciDaniel/codex-seo.git
cd codex-seo
powershell -ExecutionPolicy Bypass -File .\install.ps1
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.
Installer Overrides
CODEX_HOME=~/.codex \
CODEX_SEO_REPO=https://github.com/AgriciDaniel/codex-seo \
CODEX_SEO_REF=v1.9.6-codex.5 \
bash install.sh
Variable Purpose
CODEX_HOME
Alternate Codex home. Defaults to ~/.codex.
CODEX_SEO_REPO
Git URL, fork URL, or local repository path.
CODEX_SEO_REF
Branch, tag, or commit. Defaults to v1.9.6-codex.5.
CODEX_SEO_SKIP_PLAYWRIGHT_BROWSER=1
Skip Chromium install for visual/PDF workflows.
CODEX_SEO_PLAYWRIGHT_WITH_DEPS=1
Ask Playwright to install system dependencies where supported.
Quick Start
Restart Codex after installation. Then ask naturally; a /seo command is not required:
Do a full SEO check on https://example.com following best practices.
Review this page for schema, Core Web Vitals, image SEO, and AI search readiness.
Create an SEO strategy and content roadmap for a local dental clinic.
Command-style prompts also work:
/seo audit https://example.com
/seo technical https://example.com
/seo schema https://example.com
/seo dataforseo serp "best seo tools"
Visual Overview
Codex SEO is designed as a Codex-first routing layer: the user can ask naturally, the orchestrator selects the right specialist workflow, and deterministic runners write repeatable artifacts instead of relying on invisible chat-only output.
%%{init: {"theme":"base","themeVariables":{"background":"#05080d","primaryColor":"#07131c","primaryTextColor":"#f5fbff","primaryBorderColor":"#00d7e6","lineColor":"#00d7e6","secondaryColor":"#06222a","tertiaryColor":"#ff9f1c","edgeLabelBackground":"#05080d","fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
user["User prompt<br/>natural language or /seo"] --> orchestrator["skills/seo/SKILL.md<br/>main orchestrator"]
orchestrator --> cache[".seo-cache<br/>shared evidence"]
orchestrator --> skills["26 specialist<br/>SEO workflows"]
skills --> agents["24 TOML agents<br/>parallel analysis slices"]
skills --> scripts["scripts/<br/>deterministic runners"]
scripts --> output["output/<br/>Markdown, JSON, HTML, PDF"]
cache --> skills
class user,orchestrator accent
class cache,scripts data
class output output
classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px
classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px
classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px
classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px
Commands
Prompt Purpose
/seo audit <url>
Full site audit with specialist routing and premium report support
/seo page <url>
Deep single-page SEO analysis
/seo technical <url>
Crawlability, indexability, security, JavaScript, CWV
/seo content <url>
E-E-A-T, helpfulness, readability, AI citation readiness
/seo schema <url>
Structured data detection, validation, and JSON-LD generation
/seo images <url>
Alt text, image weight, formats, metadata, image SERP opportunities
/seo sitemap <url>
XML sitemap discovery, quality gates, generation guidance
/seo geo <url>
AI Overviews, ChatGPT, Perplexity, llms.txt, citability
/seo performance <url>
Core Web Vitals, Lighthouse-oriented performance signals
/seo visual <url>
Screenshots, mobile rendering, above-the-fold analysis
/seo plan <business-type>
Strategic SEO roadmap and content plan
/seo programmatic <url>
Programmatic SEO risk and scale planning
/seo competitor-pages <url>
Comparison and alternatives page opportunities
/seo hreflang <url>
International SEO, locale validation, content parity
/seo local <url>
Local SEO, GBP signals, NAP, citations, reviews
/seo maps <command>
Geo-grid, GBP audit, review intelligence, local maps signals
/seo google <command>
GSC, PageSpeed, CrUX, Indexing API, GA4 workflows
/seo backlinks <url>
Backlink profile summary and source-tier detection
/seo cluster <keyword>
SERP-based topic clustering and hub-spoke planning
/seo sxo <url>
Search Experience Optimization, intent/page-type fit
/seo drift baseline <url>
Capture an SEO baseline before changes
/seo drift compare <url>
Compare current SEO signals against a baseline
/seo ecommerce <url>
Product SEO, marketplace visibility, product schema
/seo flow <stage>
FLOW framework prompts for Find, Leverage, Optimize, Win
/seo dataforseo <command>
Live SERP, keyword, backlink, content, and AI visibility data
/seo firecrawl <command>
JS-rendered crawling and site mapping via Firecrawl
/seo image-gen <use-case>
OG images, hero images, product visuals, infographics
Full command details live in docs/COMMANDS.md.
Features
Full Audit Pipeline
-
Detects site/business type.
-
Runs technical, content, schema, sitemap, performance, visual, GEO, image, and on-page analysis.
-
Adds conditional specialists for local, maps, Google APIs, backlinks, clusters, SXO, drift, and e-commerce.
-
Writes markdown reports, JSON summaries, cache artifacts, and optional premium HTML/PDF output.
%%{init: {"theme":"base","themeVariables":{"background":"#05080d","primaryColor":"#07131c","primaryTextColor":"#f5fbff","primaryBorderColor":"#00d7e6","lineColor":"#00d7e6","secondaryColor":"#06222a","tertiaryColor":"#ff9f1c","edgeLabelBackground":"#05080d","fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart TD
request["Audit request"] --> detect["Detect site type<br/>business model and context"]
detect --> core["Core audit specialists"]
core --> technical["Technical"]
core --> content["Content"]
core --> schema["Schema"]
core --> sitemap["Sitemap"]
core --> geo["GEO / AI search"]
core --> images["Images"]
core --> performance["Performance"]
core --> visual["Visual"]
detect --> conditional["Conditional specialists"]
conditional --> local["Local / Maps"]
condit