prompt-to-romhack

Prompt to Romhack Plugin

This repository packages a shared agent workflow for Pokemon Red, Blue, and Yellow romhacks. It provides:

• A shared skill for romhack editing and verification.
• A bootstrap CLI that clones pret/pokered, pret/pokeyellow, or a fork.
• Pinned RGBDS 1.0.1 bootstrap support under the ignored vendor/rgbds/ cache.
• Node helper scripts for build, static audits, headless smoke tests, browser preview, live RAM reads/writes, screenshots, and ROM-diff application.
• Romhack docs copied into each prepared workspace.

Quick Start

From this plugin repo:

node scripts/prompt-to-romhack.mjs setup --game red --dir ./pokered
node scripts/prompt-to-romhack.mjs setup --game yellow --dir ./pokeyellow

For a fork:

node scripts/prompt-to-romhack.mjs setup \
  --game red \
  --repo https://github.com/owner/pokered.git \
  --branch my-branch \
  --dir ./my-hack

Then:

cd ./pokered
node scripts/prompt_to_romhack.mjs doctor
node scripts/prompt_to_romhack.mjs preview --rom red --allow-missing-logo

For real visual review, generate a custom non-official title logo into web/romhack-preview/assets/ and pass it with --logo instead of using --allow-missing-logo.

What Gets Installed Into The Clone

The bootstrap copies only the workflow layer:

• scripts/prompt_to_romhack.mjs
• scripts/romhack_catalog.mjs
• scripts/romhack_battle.mjs
• scripts/romhack_scripts.mjs
• scripts/headless/runner.cjs
• web/romhack-preview/
• docs/prompt-to-romhack.md
• docs/romhack/
• .codex/skills/prompt-to-romhack/SKILL.md
• .claude/skills/prompt-to-romhack/SKILL.md
• .prompt-to-romhack/config.json

The disassembly source remains outside this plugin and comes from the configured clone URL.

RGBDS

pokered and pokeyellow both document RGBDS 1.0.1 as their expected build toolchain. The plugin pins that version and downloads the official release asset for the current platform:

node scripts/prompt-to-romhack.mjs vendor-rgbds --workspace ./pokered

The workspace helper reads .prompt-to-romhack/config.json and passes the vendored prefix to make as RGBDS=/path/to/vendor/bin/.

RGBDS is MIT licensed. The release asset is not committed to this repo by default; it is downloaded into an ignored local cache and the downloader also stores the upstream LICENSE text beside the binaries. Redistributing a pre-populated vendor/rgbds/ cache should be possible under MIT terms as long as the RGBDS license text and copyright notice are included, but the current public-repo shape avoids shipping those binaries at all.

Redistribution Notes

This repository is MIT licensed. It intentionally does not include game ROMs, generated ROM outputs, or the pokered/pokeyellow disassembly checkouts. Local workspaces live under ignored directories such as test-workspaces/, and downloaded RGBDS binaries live under ignored vendor/rgbds/.

The bundled browser/headless emulator files under tools/prompt-to-romhack/web/romhack-preview/vendor/ are from binjgb, which is MIT licensed; see the adjacent LICENSE.binjgb.

Pokemon, Game Boy, and related names are used descriptively for compatibility with user-provided disassembly checkouts. This project is not affiliated with, endorsed by, or sponsored by Nintendo, Game Freak, Creatures, or The Pokemon Company.

Preview pages require a custom, non-official title logo by default. The helper warns in doctor when web/romhack-preview/assets/ has no generated image and fails in preview/serve before starting the webpage unless a logo is present or explicitly passed with --logo.

Local Plugin Installation

Codex Desktop

For a home-local Codex plugin install, link this repo under ~/plugins:

mkdir -p ~/plugins ~/.agents/plugins
ln -sfn /path/to/prompt-to-romhack ~/plugins/prompt-to-romhack

Then add the plugin entry to the plugins array in ~/.agents/plugins/marketplace.json. If the file does not exist yet, this is the minimal complete shape:

{
  "name": "local-dev",
  "interface": {
    "displayName": "Local Dev"
  },
  "plugins": [
    {
      "name": "prompt-to-romhack",
      "source": {
        "source": "local",
        "path": "./plugins/prompt-to-romhack"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Coding"
    }
  ]
}

Restart Codex Desktop or refresh the plugin list, then install or enable prompt-to-romhack from the local marketplace. The plugin root is the directory containing .codex-plugin/plugin.json; the shipped skill lives under skills/.

Claude

Claude plugins use their own manifest at .claude-plugin/plugin.json, while the skill and helper files stay shared at the repo root. For local development or one-off testing, run Claude with this plugin directory:

claude --plugin-dir /path/to/prompt-to-romhack