convez.ai
Agente
avalonreset

seo-dungeon

avalonreset/seo-dungeon

Ver no GitHub
BomPluginScore · de 0 a 100

Gamified AI SEO audit app that turns website issues into 16-bit dungeon battles for local Codex, Claude, and Gemini CLI workflows.

Instalação

$npx convez-ai avalonreset/seo-dungeon

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 5 dias
Versão
v2.2.7
Issues abertas
2
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

SEO Dungeon - AI SEO Audits as Dungeon Battles

CI License: MIT Version Runtime

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 & Key Art

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. Arm YOLO Mode so Codex 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.

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.

Full audits are treated as multi-agent work by default. 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.

AreaCoverage
AuditFull-site audits, page audits, technical SEO, schema, sitemap, image SEO, hardened URL safety
ContentE-E-A-T, content briefs, semantic clustering, SXO, competitor pages, QRG-aligned quality gates
GrowthLocal SEO, maps intelligence, backlinks, e-commerce, programmatic SEO
MonitoringSEO drift baselines and comparisons
DataGoogle SEO APIs, DataForSEO, Firecrawl, Ahrefs, Bing Webmaster, Profound, SE Ranking, Unlighthouse
AssetsSEO image generation planning through the optional Banana/Gemini extension mirror
FrameworkFLOW 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

# Windows
.\install.ps1
# 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

cd dungeon
npm install
npm run dev

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.

Runtime environment:

VariableDefaultPurpose
SEO_DUNGEON_RUNTIMEcodexBridge fallback runtime when the UI does not send one
SEO_DUNGEON_CODEX_CLIcodexCodex executable override
SEO_DUNGEON_CODEX_DANGEROUS_BYPASSunsetSet to 1 to force Codex YOLO mode from the bridge when no UI setting is provided
SEO_DUNGEON_CODEX_BYPASSunsetShort alias for SEO_DUNGEON_CODEX_DANGEROUS_BYPASS
SEO_DUNGEON_CLAUDE_CLIclaudeClaude Code executable override
SEO_DUNGEON_GEMINI_CLIgeminiGemini CLI executable override
SEO_DUNGEON_CODEX_MODELCodex defaultOptional Codex model override
SEO_DUNGEON_CODEX_EFFORT_DEEPxhighCodex Warrior effort
SEO_DUNGEON_CODEX_EFFORT_BALANCEDhighCodex Samurai effort
SEO_DUNGEON_CODEX_EFFORT_FASTmediumCodex Knight effort
SEO_DUNGEON_CLAUDE_MODEL_DEEPopusClaude Warrior model alias
SEO_DUNGEON_CLAUDE_MODEL_BALANCEDsonnetClaude Samurai model alias
SEO_DUNGEON_CLAUDE_MODEL_FASThaikuClaude Knight model alias
SEO_DUNGEON_GEMINI_MODEL_DEEPproGemini Warrior model alias
SEO_DUNGEON_GEMINI_MODEL_BALANCEDflashGemini Samurai model alias
SEO_DUNGEON_GEMINI_MODEL_FASTflash-liteGemini Knight model alias
GEMINI_API_KEYunsetRequired 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 acceptEditsClaude CLI argument template
SEO_DUNGEON_GEMINI_ARGS--prompt {{prompt}} --output-format text --approval-mode auto_editGemini 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

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

Commands

CommandWhat 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] [urltopic]`
/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

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

ProblemFix
"The dungeon is unreachable"Bridge server is not running. Run npm run server in dungeon/.
Skills not found by CodexRun install.ps1 or install.sh from the repo root.
Codex, Claude, or Gemini fails to spawnConfirm 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 timeNormal for first full-site audits. Use cached audits when available.
Google API commands failRun /seo google for setup instructions.
Drift baseline not foundRun /seo drift baseline <url> before /seo drift compare <url>.

Asset Credits

AssetCreatorLicenseSource
DungeonTileset II0x72CC0itch.io
Medieval Warrior PackLuizMeloFree for personal and commercial useitch.io
Martial Hero PackLuizMeloFree for personal and commercial useitch.io
RPG GUI Construction Kit v1.0LamootCC-BY 3.0OpenGameArt
Golden UIBuchCC0OpenGameArt

License

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

Ver o original no GitHub

Bom para

Relacionados