https://github.com/avalonreset/seo-dungeon
Codex-first 16-bit dungeon crawler that turns SEO audits into boss battles, with legacy Claude compatibility behind explicit opt-in.
https://github.com/avalonreset/seo-dungeon
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
Last synced: 13 days ago
JSON representation
Codex-first 16-bit dungeon crawler that turns SEO audits into boss battles, with legacy Claude compatibility behind explicit opt-in.
- Host: GitHub
- URL: https://github.com/avalonreset/seo-dungeon
- Owner: avalonreset
- License: mit
- Created: 2026-04-17T14:38:21.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-13T12:48:35.000Z (14 days ago)
- Last Synced: 2026-06-13T14:25:26.977Z (14 days ago)
- 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
- Language: JavaScript
- Homepage: https://seodungeon.com
- Size: 51.6 MB
- Stars: 19
- Watchers: 1
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# SEO Dungeon - AI SEO Audits as Dungeon Battles
[](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml)
[](LICENSE)
[](CHANGELOG.md)
[](dungeon/)
SEO Dungeon turns SEO audits into a 16-bit dungeon crawler. Enter a domain,
inspect the issues as demons, and use a local AI CLI to analyze or fix them
inside your project. The packaged bridge selects Codex by default and also
supports Claude Code and Gemini CLI when those local tools are installed.
## Screenshots
Pick a CLI, pick a warrior, enter a domain
Continue a previous quest or begin a new one
Browse SEO demons sorted by severity
Battle demons with agent-powered fixes
## How It Works
1. Choose a local CLI runtime: Codex, Claude Code, or Gemini CLI. Codex is
selected by default in the packaged app.
2. Choose a character profile:
- Warrior: deep profile. Codex uses `xhigh`; Claude uses `opus`; Gemini uses `pro`.
- Samurai: balanced profile. Codex uses `high`; Claude uses `sonnet`; Gemini uses `flash`.
- Knight: fast profile. Codex uses `medium`; Claude uses `haiku`; Gemini uses `flash-lite`.
3. Enter a domain and local project path.
4. Run a full `/seo audit` through the selected local CLI.
5. Review SEO issues as dungeon demons sorted by severity.
6. Use **Attack** to send a scoped agent turn for the selected issue.
7. Use **Vanquish** when you decide the issue is handled.
The Guild Ledger sidebar can be resized or hidden while you work, and the title
screen remembers your last domain and project folder.
The dungeon bridge starts local CLI processes only. It does not proxy model
access and does not route through browser automation or consumer-app wrappers.
## SEO Engine
The bundled v2.2 engine is synchronized with Daniel Agrici's public
`AgriciDaniel/claude-seo` v2.2.0 release. It includes 25 sub-skills (21 core +
1 orchestrator + 1 framework integration + 2 extension mirrors), 18 portable
sub-agents, 23 Codex agent profiles, and 50 Python execution scripts.
| Area | Coverage |
|------|----------|
| Audit | Full-site audits, page audits, technical SEO, schema, sitemap, image SEO, hardened URL safety |
| Content | E-E-A-T, content briefs, semantic clustering, SXO, competitor pages, QRG-aligned quality gates |
| Growth | Local SEO, maps intelligence, backlinks, e-commerce, programmatic SEO |
| Monitoring | SEO drift baselines and comparisons |
| Data | Google SEO APIs, DataForSEO, Firecrawl, Ahrefs, Bing Webmaster, Profound, SE Ranking, Unlighthouse |
| Assets | SEO image generation planning through the optional Banana/Gemini extension mirror |
| Framework | FLOW prompts for Find, Leverage, Optimize, Win, and local workflows |
## Quick Start
### Prerequisites
- Node.js 22+
- Python 3.10+
- Git
- Codex CLI installed and signed in for the packaged default runtime
- Optional: Claude Code CLI or Gemini CLI for the runtime picker options
### Install Codex Skills
```powershell
# Windows
.\install.ps1
```
```bash
# macOS/Linux
bash install.sh
```
The installer places the SEO skills under your Codex home and copies the Codex
TOML profiles into the Codex agents folder. The portable `agents/` Markdown
prompts remain in the repository for compatible non-Codex agent workflows.
### Run The Game
```bash
cd dungeon
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000). The bridge server starts on
port `3001`.
For live development visibility, keep a second terminal open:
```bash
cd dungeon
npm run logs
```
The bridge mirrors startup, runtime selection, CLI executable paths, child
exits, and errors to `dungeon/.logs/bridge.log`.
Runtime environment:
| Variable | Default | Purpose |
|----------|---------|---------|
| `SEO_DUNGEON_RUNTIME` | `codex` | Bridge fallback runtime when the UI does not send one |
| `SEO_DUNGEON_CODEX_CLI` | `codex` | Codex executable override |
| `SEO_DUNGEON_CLAUDE_CLI` | `claude` | Claude Code executable override |
| `SEO_DUNGEON_GEMINI_CLI` | `gemini` | Gemini CLI executable override |
| `SEO_DUNGEON_CODEX_MODEL` | Codex default | Optional Codex model override |
| `SEO_DUNGEON_CODEX_EFFORT_DEEP` | `xhigh` | Codex Warrior effort |
| `SEO_DUNGEON_CODEX_EFFORT_BALANCED` | `high` | Codex Samurai effort |
| `SEO_DUNGEON_CODEX_EFFORT_FAST` | `medium` | Codex Knight effort |
| `SEO_DUNGEON_CLAUDE_MODEL_DEEP` | `opus` | Claude Warrior model alias |
| `SEO_DUNGEON_CLAUDE_MODEL_BALANCED` | `sonnet` | Claude Samurai model alias |
| `SEO_DUNGEON_CLAUDE_MODEL_FAST` | `haiku` | Claude Knight model alias |
| `SEO_DUNGEON_GEMINI_MODEL_DEEP` | `pro` | Gemini Warrior model alias |
| `SEO_DUNGEON_GEMINI_MODEL_BALANCED` | `flash` | Gemini Samurai model alias |
| `SEO_DUNGEON_GEMINI_MODEL_FAST` | `flash-lite` | Gemini Knight model alias |
| `GEMINI_API_KEY` | unset | Required by Gemini CLI when it is not authenticated through another supported Gemini CLI auth path |
| `SEO_DUNGEON_CLAUDE_ARGS` | `--print --output-format text --permission-mode acceptEdits` | Claude CLI argument template |
| `SEO_DUNGEON_GEMINI_ARGS` | `--prompt {{prompt}} --output-format text --approval-mode auto_edit` | Gemini CLI argument template |
Set a model variable to `default`, `auto`, or `none` to let that CLI use its own
configured default model.
First audits can take 5-10 minutes because `/seo audit` fans out many tool
calls. Cached audits are much faster.
## Commands
| Command | What it does |
|---------|-------------|
| `/seo audit ` | Full website audit |
| `/seo page ` | Deep single-page analysis |
| `/seo technical ` | Technical SEO audit |
| `/seo content ` | E-E-A-T and content quality |
| `/seo content-brief ` | Detailed SEO content brief |
| `/seo schema ` | Schema.org detection and generation |
| `/seo sitemap ` | XML sitemap analysis or generation |
| `/seo images ` | Image SEO analysis |
| `/seo geo ` | AI search readiness |
| `/seo plan ` | Strategic SEO planning |
| `/seo flow [stage] [url|topic]` | FLOW framework prompts |
| `/seo cluster ` | Semantic clustering |
| `/seo sxo ` | Search experience optimization |
| `/seo drift baseline ` | Capture drift baseline |
| `/seo drift compare ` | Compare against drift baseline |
| `/seo ecommerce ` | E-commerce SEO |
| `/seo programmatic [url]` | Programmatic SEO |
| `/seo competitor-pages [url]` | Competitor comparison pages |
| `/seo local ` | Local SEO |
| `/seo maps [cmd] [args]` | Maps intelligence |
| `/seo hreflang ` | International SEO |
| `/seo google [cmd] [url]` | Google SEO APIs |
| `/seo backlinks ` | Backlink analysis |
| `/seo dataforseo [cmd]` | DataForSEO extension |
| `/seo firecrawl [cmd] ` | Firecrawl extension |
| `/seo image-gen [use-case]` | SEO image generation planning extension |
## Architecture
```text
seo-dungeon/
dungeon/ # Phaser game and WebSocket bridge
server/index.js # Local CLI bridge
src/scenes/ # Game scenes
src/utils/ # Sound, WebSocket client, colors, particles
skills/ # 25 SEO engine skills
agents/ # 18 portable Markdown agent prompts
agents-codex/ # 23 Codex TOML agent profiles
scripts/ # 50 Python SEO scripts
schema/ # JSON-LD templates
extensions/ # Optional SEO data, crawl, and asset add-ons
```
## Troubleshooting
| Problem | Fix |
|---------|-----|
| "The dungeon is unreachable" | Bridge server is not running. Run `npm run server` in `dungeon/`. |
| Skills not found by Codex | Run `install.ps1` or `install.sh` from the repo root. |
| 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. |
| Audit takes a long time | Normal for first full-site audits. Use cached audits when available. |
| Google API commands fail | Run `/seo google` for setup instructions. |
| Drift baseline not found | Run `/seo drift baseline ` before `/seo drift compare `. |
## Asset Credits
| Asset | Creator | License | Source |
|-------|---------|---------|--------|
| DungeonTileset II | 0x72 | CC0 | [itch.io](https://0x72.itch.io/dungeontileset-ii) |
| Medieval Warrior Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/medieval-warrior-pack-2) |
| Martial Hero Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/martial-hero) |
| RPG GUI Construction Kit v1.0 | Lamoot | CC-BY 3.0 | [OpenGameArt](https://opengameart.org/content/rpg-gui-construction-kit-v10) |
| Golden UI | Buch | CC0 | [OpenGameArt](https://opengameart.org/content/golden-ui) |
## License
[MIT](LICENSE) - Copyright (c) 2026 Avalon Reset.
SEO engine code is derived from Daniel Agrici's open-source SEO skill suite and
used under the MIT license. SEO Dungeon is independent and runs through local
terminal-agent workflows selected in the app.