legends-seo-dungeon

Legends SEO Dungeon - Multi-Agent SEO Audit Game

Project Home | Source | Releases

Legends 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 local project.

This Legends build carries the public Claude SEO v2.2.5 engine refresh while keeping the browser game Codex-default. The app can also spawn local Claude Code, Gemini CLI, or Grok CLI when selected, and the underlying skills, agents, scripts, and references remain plain files for compatible terminal agents.

The Dungeon version follows the bundled public Claude SEO release: 2.2.5. Dungeon-specific fixes within that engine version are identified by Git commits.

Screenshots & Key Art

Game screenshots use fictional example.com data.

How It Works

1. Choose a local CLI runtime: Codex, Claude Code, Gemini CLI, or Grok CLI. Codex is selected by default.
2. Choose a character profile. Codex maps Warrior/Samurai/Knight to xhigh, high, and medium; Claude maps them to Opus/Sonnet/Haiku; Gemini maps them to Pro/Flash/Flash Lite. Grok uses your configured model with high/high/medium reasoning effort.
3. Enter a domain and local project path.
4. For Codex, arm YOLO Mode so it runs with --dangerously-bypass-approvals-and-sandbox.
5. Run a full /seo audit through the selected local CLI.
6. Review SEO issues as dungeon demons sorted by severity.
7. Use Attack to send a scoped agent turn for the selected issue.
8. Queue or steer follow-up prompts through the Guild Ledger while work is running; queued prompts release when the active turn settles.
9. 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. YOLO Mode is deliberately not remembered; it must be armed on each fresh app launch.

Inside the browser game, the actual work happens through the selected local CLI in your local environment. 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. Outside the game, compatible terminal agents can use the same skills/, agents/, and scripts/ directly.

SEO Engine

Source: Daniel Agrici's public Claude SEO, MIT licensed. The engine pin and local adaptations are documented in the upstream audit. See third-party notices and the original MIT license.

From the repository, check readiness with python scripts/runtime.py doctor --json. Prepare the isolated engine with python scripts/runtime.py setup. Run a tool with python scripts/runtime.py run <script.py> [arguments]. These are the cross-platform equivalents of upstream's claude-seo launcher. The Codex installers bind installed prompts to the installed runtime's absolute path.

The bundled public Claude SEO v2.2.5 engine (plus published maintenance) has 25 sub-skills (21 core + 1 orchestrator + 1 framework integration + 2 extension mirrors), 18 portable sub-agents, 23 Codex TOML profiles, and 53 upstream Python modules plus 2 Dungeon API adapters.

Full audits are treated as multi-agent work by default. Legends SEO Dungeon asks the selected runtime to fan out specialist audit workers in parallel whenever that runtime supports it, and delegated workers inherit the selected strength profile: Warrior stays extra-high, Samurai stays high, and Knight stays medium.

Quick Start

Prerequisites

• Node.js 22.12+
• Python 3.10+
• Git
• At least one supported local CLI installed and signed in: Codex (default), Claude Code, Gemini CLI, or xAI Grok CLI. See runtime setup.

Prepare the SEO Engine

From the extracted source folder:

python scripts/runtime.py setup

This installs the engine in its own environment. Some integrations need their own credentials; they are optional for starting the game.

Install Codex Skills (Optional for the Game)

# Windows
.\install.ps1

# macOS/Linux
bash install.sh

Run The Game

cd dungeon
npm ci
npm start

Open http://localhost:3002. The bridge server starts on port 3003.

For live development visibility, keep a second terminal open:

cd dungeon
npm run logs

The bridge mirrors startup, runtime selection, CLI executable paths, child exits, and errors to dungeon/.logs/bridge.log.

Codex Remote Control

When the app and bridge are running, Codex can use the local helper to drive the browser-owned setup and Guild Ledger paths:

cd dungeon
npm run remote -- status --json
npm run remote -- event --wait --timeout 30000 --kind ui-intent --action launch --domain example.com --project /path/to/your/project --runtime codex --profile fast --character knight --dangerous-bypass --meta source=codex-helper
npm run remote -- send --wait --timeout 120000 --project /path/to/your/project --profile fast --dangerous-bypass -- "/seo page https://example.com"
npm run remote -- watch --kind ledger-result --filter-source guild-ledger --count 1 --timeout 30000

The helper talks to the localhost WebSocket bridge. It does not automate the Codex desktop composer; the browser applies ui-intent setup/start actions and the Guild Ledger claims send commands through the normal Codex app-server runtime. event --wait waits for a matching browser ui-result; watch remains available for passive session observation.

To record a browser-side walkthrough of the structured intent path:

cd dungeon
npm run demo:remote-intents -- --keep-open-ms 100

The recorder uses isolated dynamic ports, drives launch, Gate resume, Hall issue selection, Battle attack, queue steer/stop/clear, and remote vanquish through npm run remote -- event --wait, then writes a WebM, screenshot, manifest, session log, ledger transcript, and CLI result receipts under dungeon/.logs/remote-intents-demo/<timestamp>/. This is the fast browser proof lane for recursive testing before a full desktop capture.

To record the same structured intent path as a full Windows desktop capture:

cd dungeon
npm run proof:desktop-intents -- --fake-codex --keep-open-ms 100 --allow-foreground-mismatch

This writes an MP4 at the current desktop resolution, early and late frames, browser screenshot, manifest, session log, ledger transcript, and CLI receipts under dungeon/.logs/desktop-intents-proof/<timestamp>/. The default fake-Codex mode is for recursive smoke testing. Release/demo proof should use --real-codex --position-codex-window, Codex visible on the left, Legends SEO Dungeon visible on the right, and no --allow-foreground-mismatch.

Runtime environment:

Set a model variable to default, auto, or none to let that CLI use its own configured default model.

Project API Credentials

Legends SEO Dungeon treats the selected project folder as the credential source for audit integrations. Add a .env or .env.local file at that project root when you want live data:

DATAFORSEO_USERNAME=your-login
DATAFORSEO_PASSWORD=your-password
FIRECRAWL_API_KEY=fc-your-api-key
GOOGLE_API_KEY=your-google-api-key
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
GSC_SITE_URL=https://example.com/
GA4_PROPERTY_ID=123456789

The bridge forwards known SEO-related keys from the project .env into the selected local CLI. DataForSEO, Firecrawl, and Google workflows should use those credentials directly first. MCP servers are optional adapters: if you already have one configured, an agent may use it quietly, but Legends SEO Dungeon does not require MCP setup for audits.

First audits can take 5-10 minutes because /seo audit fans out multiple specialist passes. Cached audits are much faster.

Portable Skill Use

Use AGENTS.md, skills/, agents/, and scripts/ as the source of truth. The skill frontmatter and Python helpers are intentionally portable, and all URL-fetching scripts keep the same SSRF protections across compatible runtimes.

Commands

Architecture

legends-seo-dungeon/
  dungeon/                         # Phaser game and WebSocket bridge
    server/index.js                # Local CLI game 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

Asset Credits

License

MIT - Copyright (c) 2026 Avalon Reset.

SEO engine code is derived from Daniel Agrici's SEO skill suite and used under the MIT license. Legends SEO Dungeon is an independent Codex-default workflow with portable skill files.