{"id":50188596,"url":"https://github.com/avalonreset/seo-dungeon","last_synced_at":"2026-06-13T20:01:13.081Z","repository":{"id":352029534,"uuid":"1213586443","full_name":"avalonreset/seo-dungeon","owner":"avalonreset","description":"Codex-first 16-bit dungeon crawler that turns SEO audits into boss battles, with legacy Claude compatibility behind explicit opt-in.","archived":false,"fork":false,"pushed_at":"2026-06-13T12:48:35.000Z","size":54061,"stargazers_count":19,"open_issues_count":10,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T14:25:26.977Z","etag":null,"topics":["ai-agents","ai-seo","ai-tools","codex","codex-cli","developer-tools","dungeon-crawler","gamification","javascript","phaser-js","seo","seo-audit","seo-automation","seo-tools","turn-based-combat","web-audio-api"],"latest_commit_sha":null,"homepage":"https://seodungeon.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avalonreset.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":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","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":{"custom":["https://www.skool.com/ai-marketing-hub-pro"]}},"created_at":"2026-04-17T14:38:21.000Z","updated_at":"2026-06-13T12:46:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/avalonreset/seo-dungeon","commit_stats":null,"previous_names":["avalonreset/claude-seo-dungeon","avalonreset/seo-dungeon"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/avalonreset/seo-dungeon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avalonreset%2Fseo-dungeon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avalonreset%2Fseo-dungeon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avalonreset%2Fseo-dungeon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avalonreset%2Fseo-dungeon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avalonreset","download_url":"https://codeload.github.com/avalonreset/seo-dungeon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avalonreset%2Fseo-dungeon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34298252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-agents","ai-seo","ai-tools","codex","codex-cli","developer-tools","dungeon-crawler","gamification","javascript","phaser-js","seo","seo-audit","seo-automation","seo-tools","turn-based-combat","web-audio-api"],"created_at":"2026-05-25T11:33:47.595Z","updated_at":"2026-06-13T20:01:13.074Z","avatar_url":"https://github.com/avalonreset.png","language":"JavaScript","funding_links":["https://www.skool.com/ai-marketing-hub-pro"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"assets/banner.webp\"\u003e\u003cimg src=\"assets/banner.webp\" alt=\"SEO Dungeon - Gamified SEO Audit Tool\" width=\"100%\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# SEO Dungeon - AI SEO Audits as Dungeon Battles\n\n[![CI](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml/badge.svg)](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Version](https://img.shields.io/badge/version-2.2.4-blue)](CHANGELOG.md)\n[![Runtime](https://img.shields.io/badge/runtime-Codex%20%7C%20Claude%20%7C%20Gemini-2ea44f)](dungeon/)\n\nSEO Dungeon turns SEO audits into a 16-bit dungeon crawler. Enter a domain,\ninspect the issues as demons, and use a local AI CLI to analyze or fix them\ninside your project. The packaged bridge selects Codex by default and also\nsupports Claude Code and Gemini CLI when those local tools are installed.\n\n## Screenshots\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003ca href=\"screenshots/title-screen.webp\"\u003e\u003cimg src=\"screenshots/title-screen.webp\" alt=\"SEO Dungeon title screen with character and runtime selection\"\u003e\u003c/a\u003e\u003cbr\u003e\u003cem\u003ePick a CLI, pick a warrior, enter a domain\u003c/em\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003ca href=\"screenshots/gate-scene-full.webp\"\u003e\u003cimg src=\"screenshots/gate-scene-full.webp\" alt=\"Gate scene showing quest continuation options\"\u003e\u003c/a\u003e\u003cbr\u003e\u003cem\u003eContinue a previous quest or begin a new one\u003c/em\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003ca href=\"screenshots/dungeon-hall.webp\"\u003e\u003cimg src=\"screenshots/dungeon-hall.webp\" alt=\"Dungeon hall showing SEO issue demons sorted by severity\"\u003e\u003c/a\u003e\u003cbr\u003e\u003cem\u003eBrowse SEO demons sorted by severity\u003c/em\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003ca href=\"screenshots/battle-scene.webp\"\u003e\u003cimg src=\"screenshots/battle-scene.webp\" alt=\"Turn-based battle scene with real-time Guild Ledger\"\u003e\u003c/a\u003e\u003cbr\u003e\u003cem\u003eBattle demons with agent-powered fixes\u003c/em\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## How It Works\n\n1. Choose a local CLI runtime: Codex, Claude Code, or Gemini CLI. Codex is\n   selected by default in the packaged app.\n2. Choose a character profile:\n   - Warrior: deep profile. Codex uses `xhigh`; Claude uses `opus`; Gemini uses `pro`.\n   - Samurai: balanced profile. Codex uses `high`; Claude uses `sonnet`; Gemini uses `flash`.\n   - Knight: fast profile. Codex uses `medium`; Claude uses `haiku`; Gemini uses `flash-lite`.\n3. Enter a domain and local project path.\n4. Run a full `/seo audit` through the selected local CLI.\n5. Review SEO issues as dungeon demons sorted by severity.\n6. Use **Attack** to send a scoped agent turn for the selected issue.\n7. Use **Vanquish** when you decide the issue is handled.\n\nThe Guild Ledger sidebar can be resized or hidden while you work, and the title\nscreen remembers your last domain and project folder.\n\nThe dungeon bridge starts local CLI processes only. It does not proxy model\naccess and does not route through browser automation or consumer-app wrappers.\n\n## SEO Engine\n\nThe bundled v2.2 engine is synchronized with Daniel Agrici's public\n`AgriciDaniel/claude-seo` v2.2.0 release. It includes 25 sub-skills (21 core +\n1 orchestrator + 1 framework integration + 2 extension mirrors), 18 portable\nsub-agents, 23 Codex agent profiles, and 50 Python execution scripts.\n\n| Area | Coverage |\n|------|----------|\n| Audit | Full-site audits, page audits, technical SEO, schema, sitemap, image SEO, hardened URL safety |\n| Content | E-E-A-T, content briefs, semantic clustering, SXO, competitor pages, QRG-aligned quality gates |\n| Growth | Local SEO, maps intelligence, backlinks, e-commerce, programmatic SEO |\n| Monitoring | SEO drift baselines and comparisons |\n| Data | Google SEO APIs, DataForSEO, Firecrawl, Ahrefs, Bing Webmaster, Profound, SE Ranking, Unlighthouse |\n| Assets | SEO image generation planning through the optional Banana/Gemini extension mirror |\n| Framework | FLOW prompts for Find, Leverage, Optimize, Win, and local workflows |\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 22+\n- Python 3.10+\n- Git\n- Codex CLI installed and signed in for the packaged default runtime\n- Optional: Claude Code CLI or Gemini CLI for the runtime picker options\n\n### Install Codex Skills\n\n```powershell\n# Windows\n.\\install.ps1\n```\n\n```bash\n# macOS/Linux\nbash install.sh\n```\n\nThe installer places the SEO skills under your Codex home and copies the Codex\nTOML profiles into the Codex agents folder. The portable `agents/` Markdown\nprompts remain in the repository for compatible non-Codex agent workflows.\n\n### Run The Game\n\n```bash\ncd dungeon\nnpm install\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000). The bridge server starts on\nport `3001`.\n\nFor live development visibility, keep a second terminal open:\n\n```bash\ncd dungeon\nnpm run logs\n```\n\nThe bridge mirrors startup, runtime selection, CLI executable paths, child\nexits, and errors to `dungeon/.logs/bridge.log`.\n\nRuntime environment:\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `SEO_DUNGEON_RUNTIME` | `codex` | Bridge fallback runtime when the UI does not send one |\n| `SEO_DUNGEON_CODEX_CLI` | `codex` | Codex executable override |\n| `SEO_DUNGEON_CLAUDE_CLI` | `claude` | Claude Code executable override |\n| `SEO_DUNGEON_GEMINI_CLI` | `gemini` | Gemini CLI executable override |\n| `SEO_DUNGEON_CODEX_MODEL` | Codex default | Optional Codex model override |\n| `SEO_DUNGEON_CODEX_EFFORT_DEEP` | `xhigh` | Codex Warrior effort |\n| `SEO_DUNGEON_CODEX_EFFORT_BALANCED` | `high` | Codex Samurai effort |\n| `SEO_DUNGEON_CODEX_EFFORT_FAST` | `medium` | Codex Knight effort |\n| `SEO_DUNGEON_CLAUDE_MODEL_DEEP` | `opus` | Claude Warrior model alias |\n| `SEO_DUNGEON_CLAUDE_MODEL_BALANCED` | `sonnet` | Claude Samurai model alias |\n| `SEO_DUNGEON_CLAUDE_MODEL_FAST` | `haiku` | Claude Knight model alias |\n| `SEO_DUNGEON_GEMINI_MODEL_DEEP` | `pro` | Gemini Warrior model alias |\n| `SEO_DUNGEON_GEMINI_MODEL_BALANCED` | `flash` | Gemini Samurai model alias |\n| `SEO_DUNGEON_GEMINI_MODEL_FAST` | `flash-lite` | Gemini Knight model alias |\n| `GEMINI_API_KEY` | unset | Required by Gemini CLI when it is not authenticated through another supported Gemini CLI auth path |\n| `SEO_DUNGEON_CLAUDE_ARGS` | `--print --output-format text --permission-mode acceptEdits` | Claude CLI argument template |\n| `SEO_DUNGEON_GEMINI_ARGS` | `--prompt {{prompt}} --output-format text --approval-mode auto_edit` | Gemini CLI argument template |\n\nSet a model variable to `default`, `auto`, or `none` to let that CLI use its own\nconfigured default model.\n\nFirst audits can take 5-10 minutes because `/seo audit` fans out many tool\ncalls. Cached audits are much faster.\n\n## Commands\n\n| Command | What it does |\n|---------|-------------|\n| `/seo audit \u003curl\u003e` | Full website audit |\n| `/seo page \u003curl\u003e` | Deep single-page analysis |\n| `/seo technical \u003curl\u003e` | Technical SEO audit |\n| `/seo content \u003curl\u003e` | E-E-A-T and content quality |\n| `/seo content-brief \u003ctopic or url\u003e` | Detailed SEO content brief |\n| `/seo schema \u003curl\u003e` | Schema.org detection and generation |\n| `/seo sitemap \u003curl\u003e` | XML sitemap analysis or generation |\n| `/seo images \u003curl\u003e` | Image SEO analysis |\n| `/seo geo \u003curl\u003e` | AI search readiness |\n| `/seo plan \u003ctype\u003e` | Strategic SEO planning |\n| `/seo flow [stage] [url|topic]` | FLOW framework prompts |\n| `/seo cluster \u003ckeyword\u003e` | Semantic clustering |\n| `/seo sxo \u003curl\u003e` | Search experience optimization |\n| `/seo drift baseline \u003curl\u003e` | Capture drift baseline |\n| `/seo drift compare \u003curl\u003e` | Compare against drift baseline |\n| `/seo ecommerce \u003curl\u003e` | E-commerce SEO |\n| `/seo programmatic [url]` | Programmatic SEO |\n| `/seo competitor-pages [url]` | Competitor comparison pages |\n| `/seo local \u003curl\u003e` | Local SEO |\n| `/seo maps [cmd] [args]` | Maps intelligence |\n| `/seo hreflang \u003curl\u003e` | International SEO |\n| `/seo google [cmd] [url]` | Google SEO APIs |\n| `/seo backlinks \u003curl\u003e` | Backlink analysis |\n| `/seo dataforseo [cmd]` | DataForSEO extension |\n| `/seo firecrawl [cmd] \u003curl\u003e` | Firecrawl extension |\n| `/seo image-gen [use-case]` | SEO image generation planning extension |\n\n## Architecture\n\n```text\nseo-dungeon/\n  dungeon/                         # Phaser game and WebSocket bridge\n    server/index.js                # Local CLI bridge\n    src/scenes/                    # Game scenes\n    src/utils/                     # Sound, WebSocket client, colors, particles\n  skills/                          # 25 SEO engine skills\n  agents/                          # 18 portable Markdown agent prompts\n  agents-codex/                    # 23 Codex TOML agent profiles\n  scripts/                         # 50 Python SEO scripts\n  schema/                          # JSON-LD templates\n  extensions/                      # Optional SEO data, crawl, and asset add-ons\n```\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| \"The dungeon is unreachable\" | Bridge server is not running. Run `npm run server` in `dungeon/`. |\n| Skills not found by Codex | Run `install.ps1` or `install.sh` from the repo root. |\n| Codex, Claude, or Gemini fails to spawn | Confirm the selected CLI is installed, signed in, and available on `PATH`. On Windows, the bridge resolves `.ps1`, `.cmd`, `.bat`, and `.exe` shims before launching; override `SEO_DUNGEON_CODEX_CLI`, `SEO_DUNGEON_CLAUDE_CLI`, or `SEO_DUNGEON_GEMINI_CLI` if your CLI lives elsewhere. |\n| Audit takes a long time | Normal for first full-site audits. Use cached audits when available. |\n| Google API commands fail | Run `/seo google` for setup instructions. |\n| Drift baseline not found | Run `/seo drift baseline \u003curl\u003e` before `/seo drift compare \u003curl\u003e`. |\n\n## Asset Credits\n\n| Asset | Creator | License | Source |\n|-------|---------|---------|--------|\n| DungeonTileset II | 0x72 | CC0 | [itch.io](https://0x72.itch.io/dungeontileset-ii) |\n| Medieval Warrior Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/medieval-warrior-pack-2) |\n| Martial Hero Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/martial-hero) |\n| RPG GUI Construction Kit v1.0 | Lamoot | CC-BY 3.0 | [OpenGameArt](https://opengameart.org/content/rpg-gui-construction-kit-v10) |\n| Golden UI | Buch | CC0 | [OpenGameArt](https://opengameart.org/content/golden-ui) |\n\n## License\n\n[MIT](LICENSE) - Copyright (c) 2026 Avalon Reset.\n\nSEO engine code is derived from Daniel Agrici's open-source SEO skill suite and\nused under the MIT license. SEO Dungeon is independent and runs through local\nterminal-agent workflows selected in the app.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favalonreset%2Fseo-dungeon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favalonreset%2Fseo-dungeon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favalonreset%2Fseo-dungeon/lists"}