SEO Dungeon - Gamified SEO Audit Tool for Claude Code

Most SEO audit tools hand you a spreadsheet and wish you luck. SEO Dungeon turns every issue into a demon you can fight, and every fix into a real commit to your codebase. Built on Claude SEO v1.9.0 with 23 AI-powered skills, 17 parallel subagents, and a 16-bit dungeon crawler interface that makes SEO audits something you actually want to do.

Screenshots

Pick your warrior, enter a domain, seal your fate	Continue a previous quest or begin a new one
Browse SEO demons sorted by severity	Battle demons with AI-powered code fixes

Table of Contents

• How It Works
• What's New in v1.9.0
• Game Features
• SEO Engine (23 Skills)
• Quick Start
• Character Classes
• SEO Commands
• Extensions
• Architecture
• Tech Stack
• Troubleshooting
• Asset Credits
• Contributing
• License

How It Works

1. Choose your warrior. Warrior (Opus), Samurai (Sonnet), or Knight (Haiku). Each maps to a Claude model with different analysis depth and speed.
2. Enter a domain and project path. Point the dungeon at any website and its source code directory.
3. Descend into the dungeon. Claude SEO runs a full audit with up to 17 parallel subagents, discovering issues as dungeon demons.
4. Explore the Dungeon Hall. Browse discovered SEO issues sorted by severity. Critical issues are deadly bosses. Info-level issues are goblins.
5. Battle demons. Turn-based combat with four actions:
   • Attack - Prompt Claude directly with what you want it to do about this issue. Claude streams its work into the Guild Ledger on the right and can edit your project files.
   • Vanquish - Declare the demon slain. You decide when the issue has been handled enough to mark it defeated in your catalog.
   • Defend - Strike a defensive stance. Mostly for flavor.
   • Flee - Skip this demon and return to the dungeon. You can come back and fight it later.
6. Collect loot. Earn XP and rewards for every demon slain.

The real work happens when you choose Attack. You type a prompt describing what you want done about this issue, Claude reads your actual project files, and streams its work into the Guild Ledger on the right - tools it's calling, files it's reading, changes it's making. You can Attack as many times as you want. Real SEO fixes often take multiple prompts, back-and-forth clarification, and a little patience. Vanquish is the button you press when you've looked at what Claude did and you're satisfied the issue is handled. It's your call, not the machine's.

What's New in v1.9.0

This release brings the SEO engine from v1.6.1 to v1.9.0, adding 6 major new skill categories and 30+ commits of game improvements.

New SEO Skills

Game Improvements

• Guild Ledger Terminal - Type prompts directly to Claude during gameplay
• Persistent Interactive Sessions - Claude maintains context across battle actions with token tracking
• RPG Narrator - Haiku narrates attack results in the battle log with cinematic flair
• Smart Scroll - Guild Ledger respects your scroll position during updates
• Double-Escape Cancel - Press Escape twice to cancel any active Claude operation
• 18 bug fixes across battle log, animations, scroll behavior, and loading states

Game Features

Combat and Gameplay

• Turn-based combat atmosphere with HP bars, attack animations, and an RPG narrator
• Attack sends your message to Claude with the selected demon as a structured focus header - severity, category, URL, file, selector all travel with every turn. Claude reads your intent naturally, so polite directives work as fixes and questions get answered without triggering edits.
• Vanquish is your judgment call. You decide when the issue has been handled enough to mark it defeated.
• Neutral chat outside battle - the Guild Ledger input becomes a plain pass-through to claude -p when no demon is selected, so you can ask anything with no SEO scope applied.
• Quest caching via localStorage so you can resume audits without re-running them
• Dynamic difficulty where demon HP scales with issue severity (critical = boss fight, info = goblin)

Audio and Visuals

• 25+ procedural sound effects synthesized via Web Audio API (zero audio files shipped)
• Three animated character classes with idle, run, attack, hit, and death sprite animations
• 13-demon animated roster from 0x72 DungeonTileset II - every demon has a real 4-frame idle animation, tier-ranked across Critical / High / Medium / Low / Info. Themed assignment matches SEO category to demon archetype (schema → enforcers, broken links → skeletons, performance → imps, stale content → zombies)
• Cinematic silhouette state for undefeated demons with tier-escalating aura (critical adds embers + halo)
• Painterly defeated state - blood-drain tint, slump rotation, layered pool with drip droplets, killing-blow slashes, spatter ring, corner DEFEATED stamp. Every corpse freezes on a deterministic random idle frame so no two look the same.
• Final victory sequence - "The Hall Is Still" - four-phase Dark-Souls-inspired finale when every demon falls. Parchment stat ledger (tier counts, XP, active quest time), name awarded by total XP, then SEEK ANOTHER or REMAIN.
• Visibility-aware quest timer - TIME IN THE DARK pauses when the tab is hidden
• 4K rendering with DPR-aware canvas scaling (3x minimum) for crisp text on high-DPI displays
• Atmospheric effects including dust motes, embers, ground fog, blood drip transitions, and procedural brick walls
• Cinematic transitions with fade-to-black sequences for descending and ascending

Guild Ledger

• Real-time activity log showing every tool call, agent spawn, file read, and decision Claude makes
• 14 icon categories with per-line color coding (tools, agents, fetches, errors, completions)
• Typewriter animation with configurable speed and idle state detection
• Interactive terminal mode for typing prompts directly to Claude mid-gameplay

SEO Engine (23 Skills)

The full Claude SEO v1.9.0 engine is bundled, giving you 23 specialized skills that work both through the game and directly from the Claude Code CLI.

Core Analysis (14 skills)

New in v1.9.0 (6 skills)

