{"id":49388741,"url":"https://github.com/agricidaniel/codex-seo","last_synced_at":"2026-05-04T17:01:58.990Z","repository":{"id":354288179,"uuid":"1222984521","full_name":"AgriciDaniel/codex-seo","owner":"AgriciDaniel","description":"Codex-first SEO skill suite. 26 workflows, 24 TOML agents, DataForSEO/Gemini/Google/Firecrawl integrations, GEO/AEO, CWV, schema, backlinks, local/maps, and deterministic reports.","archived":false,"fork":false,"pushed_at":"2026-04-30T03:00:15.000Z","size":1248,"stargazers_count":61,"open_issues_count":2,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-03T16:27:48.414Z","etag":null,"topics":["ai-search","ai-seo","automation","codex","codex-cli","codex-skills","content-strategy","core-web-vitals","dataforseo","ecommerce-seo","generative-engine-optimization","google-search-console","local-seo","marketing-automation","mcp","open-source","python","schema-markup","seo","technical-seo"],"latest_commit_sha":null,"homepage":"https://github.com/AgriciDaniel/codex-seo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgriciDaniel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["AgriciDaniel"]}},"created_at":"2026-04-27T22:43:34.000Z","updated_at":"2026-05-03T15:14:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AgriciDaniel/codex-seo","commit_stats":null,"previous_names":["agricidaniel/codex-seo"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/AgriciDaniel/codex-seo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgriciDaniel%2Fcodex-seo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgriciDaniel%2Fcodex-seo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgriciDaniel%2Fcodex-seo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgriciDaniel%2Fcodex-seo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgriciDaniel","download_url":"https://codeload.github.com/AgriciDaniel/codex-seo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgriciDaniel%2Fcodex-seo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32616270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-search","ai-seo","automation","codex","codex-cli","codex-skills","content-strategy","core-web-vitals","dataforseo","ecommerce-seo","generative-engine-optimization","google-search-console","local-seo","marketing-automation","mcp","open-source","python","schema-markup","seo","technical-seo"],"created_at":"2026-04-28T11:01:14.835Z","updated_at":"2026-05-04T17:01:58.949Z","avatar_url":"https://github.com/AgriciDaniel.png","language":"Python","funding_links":["https://github.com/sponsors/AgriciDaniel"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/cover-image.webp\" alt=\"Codex SEO: SEO audit skill suite for Codex\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Codex SEO - SEO Audit Skill Suite for Codex\n\nCodex-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.\n\n[![CI](https://github.com/AgriciDaniel/codex-seo/actions/workflows/runners-ci.yml/badge.svg)](https://github.com/AgriciDaniel/codex-seo/actions/workflows/runners-ci.yml)\n[![Release](https://img.shields.io/github/v/release/AgriciDaniel/codex-seo?label=Release)](https://github.com/AgriciDaniel/codex-seo/releases)\n[![Codex Skill](https://img.shields.io/badge/Codex-Skill_Suite-blue)](https://github.com/openai/codex)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](pyproject.toml)\n[![Workflows](https://img.shields.io/badge/SEO_Workflows-26-orange)](docs/COMMANDS.md)\n\nCodex SEO is a Codex-native port of [`AgriciDaniel/claude-seo`](https://github.com/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.\n\nIt 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.\n\n## Contents\n\n- [Status](#status)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Visual Overview](#visual-overview)\n- [Commands](#commands)\n- [Features](#features)\n- [Extensions](#extensions)\n- [Headless/API Usage](#headlessapi-usage)\n- [Architecture](#architecture)\n- [Verification](#verification)\n- [Requirements](#requirements)\n- [Credentials And Cache](#credentials-and-cache)\n- [Security](#security)\n- [Uninstall](#uninstall)\n- [Contributing](#contributing)\n- [Related Projects](#related-projects)\n- [Credits](#credits)\n- [Attribution](#attribution)\n\n## Status\n\n- Repository visibility: public.\n- Current release: [`v1.9.6-codex.4`](https://github.com/AgriciDaniel/codex-seo/releases/tag/v1.9.6-codex.4).\n- Installer default ref: `v1.9.6-codex.4`.\n- Latest local validation: 49 tests passing, full installed smoke suite passing, demo readiness passing.\n- Runtime credentials stay outside the repo under Codex/local config paths.\n- 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`.\n\n## Install\n\n### One-Line Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.4/install.sh | bash\n```\n\nWindows:\n\n```powershell\nirm https://raw.githubusercontent.com/AgriciDaniel/codex-seo/v1.9.6-codex.4/install.ps1 | iex\n```\n\n### Review Before Installing\n\n```bash\ngit clone https://github.com/AgriciDaniel/codex-seo.git\ncd codex-seo\nbash install.sh\n```\n\nWindows:\n\n```powershell\ngit clone https://github.com/AgriciDaniel/codex-seo.git\ncd codex-seo\npowershell -ExecutionPolicy Bypass -File .\\install.ps1\n```\n\nThe installer copies the skill suite into `~/.codex/skills/`, installs TOML agents into `~/.codex/agents/`, creates a Python virtualenv at `~/.codex/skills/seo/.venv/`, and verifies the runtime.\n\n### Installer Overrides\n\n```bash\nCODEX_HOME=~/.codex \\\nCODEX_SEO_REPO=https://github.com/AgriciDaniel/codex-seo \\\nCODEX_SEO_REF=v1.9.6-codex.4 \\\nbash install.sh\n```\n\n| Variable | Purpose |\n|---|---|\n| `CODEX_HOME` | Alternate Codex home. Defaults to `~/.codex`. |\n| `CODEX_SEO_REPO` | Git URL, fork URL, or local repository path. |\n| `CODEX_SEO_REF` | Branch, tag, or commit. Defaults to `v1.9.6-codex.4`. |\n| `CODEX_SEO_SKIP_PLAYWRIGHT_BROWSER=1` | Skip Chromium install for visual/PDF workflows. |\n| `CODEX_SEO_PLAYWRIGHT_WITH_DEPS=1` | Ask Playwright to install system dependencies where supported. |\n\n## Quick Start\n\nRestart Codex after installation. Then ask naturally; a `/seo` command is not required:\n\n```text\nDo a full SEO check on https://example.com following best practices.\n```\n\n```text\nReview this page for schema, Core Web Vitals, image SEO, and AI search readiness.\n```\n\n```text\nCreate an SEO strategy and content roadmap for a local dental clinic.\n```\n\nCommand-style prompts also work:\n\n```text\n/seo audit https://example.com\n/seo technical https://example.com\n/seo schema https://example.com\n/seo dataforseo serp \"best seo tools\"\n```\n\n## Visual Overview\n\nCodex 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.\n\n```mermaid\n%%{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\"}}}%%\nflowchart LR\n  user[\"User prompt\u003cbr/\u003enatural language or /seo\"] --\u003e orchestrator[\"skills/seo/SKILL.md\u003cbr/\u003emain orchestrator\"]\n  orchestrator --\u003e cache[\".seo-cache\u003cbr/\u003eshared evidence\"]\n  orchestrator --\u003e skills[\"26 specialist\u003cbr/\u003eSEO workflows\"]\n  skills --\u003e agents[\"24 TOML agents\u003cbr/\u003eparallel analysis slices\"]\n  skills --\u003e scripts[\"scripts/\u003cbr/\u003edeterministic runners\"]\n  scripts --\u003e output[\"output/\u003cbr/\u003eMarkdown, JSON, HTML, PDF\"]\n  cache --\u003e skills\n  class user,orchestrator accent\n  class cache,scripts data\n  class output output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n## Commands\n\n| Prompt | Purpose |\n|---|---|\n| `/seo audit \u003curl\u003e` | Full site audit with specialist routing and premium report support |\n| `/seo page \u003curl\u003e` | Deep single-page SEO analysis |\n| `/seo technical \u003curl\u003e` | Crawlability, indexability, security, JavaScript, CWV |\n| `/seo content \u003curl\u003e` | E-E-A-T, helpfulness, readability, AI citation readiness |\n| `/seo schema \u003curl\u003e` | Structured data detection, validation, and JSON-LD generation |\n| `/seo images \u003curl\u003e` | Alt text, image weight, formats, metadata, image SERP opportunities |\n| `/seo sitemap \u003curl\u003e` | XML sitemap discovery, quality gates, generation guidance |\n| `/seo geo \u003curl\u003e` | AI Overviews, ChatGPT, Perplexity, llms.txt, citability |\n| `/seo performance \u003curl\u003e` | Core Web Vitals, Lighthouse-oriented performance signals |\n| `/seo visual \u003curl\u003e` | Screenshots, mobile rendering, above-the-fold analysis |\n| `/seo plan \u003cbusiness-type\u003e` | Strategic SEO roadmap and content plan |\n| `/seo programmatic \u003curl\u003e` | Programmatic SEO risk and scale planning |\n| `/seo competitor-pages \u003curl\u003e` | Comparison and alternatives page opportunities |\n| `/seo hreflang \u003curl\u003e` | International SEO, locale validation, content parity |\n| `/seo local \u003curl\u003e` | Local SEO, GBP signals, NAP, citations, reviews |\n| `/seo maps \u003ccommand\u003e` | Geo-grid, GBP audit, review intelligence, local maps signals |\n| `/seo google \u003ccommand\u003e` | GSC, PageSpeed, CrUX, Indexing API, GA4 workflows |\n| `/seo backlinks \u003curl\u003e` | Backlink profile summary and source-tier detection |\n| `/seo cluster \u003ckeyword\u003e` | SERP-based topic clustering and hub-spoke planning |\n| `/seo sxo \u003curl\u003e` | Search Experience Optimization, intent/page-type fit |\n| `/seo drift baseline \u003curl\u003e` | Capture an SEO baseline before changes |\n| `/seo drift compare \u003curl\u003e` | Compare current SEO signals against a baseline |\n| `/seo ecommerce \u003curl\u003e` | Product SEO, marketplace visibility, product schema |\n| `/seo flow \u003cstage\u003e` | FLOW framework prompts for Find, Leverage, Optimize, Win |\n| `/seo dataforseo \u003ccommand\u003e` | Live SERP, keyword, backlink, content, and AI visibility data |\n| `/seo firecrawl \u003ccommand\u003e` | JS-rendered crawling and site mapping via Firecrawl |\n| `/seo image-gen \u003cuse-case\u003e` | OG images, hero images, product visuals, infographics |\n\nFull command details live in [docs/COMMANDS.md](docs/COMMANDS.md).\n\n## Features\n\n### Full Audit Pipeline\n\n- Detects site/business type.\n- Runs technical, content, schema, sitemap, performance, visual, GEO, image, and on-page analysis.\n- Adds conditional specialists for local, maps, Google APIs, backlinks, clusters, SXO, drift, and e-commerce.\n- Writes markdown reports, JSON summaries, cache artifacts, and optional premium HTML/PDF output.\n\n```mermaid\n%%{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\"}}}%%\nflowchart TD\n  request[\"Audit request\"] --\u003e detect[\"Detect site type\u003cbr/\u003ebusiness model and context\"]\n  detect --\u003e core[\"Core audit specialists\"]\n  core --\u003e technical[\"Technical\"]\n  core --\u003e content[\"Content\"]\n  core --\u003e schema[\"Schema\"]\n  core --\u003e sitemap[\"Sitemap\"]\n  core --\u003e geo[\"GEO / AI search\"]\n  core --\u003e images[\"Images\"]\n  core --\u003e performance[\"Performance\"]\n  core --\u003e visual[\"Visual\"]\n  detect --\u003e conditional[\"Conditional specialists\"]\n  conditional --\u003e local[\"Local / Maps\"]\n  conditional --\u003e backlinks[\"Backlinks\"]\n  conditional --\u003e google[\"Google APIs\"]\n  conditional --\u003e ecommerce[\"E-commerce\"]\n  conditional --\u003e drift[\"Drift\"]\n  technical --\u003e report[\"Unified SEO report\"]\n  content --\u003e report\n  schema --\u003e report\n  sitemap --\u003e report\n  geo --\u003e report\n  images --\u003e report\n  performance --\u003e report\n  visual --\u003e report\n  local --\u003e report\n  backlinks --\u003e report\n  google --\u003e report\n  ecommerce --\u003e report\n  drift --\u003e report\n  report --\u003e artifacts[\"SUMMARY.json\u003cbr/\u003eFULL-AUDIT-REPORT.md\u003cbr/\u003eACTION-PLAN.md\u003cbr/\u003eoptional HTML/PDF\"]\n  class request,detect accent\n  class core,conditional data\n  class report,artifacts output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n### Technical SEO\n\n- Robots.txt, sitemap discovery, canonical checks, indexability, URL hygiene.\n- Security headers, JavaScript rendering risk, mobile basics, IndexNow.\n- Core Web Vitals with INP, LCP, CLS, FCP, TTFB, and PageSpeed/CrUX integrations where available.\n\n### Content, GEO, And SXO\n\n- E-E-A-T and helpful content signals.\n- AI citation readiness, answer-first formatting, entity clarity, llms.txt support.\n- Search experience analysis: page type, user stories, persona fit, intent mismatch.\n\n### Structured Data\n\n- JSON-LD extraction and validation.\n- Schema recommendations for Organization, LocalBusiness, Product, Article, FAQ, Breadcrumb, and related types.\n- Generated schema artifacts for downstream use.\n\n### Local, Maps, And E-Commerce SEO\n\n- Local SEO signals, GBP readiness, citations, reviews, NAP consistency.\n- Maps intelligence via free sources and DataForSEO when configured.\n- Product schema, marketplace endpoints, merchant visibility, and e-commerce template checks.\n\n### Drift Monitoring\n\n- Capture SEO-critical baselines.\n- Compare deployments or page changes.\n- Track title, meta, headings, canonical, schema, robots, links, and content deltas.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"actorBkg\":\"#07131c\",\"actorBorder\":\"#00d7e6\",\"actorTextColor\":\"#f5fbff\",\"actorLineColor\":\"#21e6c1\",\"signalColor\":\"#21e6c1\",\"signalTextColor\":\"#f5fbff\",\"labelBoxBkgColor\":\"#10151a\",\"labelTextColor\":\"#f5fbff\",\"noteBkgColor\":\"#10151a\",\"noteTextColor\":\"#f5fbff\",\"activationBkgColor\":\"#06222a\",\"activationBorderColor\":\"#ff9f1c\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nsequenceDiagram\n  participant Before as Baseline\n  participant Runner as Drift runner\n  participant After as Current page\n  participant Cache as .seo-cache\n  participant Report as Drift report\n  Before-\u003e\u003eRunner: Capture titles, metas, canonicals, schema, headings\n  Runner-\u003e\u003eCache: Store baseline snapshot\n  After-\u003e\u003eRunner: Re-check current SEO signals\n  Cache-\u003e\u003eRunner: Load prior snapshot\n  Runner-\u003e\u003eReport: Write changed, missing, and regressed signals\n```\n\n### Deterministic Runners\n\n- `scripts/run_skill_workflow.py` standardizes output for every user-invokable workflow.\n- `scripts/run_api_smoke_suite.py` runs all supported workflows in one pass.\n- Setup-required workflows return structured fallback results instead of pretending live data exists.\n\n## Extensions\n\n| Extension | Skill | Setup | Notes |\n|---|---|---|---|\n| DataForSEO | `seo-dataforseo`, `seo-maps`, `seo-ecommerce`, `seo-cluster` | `./extensions/dataforseo/install.sh` | Live SERP, keyword, backlinks, on-page, content, business data, AI visibility |\n| Google APIs | `seo-google`, `seo-performance` | `python scripts/google_auth.py --setup` | PageSpeed, CrUX, GSC, URL Inspection, Indexing API, GA4 |\n| Firecrawl | `seo-firecrawl` | `./extensions/firecrawl/install.sh` | JS-rendered crawl, scrape, site map |\n| Banana / Gemini | `seo-image-gen` | `./extensions/banana/install.sh` | AI image generation through `nanobanana-mcp` |\n\nOptional integrations enrich the same workflow surface. If credentials or MCP servers are missing, wrappers return `setup_required` or `mcp_configured` states with no fabricated live data.\n\n```mermaid\n%%{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\"}}}%%\nflowchart LR\n  codex[\"Codex SEO workflows\"] --\u003e local[\"Local evidence\u003cbr/\u003eHTML, robots, sitemaps, screenshots\"]\n  codex --\u003e dfs[\"DataForSEO MCP\u003cbr/\u003eSERP, keywords, backlinks, maps\"]\n  codex --\u003e google[\"Google APIs\u003cbr/\u003eGSC, PageSpeed, CrUX, GA4\"]\n  codex --\u003e firecrawl[\"Firecrawl MCP\u003cbr/\u003eJS crawl and site maps\"]\n  codex --\u003e banana[\"Gemini / nanobanana\u003cbr/\u003eSEO image assets\"]\n  local --\u003e artifacts[\"Reports and .seo-cache\"]\n  dfs --\u003e artifacts\n  google --\u003e artifacts\n  firecrawl --\u003e artifacts\n  banana --\u003e artifacts\n  class codex accent\n  class local,dfs,google,firecrawl,banana data\n  class artifacts output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\nDemo readiness:\n\n```bash\npython scripts/demo_readiness.py --target https://example.com --live-apis --workflows --json\n```\n\nOne low-depth DataForSEO proof:\n\n```bash\npython scripts/demo_readiness.py --target https://example.com --live-apis --live-serp --serp-keyword \"seo tools\" --json\n```\n\n## Headless/API Usage\n\nRun a single workflow:\n\n```bash\npython scripts/run_skill_workflow.py --skill seo-technical https://example.com --json\npython scripts/run_skill_workflow.py --skill seo-google https://example.com --json\npython scripts/run_skill_workflow.py --skill seo-dataforseo https://example.com --json\n```\n\nRun the full smoke suite:\n\n```bash\npython scripts/run_api_smoke_suite.py https://example.com --json\n```\n\nVerify environment:\n\n```bash\npython scripts/verify_environment.py --target https://example.com --json\n```\n\nBootstrap a clean runtime:\n\n```bash\npython scripts/bootstrap_environment.py --venv .venv --json\n```\n\nArtifacts are written to `output/`. Shared project cache is written to `.seo-cache/`. Both are ignored by git.\n\n```mermaid\n%%{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\"}}}%%\nflowchart LR\n  cli[\"run_skill_workflow.py\u003cbr/\u003esingle workflow\"] --\u003e json[\"JSON result\"]\n  cli --\u003e markdown[\"Markdown report\"]\n  cli --\u003e cacheWrite[\".seo-cache update\"]\n  suite[\"run_api_smoke_suite.py\u003cbr/\u003eall workflows\"] --\u003e json\n  suite --\u003e outputRoot[\"output/api-smoke-*\"]\n  verify[\"verify_environment.py\"] --\u003e readiness[\"ready / setup_required\u003cbr/\u003ecapability status\"]\n  markdown --\u003e outputRoot\n  json --\u003e outputRoot\n  cacheWrite --\u003e cache[\".seo-cache\"]\n  class cli,suite,verify accent\n  class cacheWrite,readiness data\n  class json,markdown,outputRoot,cache output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n## Architecture\n\nThe repository separates Codex-facing instructions, deterministic runtime code, optional provider setup, and validation contracts. That keeps the skill system usable in chat, installable as a suite, and testable from CI/API workflows.\n\n```mermaid\n%%{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\"}}}%%\nflowchart TB\n  manifest[\".codex-plugin/plugin.json\"] --\u003e skillsRoot[\"skills/\"]\n  skillsRoot --\u003e orchestrator[\"seo/SKILL.md\u003cbr/\u003erouting and orchestration\"]\n  skillsRoot --\u003e specialists[\"seo-*/SKILL.md\u003cbr/\u003especialist workflows\"]\n  agentsDir[\"agents/seo-*.toml\"] --\u003e specialists\n  scriptsDir[\"scripts/\u003cbr/\u003edeterministic runners\"] --\u003e specialists\n  extensionsDir[\"extensions/\u003cbr/\u003eoptional MCP setup\"] --\u003e specialists\n  references[\"skills/seo/references/\u003cbr/\u003ethresholds and shared contracts\"] --\u003e specialists\n  specialists --\u003e cacheDir[\".seo-cache/\u003cbr/\u003ecross-skill memory\"]\n  specialists --\u003e outputDir[\"output/\u003cbr/\u003ereports and artifacts\"]\n  testsDir[\"tests/\u003cbr/\u003econtract and smoke coverage\"] --\u003e manifest\n  testsDir --\u003e skillsRoot\n  testsDir --\u003e scriptsDir\n  class manifest,orchestrator accent\n  class skillsRoot,specialists,agentsDir,scriptsDir,extensionsDir,references,testsDir data\n  class cacheDir,outputDir output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n```text\ncodex-seo/\n├── .codex-plugin/plugin.json        # Codex plugin manifest\n├── skills/\n│   ├── seo/SKILL.md                 # Main orchestrator\n│   └── seo-*/SKILL.md               # 26 specialist workflows\n├── agents/                          # 24 Codex TOML agent profiles\n├── scripts/                         # Deterministic runners and API helpers\n├── extensions/\n│   ├── dataforseo/                  # DataForSEO MCP setup and docs\n│   ├── firecrawl/                   # Firecrawl MCP setup and docs\n│   └── banana/                      # Gemini/nanobanana image generation setup\n├── hooks/                           # Quality-gate hooks\n├── schema/                          # Schema.org templates\n├── docs/                            # Architecture, commands, installation, MCP, demo\n└── tests/                           # Contract and workflow tests\n```\n\nDesign principles:\n\n- `skills/` is the source of truth.\n- `skills/seo/SKILL.md` routes natural-language SEO requests.\n- TOML agents are Codex-native and mirror specialist workflows.\n- Runtime credentials stay in `~/.config/codex-seo/` or `~/.codex/settings.json`.\n- Legacy `claude-seo` config/cache paths are read only as migration fallback.\n\nMore detail: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n## Verification\n\nLocal release gate:\n\n```bash\npython -m pytest tests/\nbash -n install.sh uninstall.sh\npython -m compileall -q scripts hooks\npython scripts/run_api_smoke_suite.py https://example.com --json\n```\n\nPowerShell parse check:\n\n```powershell\n$files = Get-ChildItem -Recurse -Filter *.ps1\nforeach ($f in $files) {\n  $tokens = $null\n  $errs = $null\n  [System.Management.Automation.Language.Parser]::ParseFile($f.FullName, [ref]$tokens, [ref]$errs) \u003e $null\n  if ($errs.Count) { $errs; exit 1 }\n}\n```\n\nCurrent GitHub CI runs:\n\n- dependency install\n- shell syntax checks\n- Python compile checks\n- `--help` checks for runner scripts\n- `python -m pytest tests/`\n- contract smoke checks for MCP-aware workflows\n\n## Requirements\n\n- Codex CLI with local skills support\n- Python 3.10+\n- Git\n- Optional: Playwright Chromium for screenshots and PDF reports\n- Optional: DataForSEO account for live SEO data\n- Optional: Google API credentials for PageSpeed/CrUX/GSC/GA4\n- Optional: Firecrawl API key for JS-rendered crawling\n- Optional: Google AI API key for Gemini/nanobanana image generation\n\n## Credentials And Cache\n\nCodex SEO writes new local credentials and state to Codex-specific paths:\n\n- `~/.codex/settings.json` for MCP server configuration\n- `~/.config/codex-seo/` for API configs and cost ledgers\n- `~/.cache/codex-seo/` for runtime caches\n- `.seo-cache/` inside the active project for cross-skill summaries\n\nLegacy `~/.config/claude-seo/` and `~/.cache/claude-seo/` paths are read only as migration fallback. Do not commit `.seo-cache/`, `output/`, `.mcp.json`, `.env`, OAuth tokens, service accounts, or provider keys.\n\n## Security\n\n- URL-aware scripts block private, loopback, reserved, multicast, unspecified, and metadata hosts.\n- Credential setup writes outside tracked repo files.\n- Sensitive local settings are expected to use `0600` file permissions.\n- DataForSEO calls use cost guardrails through `scripts/dataforseo_costs.py`.\n- Report vulnerabilities through [SECURITY.md](SECURITY.md).\n\n## Uninstall\n\n```bash\nbash uninstall.sh\n```\n\nWindows:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\uninstall.ps1\n```\n\n## Contributing\n\nUse [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and validation, [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project standards, [SECURITY.md](SECURITY.md) for vulnerability reporting, and [CREDITS.md](CREDITS.md) for project credits. Agent-facing project context is also available in [llms.txt](llms.txt).\n\n## Related Projects\n\n- [`claude-seo`](https://github.com/AgriciDaniel/claude-seo) - original Claude Code SEO skill suite\n- [`claude-blog`](https://github.com/AgriciDaniel/claude-blog) - blog creation and optimization skill ecosystem\n- [`claude-ads`](https://github.com/AgriciDaniel/claude-ads) - paid advertising audit skill suite\n- [`flow`](https://github.com/AgriciDaniel/flow) - evidence-led SEO framework for AI search\n- [`wp-mcp-ultimate`](https://github.com/AgriciDaniel/wp-mcp-ultimate) - WordPress MCP server\n\n## Credits\n\nSpecial thanks to [avalonreset](https://github.com/avalonreset) for making the Codex conversion possible and for creating the initial Codex SEO version that this repository builds on.\n\n## Attribution\n\nOriginal project and concept by [AgriciDaniel](https://github.com/AgriciDaniel) in [`claude-seo`](https://github.com/AgriciDaniel/claude-seo). This Codex port preserves upstream SEO capabilities and adapts the runtime for Codex skills, TOML agents, plugin discovery, cache sharing, MCP extension setup, and API-safe wrappers.\n\nCodex SEO is released under the MIT License. FLOW prompt references retain their upstream attribution and licensing notices where included.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagricidaniel%2Fcodex-seo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagricidaniel%2Fcodex-seo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagricidaniel%2Fcodex-seo/lists"}