Ghostframe user guide

#1. What you need

#A Pokémon Red ROM file (required)

Ghostframe does not include, download or share the game. Use a ROM you dumped from your own cartridge.

• Supported version: Pokémon Red (USA, Europe), including the SGB-enhanced release, as a .gb file.
• Required fingerprint: SHA-1 ea9bcae617fdf159b045185467ae58b2e4a48b9a. Other revisions (Blue, Yellow, Japanese and other language versions, hacks) are rejected, because the game-memory reader is built for this exact build.
• Zip files: if your dump is in a .zip, extract the .gb file first. Ghostframe reads the .gb file directly.

To check the fingerprint yourself in PowerShell:

Get-FileHash -Algorithm SHA1 "C:\path\to\Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb"

#API keys (needed for AI runners)

You can explore without keys. The Heuristic bot runner and manual play are free and need neither key. Each AI runner needs only its own keys: Jev solo needs only Jev; Claude solo needs only Anthropic.

Treat keys like passwords. If you ever paste one somewhere public (or into a chat), rotate it in the provider's console.

#A computer

• Windows 10 or 11 (64-bit) for the desktop app. The source setup also works on macOS and Linux.
• About 1 GB free disk for the app, plus room for run history; a full run's data is a few MB.
• Any modern CPU. Each emulator uses about one core while running, and the league host runs one emulator per worker.
• Internet, only for the AI model calls.

#2. Setup option A: the desktop app (recommended)

#2.1 Install

1. Get Ghostframe Setup 0.1.0.exe: from whoever shares it with you, or build it yourself (see 3.8).
2. Run it. The installer isn't code-signed yet, so Windows SmartScreen may say "Windows protected your PC". Click More info → Run anyway.
3. Choose an install folder (the default is fine) and finish. Ghostframe appears in the Start menu.

#2.2 First launch: the setup screen

The first launch opens Setup. You can reopen it any time from File → Setup (ROM, API keys, data folder)….

Step 1: Choose your ROM. Under Game ROM, click Choose ROM file… and pick your .gb file.

• The app checks the fingerprint and shows ✓ Pokémon Red (USA, Europe).
• The ROM is read in place: never copied, modified or uploaded.
• If it says ✗ Unsupported, see Troubleshooting.

Step 2: Enter API keys. Under API keys, paste your Jev and/or Anthropic key and click Save keys.

• They're encrypted with Windows' own data protection (DPAPI), so only your Windows account can decrypt them.
• After saving, a key shows only as saved ✓; it's never displayed again. To change a key, paste the new one and save again.

Step 3: Pick a data folder. Under Data folder, keep the default or click Change…. The default is %APPDATA%\Ghostframe\data. This folder holds your run history, checkpoints and logs (see section 17). Choose another drive if you'll record many runs.

Step 4: Prepare and open. Click Prepare & open Ghostframe. The app plays the game's opening with a fixed script, saving save states (checkpoints) that categories and practice runs start from. Progress appears as a checklist:

• New-game checkpoints: bedroom, Pallet Town, Oak's Lab, starter in hand, rival battle (a few seconds).
• Stage checkpoints: after the rival, Route 1, Viridian City, the parcel, the Pokédex, Route 2, healed, trained, Viridian Forest, Pewter City, trained for Brock, Boulder Badge (about a minute).

This happens once per data folder; later launches skip it. If something fails, the button changes to Retry, and finished checkpoints are skipped. When it's done, the main window opens on Set up a run.

#2.3 Living with the app

• Closing the window during a run keeps the run going in the system tray. Click the tray icon to bring the window back.
• Quitting (tray menu → Quit, or Ctrl+Q) asks first if a run is active, then shuts down cleanly. Your history and checkpoints are always kept.
• Your computer stays yours. The game is driven through the emulator's own interface: Ghostframe never moves your mouse, presses keys or reads your screen.
• Access is local only. The app's internal server listens only on 127.0.0.1, on a random port, with a fresh secret token every launch.
• Useful menu items: File → Open data folder and File → Open backend log.

#2.4 Updating and uninstalling

• Update: run a newer installer over the old one. Your data folder and settings are untouched.
• Uninstall: Windows Settings → Apps → Ghostframe → Uninstall. The data folder is not deleted. Remove %APPDATA%\Ghostframe yourself if you want everything gone, including encrypted keys and settings.

