Skip to main content
plugin CX Codex

legends-seo-dungeon — Claude Code plugin: what it does, how to install

legends-seo-dungeon is a Claude Code plugin that turns technical and content SEO audits into a 16-bit dungeon crawler with demons representing website defects.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install legends-seo-dungeon@awesome-codex-plugins
Open on GitHub

What legends-seo-dungeon does

Legends SEO Dungeon wraps routine website diagnostics in a retro dungeon crawler interface. Enter a target domain alongside your project path, and the system categorizes discovered defects by severity. Pressing Attack triggers an agent turn via your local CLI to fix the underlying code or content defect directly on disk.

The system runs Daniel Agrici's Claude SEO engine version 2.2.5. It bundles 25 sub-skills, 18 portable sub-agents, and 53 Python modules covering technical SEO, schema validation, E-E-A-T reviews, and drift monitoring. Audits split across parallel specialist workers matching chosen hero difficulty profiles.

Running the engine requires Node.js 22.12 or newer, Python 3.10+, and a signed-in local runtime such as Codex or Claude Code. Initial configuration demands running python scripts/runtime.py setup in the repository root.

What it helps with

  • run technical website inspections across sitemaps and schema markup
  • audit content against E-E-A-T criteria and review competitor pages
  • dispatch local agent turns to repair issues in project files
  • track search performance drift and evaluate semantic clusters

Example prompts for the agent

  • Run a complete site inspection using /seo audit
  • Attack missing structured data and invalid schema issues
  • Review E-E-A-T signals and generate a content brief for the target domain

How to install legends-seo-dungeon

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install legends-seo-dungeon@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about legends-seo-dungeon

How to install legends-seo-dungeon in Claude Code?

Run both marketplace commands in succession: first /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install legends-seo-dungeon@awesome-codex-plugins.

What does legends-seo-dungeon do?

It translates technical SEO flaws into dungeon demons inside a browser screen, letting terminal CLI agents address each issue in local files.

What are the runtime prerequisites?

Your machine needs Git, Node.js 22.12 or newer, Python 3.10+, and an authenticated local CLI like Claude Code or Codex.

Source text

seo-dungeon · MIT
<p align="center">
  <a href="assets/banner.webp"><img src="assets/banner.webp" alt="legends-seo-dungeon: a playable seo audit where your agents fix the issues" width="100%"></a>
</p>

# Legends SEO Dungeon - Multi-Agent SEO Audit Game