Extensions (3 optional add-ons)

Quick Start

Prerequisites

• Node.js 18+
• Python 3.10+ (for SEO analysis scripts)
• Claude Code installed and authenticated
• Git

1. Clone and install

git clone https://github.com/avalonreset/seo-dungeon.git
cd seo-dungeon

Install the Claude SEO skill suite (copies 23 skills + 17 agents to your Claude Code config):

# Windows
.\install.ps1

# macOS/Linux
bash install.sh

2. Start the dungeon

cd dungeon
npm install
npm run dev

Open http://localhost:3000. The bridge server starts on port 3001 automatically.

Windows users: The first time the dungeon runs an audit, Windows Defender Firewall may prompt to allow claude.exe network access. Click Allow. Without this, audits will hang silently because Claude cannot reach Anthropic's API. This prompt only appears once per install.

First audit takes 5-10 minutes. The /seo audit skill runs up to 15 subagents in parallel and fans out tool calls across many pages. The progress bar shows 0% during tool-call phases because nothing text-based is streaming yet. This is normal. Subsequent cached audits are near-instant.

3. Production build (recommended for recording)

cd dungeon
npm run build
npm run server          # Terminal 1: Bridge server
npx serve dist -l 3000 -s  # Terminal 2: Static build

Dev Shortcuts

• ?battle=1 - Skip straight to battle scene with the first cached demon
• ?battle=1&issue=2 - Jump to a specific issue index

Character Classes

Each character maps to a Claude model. Your choice affects analysis depth, fix quality, and combat speed.

SEO Commands

The skills work directly from the Claude Code CLI without the game interface:

Extensions

DataForSEO (live keyword and SERP data)

Adds real-time search volume, keyword difficulty, SERP analysis, backlink data, and AI visibility tracking. Requires a DataForSEO account (free tier available).

# Windows
powershell -File extensions\dataforseo\install.ps1

# macOS/Linux
bash extensions/dataforseo/install.sh

Firecrawl (full-site crawling)

Adds site-wide URL discovery and JavaScript-rendered crawling via Firecrawl MCP. Useful when WebFetch can't reach all pages.

# Windows
powershell -File extensions\firecrawl\install.ps1

# macOS/Linux
bash extensions/firecrawl/install.sh

Banana (AI image generation)

Adds AI-generated image creation for SEO assets (OG images, social previews, blog headers) via Gemini Nano Banana models.

# Windows
powershell -File extensions\banana\install.ps1

# macOS/Linux
bash extensions/banana/install.sh

Architecture

The game and the SEO engine are completely separate layers connected by a WebSocket bridge.

Browser (Phaser.js)  <-->  WebSocket (3001)  <-->  Bridge Server  <-->  Claude Code CLI
                                                                          |
                                                                    23 SEO Skills
                                                                    17 Subagents
                                                                    42 Python Scripts
                                                                    3 Extensions

1. The Phaser game sends commands (audit, fix, commit, narrate) over WebSocket
2. The bridge server spawns Claude Code CLI processes with the selected model
3. Claude Code loads SEO skills from ~/.claude/skills/ and runs the analysis
4. Results stream back through WebSocket to the game in real time
5. The Guild Ledger displays every tool call, file read, and decision Claude makes

seo-dungeon/
  dungeon/                         # Game application (Phaser.js)
    server/index.js                # WebSocket bridge to Claude Code
    src/scenes/                    # 8 game scenes (Boot, Gate, Summoning, Hall, Battle, Victory...)
    src/utils/                     # Sound manager, WebSocket client, colors, particles
    assets/luizmelo/               # Character sprite sheets (Warrior, Samurai, Knight)
  skills/                          # Claude SEO v1.9.0 (23 skills)
  agents/                          # 17 subagents for parallel analysis
  scripts/                         # 42 Python scripts (29 SEO + 13 visual audit)
  extensions/                      # DataForSEO + Firecrawl + Banana

Tech Stack

Troubleshooting

Asset Credits

All assets used under their respective open licenses. CC-BY attribution is rendered in the UI credits card and in dungeon/public/assets/ATTRIBUTION.md. See THIRD-PARTY-NOTICES.md for full attribution including the Claude SEO engine (MIT).

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - Copyright (c) 2026 Avalon Reset

SEO engine based on Claude SEO by Daniel Agrici (MIT).

Cost expectations

Every Attack in battle and every /seo audit run spawns a Claude Code process that calls the Anthropic API under your own credentials. This consumes real tokens against your plan. A full-site audit with 15 parallel subagents is not a cheap call.

• Warrior (Opus) is the deepest and most expensive. Reserve for high-stakes audits. Expect several minutes per full audit and meaningful token usage.
• Samurai (Sonnet) is the recommended default. Balanced cost and depth.
• Knight (Haiku) is the fastest and cheapest. Good for regular use, iteration, and large backlogs of small issues.

Users on Claude Pro may hit the 5-hour usage cap mid-audit if they run multiple Opus-class audits back-to-back. Not a bug; that is how the subscription plan works. If you are doing heavy audit work, consider Max or API credits.

Disclaimer

SEO Dungeon is an independent, open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic.

"Claude," "Claude Code," "Opus," "Sonnet," and "Haiku" are trademarks of Anthropic and are referenced here descriptively to identify the underlying models the tool spawns. No endorsement or partnership is implied. Users provide their own Claude Code authentication (subscription or API credits) and are responsible for their own token usage under their agreement with Anthropic.

Use of the Anthropic API through Claude Code is subject to Anthropic's Usage Policies and any applicable terms of service. This project does not proxy, redistribute, or resell access to Anthropic services.