#3. Setup option B: from source (developers)

Use this for development, on macOS or Linux, or to run the browser dashboard instead of the desktop window.

#3.1 Prerequisites

On Windows, run the commands below in Git Bash (installed with Git for Windows). They use Unix-style paths; PowerShell equivalents are noted where they differ.

#3.2 Get the code

git clone https://github.com/JohnGarrisonDev/ghostframe.git
cd ghostframe

#3.3 Put your ROM in place

mkdir -p roms
cp "/c/path/to/Pokemon - Red Version (USA, Europe) (SGB Enhanced).gb" roms/pokemon_red.gb

The file must be named roms/pokemon_red.gb, or point JEV_ROM_PATH at it. roms/*.gb is git-ignored, so it can never be committed by accident.

#3.4 Add your keys

cp .env.example .env

Edit .env and fill in:

JEV_API_KEY=your-jev-key
ANTHROPIC_API_KEY=your-anthropic-key
PLANNER_MODEL=claude-opus-5-5     # or claude-sonnet-5-5 (cheaper)

.env is git-ignored, and only the backend reads it; the browser never sees your keys.

#3.5 Install the backend and dashboard

cd backend
python -m venv .venv
.venv/Scripts/pip install -r requirements-dev.txt     # macOS/Linux: .venv/bin/pip
cd ../dashboard
npm install
npm run build                                          # builds into backend/static
cd ..

#3.6 Create the scenario checkpoints

Two scripted passes; the second takes about a minute:

cd backend
export JEV_DATA_DIR=../data JEV_ROM_PATH=../roms/pokemon_red.gb
.venv/Scripts/python -m app.tools.bootstrap    # new game, Pallet Town, Oak's Lab, starter, rival battle
.venv/Scripts/python -m app.tools.story        # 12 stages through Viridian Forest to the Boulder Badge
cd ..

PowerShell users: set variables with $env:JEV_DATA_DIR="../data" and so on, and use .venv\Scripts\python.

#3.7 Start it

Browser dashboard:

./restart.sh          # starts the server on http://127.0.0.1:8000 (logs: data/server.log)

Then open http://127.0.0.1:8000.

Desktop window from source:

cd electron
npm install
npm start             # uses backend/.venv and the repo's data/, roms/ and .env

#3.8 Building the desktop installer (optional)

cd electron
npm run dist          # dashboard build + PyInstaller backend + NSIS installer

The installer is written to electron/release/Ghostframe Setup 0.1.0.exe. The bundled backend is about 115 MB; it does not contain your ROM or keys.

#3.9 Running the tests

cd backend
.venv/Scripts/python -m pytest -q                         # fast suite (fake emulator), ~15 s
JEV_SLOW_TESTS=1 .venv/Scripts/python -m pytest -q -k boulder   # real ROM: scripted route to the badge, ~1 min

#4. Setup option C: Docker

For a headless server, for example a league host:

cp .env.example .env            # add keys
mkdir -p roms && cp /path/to/your.gb roms/pokemon_red.gb
docker compose up --build       # http://127.0.0.1:8000
docker compose exec jev-lab python -m app.tools.bootstrap
docker compose exec jev-lab python -m app.tools.story

• Isolation: the container binds to 127.0.0.1 only, mounts ./roms read-only, runs as a non-root user with a read-only root filesystem, and drops all capabilities.
• Resources: defaults to 1 CPU and 768 MB; change with JEV_CPUS and JEV_MEM.
• Data: stored in the jev-data volume. ROMs and keys are never copied into the image.

#5. Checking that everything works

1. Open Settings → About this install:
   • Game should show Pokémon Red (USA, Europe) with Verified.
   • Jev key and Anthropic key should show Set for the keys you added.
2. On the Run page, choose Free run → Starter in hand → Heuristic bot and press Start run. The game screen should move within a few seconds. This costs nothing.
3. Press Stop. The run appears on the Runs page.

If any step fails, see Troubleshooting.

#6. Your first run

The Run page opens on Set up a run. The switch at the top picks between:

• Ranked category: fixed rules, timed on the leaderboards, verified automatically. Best for "how fast can it go?".
• Free run: any start point, finish line and settings. Best for experiments and practice.

#A first ranked run (Any%)

1. Category: pick Any% — Boulder Badge, which goes from a new game to beating Brock.
2. Runner: pick Strategist + Jev: Claude plans, Jev makes every move. This is the strongest runner so far (about 1h50m–2h20m in-game, around $0.45–0.55 per run).
3. Build name: optional; it's shown on the leaderboard.
4. Press Start ranked run.

A full run takes roughly 7–10 minutes of real time, depending on model response times. In-game time is what counts; see Glossary.

#A first free run

1. Where does the run start? Pick any checkpoint, from New game to Pewter City.
2. Who plays? Pick a runner.
3. Finish line: pick a milestone (for example Received a starter Pokémon) or No finish line.
4. Advanced settings (optional):
   • decision and spending caps
   • what the AI can see
   • notes
   • a random start offset
   • type-matchup hints
5. Press Start run, or Create only to set it up and start later.

#7. The Run page

Good to know

• Leaving is safe. Closing the page or switching pages never stops a run, and the view restores when you come back.
• Forced decisions: when only one sensible option exists (say, advancing dialogue), the game code takes it automatically. These show as automatic and don't cost a model call. Tick show forced (code) decisions to see them.
• Save states: Restore jumps back; starting again from there creates a branch attempt. Auto-saves happen every 100 decisions by default.
• Finishing a ranked run shows a banner with your place, any new record or personal best, and the verification status.

#8. Leaderboards and ranked categories

#Categories

Rules every ranked run follows

• The AI sees only what a player could see.
• It uses the Pokémon action layer.
• Notes are read-only.
• The category's caps apply.

Each category has a ruleset id such as any_badge1@v1-1610c06f. Only runs under the same ruleset are ranked together.

#The Leaderboards page

• Achievements at the top show what you've unlocked; click Show all to see the locked ones.
• Category cards show the record, finished runs and attempts.
• The board:
  • Best per build or All runs, with Verified only as a filter.
  • Each row has ▶ Watch (replay), Download run, and Download build (the gear icon) to share.
  • Race the top N replays the best runs side by side.
  • Run this category starts a ranked attempt.

#9. Builds: making your own runner

A build is everything that decides how a runner plays. The Builds page is where you make, version and test them.

#Create a build

1. Click New build and start from a template (or Copy of the selected build).
2. Edit any section:
   • Runner, with the strategist model and effort and the Jev model.
   • Prompts: the strategist prompt, the Jev instructions, the Claude move-picking prompt (Claude solo only), the note-taking prompt (when notes are written), and fixed objectives (Jev solo). An edited tag marks changed prompts; Default resets one.
   • Strategist triggers: when to re-plan, re-plan every N decisions, the maximum calls per run, and whether to show the route ladder.
   • Notes: off, read, or read and add, plus which notebook.
   • Gameplay and limits: decision cap, spending cap, what to do when stuck, and type-matchup hints.
3. Click Review and save. The dialog shows every change, line by line for prompts.
   • On an existing build, Save as v2 (v3, …) keeps the history.
   • Fork as a new build starts a new name.

#Test it

• The Overview tab lists every course with your best ranked and practice times.
• Practice runs the course unranked under the same rules. Practice runs may add to the notebook.
• Race makes a ranked attempt; it's disabled if the category doesn't allow the runner type.

#Track it

• Versions: every version with its note, run count and best Any% time. Changes shows the diff from the version before.
• Compare: pick any other build or version to see setting differences and time deltas side by side.
• Download / Import: share a build as a .gfbuild.json file.
• Archive (box icon) moves a build to past experiments; its runs and times are kept. Tick Show past experiments to see them.

A build that uses notes must have a strategist: notes are given to the planner, so Jev solo can't use them.

#10. Runs, verification and sharing

The Runs page lists every attempt: build and version, category (or practice), outcome, in-game time, splits, AI decisions, cost and start time.

Row actions

• ▶ Watch opens the replay.
• Inspect shows the event log.
• Download run saves a shareable JSON file.
• Verify (shield icon) replays the run's recorded inputs in a separate hidden emulator and checks every split matches to the frame. It never disturbs a live run.
• Submit to leaderboard (trophy icon) appears on past runs that happened to follow a category's rules.

Top-bar actions

• Select and race: tick up to four runs and press Race.
• Import loads a run someone shared. It can be verified on your machine if you have the same starting checkpoint, which you will if you ran setup.
• CSV exports the table.

Verification states: Verified (frame-identical), Verifying…, Not reproduced, Unverified. Ranked runs are verified automatically when they finish.

#11. Watching replays and races

Replays are re-rendered from recorded inputs, so no video files are stored and every replay is exact.

• Open a replay with ▶ on any run (Runs, Leaderboards or League).
• Race up to four runs: use Race the top N, or tick runs on the Runs page.
• Controls:
  • Play / Pause.
  • Speed from 1× to 16×. The emulator tops out near 9×; above that, the clock waits so lanes stay in sync.
  • Click the timeline to jump. Split markers show on it. Jumping backwards restarts the replay and fast-forwards.
• Race lanes show each run at the same in-game time, with a finishing place (#1, #2…) and a finish flag.
• Highlights: splits (★ = best-ever segment), trainer battles, blackouts, long battles and stuck moments. Click one to jump to just before it.
• Commentary (optional): Add commentary makes one short Claude Sonnet call (about a cent) that turns the highlights into captions. It's saved, so you only pay once per run.
• Closing the replay deletes its temporary data; nothing is added to your history.

#12. Notes (lessons across runs)

The Notes page manages notebooks: short lessons a strategist reads at the start of a run.

• With notes set to read and add, Claude reflects after each run and adds or retires lessons. This costs one small Claude call.
• Ranked runs only read notes; practice and free runs can write them.
• Type a lesson in Add a lesson by hand and press Add. Press Retire on any that are wrong; show retired brings them back into view. Lessons can apply to a milestone, so they're shown only when relevant, or be general.

#13. Leagues: racing friends

A league is a shared Ghostframe server that runs everyone's builds under identical conditions.

#Join

1. Get the league address (for example http://192.168.1.20:8765) and a one-time invite code (GF-…) from the host.
2. Open League, choose I have an invite, enter both, and press Join. Ghostframe stores your player token in league.json in your data folder.

#Tabs

• Boards: best time per player (or all runs), filterable by season and to verified runs only. ▶ watches a run on your machine.
• Submit:
  1. Pick a category and one of your saved builds.
  2. Choose who pays: Use my own API keys sends your keys with that one submission. The league keeps them in memory for that run only, and never stores, logs or returns them. If the host offers it, pick The host pays.
  3. Press Submit to league.
• My submissions: queue position, status, time, cost, and the start seed once the run ends. Cancel works while a submission is waiting or running.
• Seasons: time-boxed boards with saved final standings.
• Achievements: what each player has unlocked.

#What's fair and what's private

• Hidden seeds: every submission gets a secret random start offset, so builds can't be tuned to one exact sequence. It's revealed when the run ends.
• Verification: every finished run is replayed.
• Your prompts stay private: other players see only your build's name and result. Even replays you download never include build settings.
• Your ROM never leaves your computer. Each machine uses its own copy.
• Plain http warning: if the league address starts with http:// and isn't on your own machine, the app warns you before sending keys. Only send keys over a network you trust, or ask the host to set up HTTPS.

Statuses: queued (#N in line) → running → done (reached the goal), did not finish (stopped by a limit), failed (something broke) or cancelled.

#14. Hosting a league

The host machine needs its own ROM and the prepared checkpoints (section 3.6, or the desktop setup).

#Start the server

From source:

cd backend
.venv/Scripts/python -m app.tools.league serve --host 0.0.0.0 --port 8765 --workers 2

With the installed app, from the install folder:

& "$env:LOCALAPPDATA\Programs\Ghostframe\resources\backend\jev-backend.exe" league serve --host 0.0.0.0 --port 8765

• Admin token: the first serve creates one and saves it to <data folder>/league-admin-token.txt. Keep it private: it's the host's admin key.
• Workers = how many runs can play at once. Each uses about one CPU core.
• Firewall: allow the port through Windows Firewall when it asks. For internet play, put the server behind HTTPS, for example with a reverse proxy such as Caddy, rather than exposing plain http.

#Invite players

.venv/Scripts/python -m app.tools.league invite "Misty"      # prints a one-time code
.venv/Scripts/python -m app.tools.league players             # list players

You can also do this from the app: League → I'm the host, enter the server address and the admin token, then use the Players tab.

#Run the league (Players tab, host only)

• Invite players; each code works once.
• Suspend or restore players. Suspending cancels their waiting runs and hides their times.
• Hide a run from the boards with a reason (box icon on a board row), and restore it later.
• Seasons: start one (name and length) and end it early if needed. Seasons also end on their own.
• Audit log: every invite, join, submission and moderation action.

#Options (environment variables or .env on the host)

If the server restarts, runs in progress are marked failed. Waiting runs that use players' own keys are also marked failed, because keys are never kept, so those players need to resubmit. Host-paid waiting runs resume.

#15. Settings

• Appearance: dark (default), light, or follow the system. The switch also sits at the bottom of the sidebar.
• Performance:
  • Playback speed: 0 = as fast as possible; 1 = real time, nice for watching live runs.
  • Video frames per second: smoother at a little more CPU; frames stream only while a window is open.
  • Auto-save every N decisions: how often save states are made (0 = off).
  • Input chunk (frames): how quickly Pause takes effect.
• About this install: version, game and its rights status, which keys are set, and the pricing table date.

#16. Costs and how to keep them low

Costs are estimates from the pricing table (backend/app/pricing.json); your provider's bill is the source of truth. Every run records its estimated cost, and caps stop a run before it overspends.

Ways to save

• Practise on segments (Starter%, Forest%, Gym%) instead of full runs.
• Use Sonnet for the strategist.
• Set the strategist effort to low.
• Raise re-plan every N decisions.
• Set a lower spending cap in the build.

#17. Where your data lives (and backups)

• Back up by copying the whole data folder while the app is closed.
• Move to a new PC: install the app, copy the data folder over, and point File → Setup → Data folder → Change… at it.
• Nothing in the data folder is ever uploaded. League submissions send only your build's settings and, if you choose, your keys for that one run.

#18. Configuration reference

Set these in .env (source or Docker) or as environment variables. The desktop app sets them for you.

#19. Troubleshooting

"Unsupported ROM" / the fingerprint doesn't match. Only Pokémon Red (USA, Europe) with SHA-1 ea9bcae6…48b9a works. Extract the .gb file if it's zipped, and check the hash (section 1). Patched or re-headered dumps won't match.

"ROM not found".

• Desktop: reopen File → Setup and choose the ROM again.
• Source: put it at roms/pokemon_red.gb or set JEV_ROM_PATH.

"Starting checkpoint … is missing" when starting a category or practice run. The scenario checkpoints haven't been prepared for this data folder. Run File → Setup → Prepare & open Ghostframe (desktop), or app.tools.bootstrap and then app.tools.story (source).

A runner says it needs a key / "cannot start: … is not configured". Add the key in File → Setup (desktop) or .env (source), then restart the app or server.

"Anthropic rejected the API key" / auth errors from Jev. The key is wrong, expired or out of credit. Replace it, and check your provider dashboard.

A run auto-pauses. After several model or emulator failures in a row (default 5), or 25 blocked actions, the run pauses so you can look. Check the Issues tab, then press Start to continue.

A run seems stuck walking in circles. Stuck detection asks the strategist for a new plan automatically. You can also Pause, look at Decisions, and Restore a save state.

The desktop window is blank or says it can't connect. Open File → Open backend log. Common causes are a missing ROM or a damaged data folder. Quit and relaunch; the backend starts fresh every launch.

Port 8000 is busy (source). restart.sh stops whatever is on 8000 first. Or run uvicorn on another port and open that one.

Replay says the starting checkpoint isn't on this computer. The run started from a checkpoint you don't have. Prepare scenarios (setup). Imported runs and league replays need the same scenario checkpoints, which setup creates identically on every machine.

League: "not a member of this league". Your token was revoked, or you were suspended. Ask the host for a new invite, then Disconnect and join again.

League: "this league doesn't pay for model calls". Choose Use my own API keys on the Submit tab.

SmartScreen blocks the installer. Click More info → Run anyway. The installer isn't code-signed yet.

Still stuck? Run the fast tests (section 3.9). If they pass, the install is healthy, and the backend log will show what went wrong.

#20. Glossary