SEO Dungeon Documentation: Install, Architecture, and the v2.2 SEO Suite

What is SEO Dungeon?

SEO Dungeon is an open-source local AI SEO audit app. It turns full-site audits into 16-bit boss battles. Every SEO issue becomes a fightable problem, and every accepted fix stays as a reviewable edit in your working tree. The v2.2 suite ships with 25 installed SEO engine skills, an 18-agent roster, and support for up to 15 parallel subagents during a full audit. MIT licensed.

The game is an optional gamified interface. Everything the dungeon does is also reachable from compatible terminal-agent workflows through commands like /seo audit, /seo technical, or /seo schema. Codex CLI is the packaged default runtime; Claude Code and Gemini CLI are optional local runtime choices.

Architecture

The dungeon has three processes that talk to each other: the browser game (Phaser.js + Vite) on port 3002 by default, a small bridge server on port 3003 by default, and the selected local CLI runtime running on your machine.

Browser (Phaser.js)
    ↓ WebSocket
Bridge Server (:3003)
    ↓ spawn
Codex CLI (default)
Claude Code / Gemini CLI (optional)
    ↓
SEO Skills (25) + Agents (18)
    ↓
Your project files (read + edit)

The bridge server is the only thing that spawns local CLI processes. It receives commands from the Phaser front-end over WebSocket. It shells out to Codex by default, or to Claude Code/Gemini CLI when selected. Results stream back to the browser in real time, and every tool call and file edit appears in the Guild Ledger.

Install

Requires Node.js 22+ for the dungeon app, Python 3.10+, Git, and at least one supported local CLI runtime installed and authenticated. Codex is the packaged default. The installer copies the v2.2 SEO skill suite and agent profiles into the matching local config.

# 1. Clone the repo
git clone https://github.com/avalonreset/seo-dungeon.git
cd seo-dungeon

# 2. Install the SEO skill suite
#    (copies skills and agent profiles into your local runtime config)
.\install.ps1          # Windows
bash install.sh         # macOS / Linux

# 3. Start the dungeon front-end
cd dungeon
npm install
npm run dev             # app: http://localhost:3002
                        # bridge: ws://127.0.0.1:3003

After the installer finishes, open your supported local CLI in any project directory and type /seo audit to kick off a full audit without the game. To play the game, start the dev server and open the URL it prints.

For deeper setup notes see the README, recent changes in the CHANGELOG, and contribution guidelines in CONTRIBUTING.

Character classes

Your class selects the depth and speed profile for the chosen local runtime. Codex is the default runtime; Claude Code maps these classes to Opus, Sonnet, and Haiku when selected.

Combat loop

Each dungeon floor is one page of your site. Each demon is one discovered SEO issue. In battle you have four actions:

• Attack. You type a prompt describing what you want the local agent to do about this issue. The selected demon's severity, category, URL, file, and selector travel with your prompt as a structured focus header. Polite directives become real code edits; questions get answered without triggering edits. You can Attack as many times as you want, since real fixes often need multiple prompts. The Guild Ledger streams every tool call, file read, and edit live on the right.
• Vanquish. Your judgment call that the demon is handled. Marks the issue defeated in your quest log. You decide when the fight is done, not the machine.
• Defend. Flavor action. Adds animation theater without changing code.
• Flee. Skip this demon and return to the Dungeon Hall. You can come back and fight it later.

Outside of battle the Guild Ledger becomes a plain pass-through to the selected local CLI, so you can ask general project questions with no SEO scope applied. Git commits are not automatic. Every code edit stays in your working tree so you review and commit on your own cadence.

v2.2 SEO skill suite

The installed v2.2 suite exposes 25 SEO engine skills and extension mirrors. Full audits can delegate to up to 15 parallel subagents from the 18-agent roster. Individual commands can also run directly from compatible terminal-agent workflows.

Using the skills without the game

The game is optional. The same SEO routes can be called directly from a compatible local CLI:

codex
> /seo audit https://yoursite.com
> /seo technical yoursite.com
> /seo schema yoursite.com --generate

The CLI mode is what you want for CI pipelines, headless runs, or repeated audits on a schedule. The game exists for a more tactile, exploratory experience when you want to walk through findings visually.

FAQ