[![CI](https://github.com/avalonreset/legends-seo-dungeon/actions/workflows/ci.yml/badge.svg)](https://github.com/avalonreset/legends-seo-dungeon/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.2.5-blue)](CHANGELOG.md)
[![Runtime](https://img.shields.io/badge/runtime-Codex%20%7C%20Claude%20%7C%20Gemini%20%7C%20Grok-2ea44f)](dungeon/)

[Project Home](https://seodungeon.com) | [Source](https://github.com/avalonreset/legends-seo-dungeon) | [Releases](https://github.com/avalonreset/legends-seo-dungeon/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.

<table>
<tr>
<td width="50%"><a href="screenshots/title-screen.png"><img src="screenshots/title-screen.png" alt="Legends SEO Dungeon title screen with character and runtime selection"></a><br><em>Pick a CLI, pick a warrior, enter a domain</em></td>
<td width="50%"><a href="screenshots/gate-scene-full.png"><img src="screenshots/gate-scene-full.png" alt="Gate scene showing quest continuation options"></a><br><em>Continue a previous quest or begin a new one</em></td>
</tr>
<tr>
<td width="50%"><a href="screenshots/summoning-scene.png"><img src="screenshots/summoning-scene.png" alt="Legends SEO Dungeon audit loading hallway with the hero descending"></a><br><em>Run a fresh audit while the hero descends</em></td>
<td width="50%"><a href="screenshots/dungeon-hall.png"><img src="screenshots/dungeon-hall.png" alt="Dungeon hall showing SEO issue demons sorted by severity"></a><br><em>Browse SEO demons sorted by severity</em></td>
</tr>
<tr>
<td width="50%"><a href="screenshots/battle-scene.png"><img src="screenshots/battle-scene.png" alt="Turn-based battle scene with real-time Guild Ledger"></a><br><em>Battle demons with agent-powered fixes</em></td>
<td width="50%"><a href="assets/social-preview.png"><img src="assets/social-preview.png" alt="Legends SEO Dungeon social preview key art"></a><br><em>Share-ready Legends key art</em></td>
</tr>
</table>

## 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](https://github.com/AgriciDaniel/claude-seo),
MIT licensed. The engine pin and local adaptations are documented in
[the upstream audit](docs/UPSTREAM-SEO-AUDIT-2026-09-06.md).
See [third-party notices](THIRD-PARTY-NOTICES.md) and the
[original MIT license](LICENSE-CLAUDE-SEO).

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.

| 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.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](docs/RUNTIMES.md).

### Prepare the SEO Engine

From the extracted source folder:

```bash
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)

```powershell
# Windows
.\install.ps1
```

```bash
# macOS/Linux
bash install.sh
```

### Run The Game

```bash
cd dungeon
npm ci
npm start
```

Open [http://localhost:3002](http://localhost:3002). The bridge server starts on
port `3003`.

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`.

### 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:

```powershell
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:

```powershell
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:

```powershell
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:

| 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_CODEX_TRANSPORT` | `app-server` | Set to `exec` to use the older `codex exec --json` transport |
| `SEO_DUNGEON_CODEX_DANGEROUS_BYPASS` | unset | Set to `1` to force Codex YOLO mode from the bridge when no UI setting is provided |
| `SEO_DUNGEON_CODEX_BYPASS` | unset | Short alias for `SEO_DUNGEON_CODEX_DANGEROUS_BYPASS` |
| `SEO_DUNGEON_SESSION_LOG` | `.logs/session-events.jsonl` from `npm start` | Local bounded remote session ledger; set to `0` to disable |
| `SEO_DUNGEON_CLAUDE_CLI` | `claude` | Claude Code executable override |
| `SEO_DUNGEON_GEMINI_CLI` | `gemini` | Gemini CLI executable override |
| `SEO_DUNGEON_GROK_CLI` | official installed Grok | Grok executable override; see [runtime setup](docs/RUNTIMES.md) |
| `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.

### 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:

```bash
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

| Command | What it does |
|---------|-------------|
| `/seo audit <url>` | Full website audit |
| `/seo page <url>` | Deep single-page analysis |
| `/seo technical <url>` | Technical SEO audit |
| `/seo content <url>` | E-E-A-T and content quality |
| `/seo content-brief <topic or url>` | Detailed SEO content brief |
| `/seo schema <url>` | Schema.org detection and generation |
| `/seo sitemap <url>` | XML sitemap analysis or generation |
| `/seo images <url>` | Image SEO analysis |
| `/seo geo <url>` | AI search readiness |
| `/seo plan <type>` | Strategic SEO planning |
| `/seo flow [stage] [url|topic]` | FLOW framework prompts |
| `/seo cluster <keyword>` | Semantic clustering |
| `/seo sxo <url>` | Search experience optimization |
| `/seo drift baseline <url>` | Capture drift baseline |
| `/seo drift compare <url>` | Compare against drift baseline |
| `/seo ecommerce <url>` | E-commerce SEO |
| `/seo programmatic [url]` | Programmatic SEO |
| `/seo competitor-pages [url]` | Competitor comparison pages |
| `/seo local <url>` | Local SEO |
| `/seo maps [cmd] [args]` | Maps intelligence |
| `/seo hreflang <url>` | International SEO |
| `/seo google [cmd] [url]` | Google SEO APIs |
| `/seo backlinks <url>` | Backlink analysis |
| `/seo dataforseo [cmd]` | DataForSEO extension |
| `/seo firecrawl [cmd] <url>` | Firecrawl extension |
| `/seo image-gen [use-case]` | SEO image generation planning extension |

## Architecture

```text
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

| 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, Gemini, or Grok 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`, `SEO_DUNGEON_GEMINI_CLI`, or `SEO_DUNGEON_GROK_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 <url>` before `/seo drift compare <url>`. |

## 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 SEO skill suite and used under
the MIT license. Legends SEO Dungeon is an independent
Codex-default workflow with portable skill files.

© Avalon Reset · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for SEO and GEO →

From the same set391

The whole set →
shots Renders App Store screenshots and icons from the code already in your repo, then handles locale translation and ASO copy edits without leaving the agent. CX Codex ★ 1,596repo stars serply Teaches your coding agent to fetch Google search, Maps, academic papers, and Reddit discussions or scrape pages to Markdown via Serply. CX Codex ★ 1,596repo stars sendsets sendsets is a Claude Code and Codex plugin for managing cold email through Sendsets. It connects mailboxes, builds outbound sequences, launches campaigns, and handles replies through MCP. CX Codex ★ 1,596repo stars sendpaper sendpaper lets an agent order real postcards and letters to US addresses, showing a print preview and asking before any payment goes through. CX Codex ★ 1,596repo stars self-starter The self-starter plugin for Claude Code and Codex monitors plain-language event conditions in the background and resumes a task in the conversation when one is met. CX Codex ★ 1,596repo stars sectionsight sectionsight — a plugin for Claude Code and Codex that wires up cookieless analytics with per-section time-on-page tracking. It then runs a headless browser to prove the privacy claims hold. CX Codex ★ 1,596repo stars just-scrape just-scrape is a Claude Code plugin for web scraping, crawling, and structured JSON extraction through the ScrapeGraph AI API. It supports site monitoring and page content extraction. CX Codex ★ 1,596repo stars rust-reverse-engineering The rust-reverse-engineering plugin inspects compiled Rust binaries and libraries, tracing symbols, likely crate boundaries, and FFI paths. Use it to review your own builds or conduct authorized analysis. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open