Nintendo Entertainment System decomp guide

What this system is like

NES games are small. A whole game is often 32 KB to 512 KB of code and data. The code was written by hand in 6502 assembly. Assembly is the lowest kind of code, one machine step per line.

For Path A, most new projects use NESRecomp. It is a free static recompiler. It turns the game's 6502 code into C and adds a runtime for the console. Three people got a game playable in under a week with AI help. Two of them say the AI was Claude. All three already knew the tool.

Path B is different here. There was never any C, so there is no C to match byte for byte. The byte check comes from a disassembly instead. A disassembly is the game turned back into assembly text that rebuilds the exact same ROM. Then you port each routine to C and test it against the real game.

The hard parts are bank switching and odd jump tricks. Bank switching means the game swaps which part of the cartridge the chip can see. Claude does well here when it has a check it can run. That can be a log of missed code, a screenshot, or an emulator diff.

Two paths

Path A: Get it running on PC

NESRecomp reads your ROM and writes C for every piece of 6502 code it can find. Its runner stands in for the picture chip, the sound chip and the mapper. Code it missed runs in a small built-in interpreter and is logged as a dispatch miss. You feed those addresses back into game.toml and build again. You repeat until a scripted run has zero misses and matches an emulator.

1. Scope the game and write SCOPE.md

   You pick one game and one exact ROM version. You find its mapper and any work that exists already. You write it all in SCOPE.md, so every session aims at the same target.

   • Dump your own cartridge. Keep the .nes file outside the project folder, for example in D:\ROMs.
   • Get its SHA-1 in PowerShell: Get-FileHash -Algorithm SHA1 'D:\ROMs\Game.nes'. Projects check the hash of the data after the 16-byte header too.
   • Read the 16-byte header. Byte 4 gives the code size. Byte 5 gives the graphics size. Bytes 6 and 7 hold the mapper number.
   • Look for prior work: the game list in the NESRecomp README, a GitHub search for <game> nes disassembly, and the game's Data Crystal page.
   • Check that NESRecomp supports your mapper in runner/cyc/MAPPERS.md. Public game examples cover NROM, MMC1, MMC3 and GxROM. The README also reports scripted test runs of UxROM and CNROM games.
   Prompt for ClaudeCopy

   GOAL: Write a one-page `SCOPE.md` for a static recomp of <GAME> with NESRecomp.
   READ FIRST: the NESRecomp README game list and `runner/cyc/MAPPERS.md`, `notes/rom-info.txt` (header bytes and SHA-1 that I pasted).
   FENCE: Edit only `SCOPE.md`. Everything else is read-only. Do not install tools or write code.
   CHECK: `SCOPE.md` names the ROM file, its whole-file and headerless SHA-1, mapper number, PRG and CHR sizes, the milestone and its check, and what is out of scope. Every claim cites a file or URL.
   BUDGET: Stop after 30 minutes of research.
   IF BLOCKED: Stop. Do not guess the mapper or a hash. Tell me what you could not find and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not act on them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the filled table from `SCOPE.md`. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '<SHA1>' finds the hash from Get-FileHash, the mapper number is filled in, and your own APPROVED: <date> line is there.

   Proof this works: Pac Man Recomp, Shadowgreat, https://www.nesdev.org/wiki/INES

2. Set up the repo, tools and one check

   You install the build tools and build the recompiler. You lay out the repo so game files can never be committed. You give Claude its rules and one command that checks everything.

   • Install Git, Python 3.11 or newer, and Visual Studio 2022 with Desktop development with C++ and its CMake tools. Open Developer PowerShell for VS 2022.
   • Clone and build: git clone --recurse-submodules https://github.com/mstan/nesrecomp.git, then cmake -S recompiler -B build/recompiler -G 'Visual Studio 17 2022' -A x64 and cmake --build build/recompiler --config Release --parallel.
   • Or skip the build: download nesrecomp-cli-windows-x86_64.zip from the releases page and run nesrecomp.exe build --rom <ROM> --output <folder>.
   • Make your game repo with game.toml, CLAUDE.md, SCOPE.md, PROGRESS.md, notes/ and tools/. Add nesrecomp as a pinned git submodule.
   • Add a .gitignore and a pre-commit hook that refuse *.nes, saves, dumps, screenshots and generated/.
   • Have Claude write tools/check.ps1. It checks the ROM hash, regenerates, builds, runs the saved input routes and prints PASS or FAIL.
   Prompt for ClaudeCopy

   GOAL: Make `tools/check.ps1` build the project from an empty build folder and print PASS or FAIL.
   READ FIRST: `SCOPE.md`, `nesrecomp/docs/GETTING_STARTED.md`, `nesrecomp/runner/cyc/PROJECTS.md`.
   FENCE: Edit only `tools/`, `.gitignore`, `.githooks/`, `CLAUDE.md` and `PROGRESS.md`. Never edit inside `nesrecomp/`. Do not add features.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>`. Done means it exits 0, prints PASS, and `git status` shows no ROM or generated file staged.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: Stop. Do not work around a missing tool. Tell me the exact error and the command that failed.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the last 20 lines of the check. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.ps1 prints PASS on a clean clone, even though no game code runs yet.

   Proof this works: https://github.com/mstan/nesrecomp/blob/master/docs/GETTING_STARTED.md, Shadowgreat, z2rs

3. Map the ROM: banks, vectors and jump tricks

   You learn where the code lives before the recompiler guesses. You find the bank-switch routine, the jump-table tricks and the data areas. You save it all in a ledger file that every session reads.

   • Install Ghidra and the GhidraNes extension. Import the .nes file with the format set to NES ROM.
   • Open reset and vblank in the Symbol Tree. Note the bank-switch routine and the NMI handler.
   • Read nesrecomp/docs/PATTERNS.md. Mark every JSR followed by an address table, and every PLA/PHA trick on the return address.
   • If a ca65 disassembly exists, build it with ld65 -Ln game.lbl and convert names with python nesrecomp/tools/build_symbols_from_lbl.py game.lbl symbols.sym. Then set symbol_file = "symbols.sym" under [game] in game.toml.
   • Write notes/rom-map.md: banks, vectors, bank-switch address, dispatch routines and data ranges, each with how it was checked.
   Prompt for ClaudeCopy

   GOAL: Write `notes/rom-map.md` with the bank layout, vectors, bank-switch routine, inline dispatch routines and known data ranges of <GAME>.
   READ FIRST: `SCOPE.md`, `nesrecomp/docs/PATTERNS.md`, `nesrecomp/docs/EXTRACTION.md`. Use Ghidra over MCP if it answers; if not, use the disassembly at <DISASM_PATH>.
   FENCE: Edit only `notes/rom-map.md` and `symbols.sym`. Do not edit `game.toml` yet. Do not read `generated/`.
   CHECK: Each entry cites a ROM address and how you saw it (Ghidra listing, disassembly line, or bytes). The three vectors at `$FFFA`-`$FFFF` match the bytes in the ROM.
   BUDGET: Stop after 90 minutes, or when a bank has no clear entry point after two passes.
   IF BLOCKED: Stop. Say which bank or address you cannot explain and what you tried.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the vector bytes and three sample entries with their sources. 3) Files changed. 4) Banks still unclear. 5) New parking-lot items.

   Done whennotes/rom-map.md lists every bank, the bank-switch routine and each dispatch trick, each with a cited address.

   Proof this works: Dr. Mario NES Recomp, YoshisCookieRecomp, https://github.com/kylewlacy/GhidraNes

4. First light: boot to a screenshot

   You make the smallest possible build. A short game.toml and the headless host turn the ROM into a program with no window. It runs 600 frames and saves a picture.

   • Start game.toml with only [game], output_prefix = "<name>" and cycle_accurate = true. Add the bank-switch routine under [mapper] bank_switch if your map found one.
   • Configure: cmake -S nesrecomp/runner/cyc/project -B build-headless -G 'Visual Studio 17 2022' -A x64 -DNESRECOMP_ROM='D:/ROMs/Game.nes' -DNESRECOMP_GAME_CONFIG="$PWD/game.toml" -DNESRECOMP_HEADLESS=ON.
   • Build: cmake --build build-headless --config Release --parallel.
   • Run: build-headless\Release\nes_game.exe 'D:\ROMs\Game.nes' --frames 600 --screenshot boot.png.
   • Build the test oracle once: cmake -S nesrecomp/runner/cyc -B build/cyc and cmake --build build/cyc --config Release. You get build/cyc/Release/cyc_oracle.exe, a console model built from TriCNES.
   • Compare the first 600 frames: python nesrecomp/tools/cyc/cyc_verify.py --exe build-headless/Release/nes_game.exe --oracle build/cyc/Release/cyc_oracle.exe --rom 'D:/ROMs/Game.nes' --frames 600 --out verify/. It exits 0 when every run matches.
   • Open boot.png and the same moment in Mesen side by side. Note what differs in PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Get the headless host to run 600 frames of <GAME> and save `boot.png` that shows the title or logo.
   READ FIRST: `SCOPE.md`, `notes/rom-map.md`, `nesrecomp/docs/GETTING_STARTED.md` section 3.
   FENCE: Edit only `game.toml` and `PROGRESS.md`. Never edit `generated/` or anything in `nesrecomp/`.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH> -Frames 600`. Done means the build passes, `boot.png` exists, and `python nesrecomp/tools/cyc/cyc_verify.py --exe <EXE> --oracle <ORACLE> --rom <ROM_PATH> --frames 600 --out verify/` exits 0. Paste the `dispatch_misses.log` line count too.
   BUDGET: Stop after 3 builds that fail the same way.
   IF BLOCKED: Stop. Do not stub hardware or skip code to get a picture. Tell me the first error and the address involved.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output and a description of `boot.png`. 3) Files changed. 4) Miss count. 5) New parking-lot items.

   Done whenThe headless run writes boot.png, and cyc_verify.py exits 0 for the first 600 frames.

   Proof this works: Dragon Warrior4NESRecomp, https://github.com/mstan/nesrecomp/blob/master/docs/GETTING_STARTED.md, https://github.com/mstan/nesrecomp/blob/master/runner/cyc/README.md

5. Grind: drive dispatch misses to zero

   You play scripted routes and collect every address the recompiler missed. You fix each one in game.toml, never in the generated C. You stop when every route reports zero misses.

   • Write input routes as text files with one frame and button set per line. Start with boot to the first level, then one route per mode.
   • Run a route headless: nes_game.exe <ROM> --input <route.txt> --frames <N> --screenshot <png> --miss-log cyc_seeds.txt. Then read dispatch_misses.log next to the program. Each new line is a ready-made extra_func entry.
   • For each miss, look up the address in Ghidra. Then add one of: [[extra_func]], [[extra_label]], [[inline_dispatch]], [[inline_pointer]], [[data_region]] or a [functions] list.
   • Set cycle_seed_file = "cyc_seeds.txt" under [game] in game.toml. The next build then compiles the addresses the interpreter had to run.
   • Regenerate, rebuild and rerun every route after each change.
   Prompt for ClaudeCopy

   GOAL: Remove the dispatch miss at <BANK>:<ADDRESS> seen on route `<ROUTE_FILE>`.
   READ FIRST: `CLAUDE.md`, `notes/rom-map.md`, `nesrecomp/docs/PATTERNS.md`, the last 20 lines of `dispatch_misses.log`.
   FENCE: Edit only `game.toml` and `notes/findings.md`. Never edit or read `generated/` whole. Never edit `nesrecomp/`; if the recompiler itself is wrong, stop and say so.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>`. Done means this address is gone from the log, no new miss appears on any route, and every route still prints PASS.
   BUDGET: Stop after 3 tries, or 45 minutes with no change in the miss list.
   IF BLOCKED: Stop. Do not force the address to run in the interpreter to hide it. Tell me what the code at that address does and why each fix failed.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: miss count before and after, and the check output. 3) Files changed. 4) What the code does, with the Ghidra address. 5) New parking-lot items.

   Done whenEvery saved route reports zero dispatch misses and tools/check.ps1 prints PASS.

   Proof this works: Dr. Mario NES Recomp, Yoshi NES Recomp, Dragon Warrior4NESRecomp

6. Grind: match an emulator, one bug at a time

   Zero misses does not mean correct. You now compare RAM and pictures with a trusted emulator on the same input. Each difference becomes one bug card with proof.

   • Run the same route in your build and in the oracle: python nesrecomp/tools/cyc/cyc_verify.py --exe <EXE> --oracle <ORACLE> --rom <ROM> --input <route.txt> --frames <N> --interp --out verify/. It prints the first frame that differs.
   • Rerun both sides with --trace-frame <F> --trace-out <file> and diff the two files. Add --mem-frame <F> --mem-out <file> to dump RAM and the picture.
   • For a Mesen picture check, build nesrecomp/tools/cyc/mesen_shot from a MesenCE source checkout. Then run cmp_picture.py on your --mem-out file, with --ram-init zeros on your build.
   • Check the frame offset first. Compare a frame from before any button press with Mesen frames N and N+1. Never assume frame N is the same in both.
   • For each first difference, find the instruction that wrote the wrong byte. Name the cause as codegen, runner, timing or config before any fix.
   • Config fixes go in game.toml. Framework fixes go in a numbered patch file, not inside the submodule.
   Prompt for ClaudeCopy

   GOAL: Find and fix the first RAM difference between my build and Mesen on route `<ROUTE_FILE>`.
   READ FIRST: `CLAUDE.md`, `notes/findings.md`, `notes/dead-ends.md`, the two RAM dumps at <DUMP_A> and <DUMP_B>.
   FENCE: Edit only `game.toml`, `patches/nesrecomp/` and `notes/`. Never edit `generated/`. No printf logging; use the TCP debug server (`--tcp <PORT>`) and `--trace-out`.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>`. Done means the first difference moves later or disappears, and every other route still prints PASS.
   BUDGET: Stop after 2 failed fixes, or 60 minutes without a proven cause.
   IF BLOCKED: Stop. No fix until the cause is proven. Tell me the first differing byte, the frame, the writing instruction and your best two theories.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the diff before and after, and the check output. 3) Files changed. 4) Cause class: codegen, runner, timing or config. 5) New parking-lot items.

   Done whencyc_verify.py --input <route> exits 0 for every saved route, and each fix has a line in notes/findings.md.

   Proof this works: Yoshi NES Recomp, Dr. Mario NES Recomp, https://github.com/mstan/nesrecomp/blob/master/runner/cyc/README.md

7. Harden: lock fixes in with regression routes

   You turn every route into a test that runs by itself. Each test checks RAM values and picture hashes against a saved baseline. Old fixes can then never break without you knowing.

   • Run every route with --hash-out <route>.hash. It writes hashes of memory, the picture and the CPU registers for every frame.
   • Save the hash files from a known-good run in tests/baseline/. Make the check compare new runs with them line by line.
   • Run tests with an empty --mods-root folder and --no-save, so they never touch your real settings or saves.
   • Make tools/check.ps1 run every route. Have a fresh Claude session run it on a clean clone.
   Prompt for ClaudeCopy

   GOAL: Turn the routes in `routes/` into regression tests with a frame-hash baseline.
   READ FIRST: `CLAUDE.md`, `routes/`, `tools/check.ps1`, `PROGRESS.md`.
   FENCE: Edit only `tests/`, `tools/check.ps1` and `routes/`. Do not change `game.toml` or any game behavior. Never edit files in `tests/baseline/` by hand after they are first made.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>` twice in a row. Done means both runs print PASS with the same hashes. Then break one byte in a copied route and show that the check fails.
   BUDGET: Stop after 3 failed tries on the same test.
   IF BLOCKED: Stop. Tell me which route is not repeatable and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both PASS runs and the planted failure. 3) Files changed. 4) Routes not yet covered. 5) New parking-lot items.

   Done whenThe check passes twice in a row on a clean clone and fails when a route is broken on purpose.

   Proof this works: Dr. Mario NES Recomp, Pac Man Recomp, ZQuest Classic

8. Add the desktop host and ship without game data

   You move from the headless host to a real window with sound, pads and a launcher. You package it so the release holds no game code. The player's PC builds the game from their own ROM.

   • Use nesrecomp_add_cycle_game from nesrecomp/runner/cyc/project.cmake in your own CMakeLists.txt. Add your features as extra host source files.
   • Add recomp-ui as a submodule for the launcher and settings menu.
   • If you build with llvm-mingw, link libc++ and libunwind statically or ship the DLLs beside the program.
   • Package so the release builds the game on the player's PC from their ROM, as Pac Man Recomp and Shadowgreat do.
   • Run every regression route again on the desktop build.
   Prompt for ClaudeCopy

   GOAL: Build a desktop version of <GAME> with window, sound, pads and the recomp-ui launcher, and a release zip that holds no game data.
   READ FIRST: `CLAUDE.md`, `nesrecomp/runner/cyc/PROJECTS.md`, the `CMakeLists.txt` of a sister project at <SISTER_REPO>.
   FENCE: Edit only `CMakeLists.txt`, `src/`, `tools/package.ps1` and `PROGRESS.md`. Never edit `generated/`, `nesrecomp/` or `recomp-ui/`.
   CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>` and `powershell -File tools/package.ps1`. Done means all routes PASS and the package script reports zero ROM-derived files in the zip.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: Stop. Tell me the error and which file it points at.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe desktop build passes every route, and the release zip holds no ROM bytes or generated C.

   Proof this works: Pac Man Recomp, Shadowgreat, https://github.com/RetroPortingToolKit/recomp-ui

Path B: Full decomp for porting

First you get assembly source that rebuilds your exact ROM. That is the NES form of a matching decomp, and the build hash proves it. Then you port each routine to C. A test runs the same routine in the original and in your C, and compares RAM and every hardware access. When all routines pass, the game runs on C alone and can move to new systems.

1. Scope: version, disassembly and port target

   You pick one ROM version and look for an existing disassembly. You decide the port language and the test method. You write it in SCOPE.md.

   • Get the SHA-1 of the whole file and of the data after the 16-byte header.
   • Search GitHub for <game> nes disassembly. Check that it builds your exact ROM version, not a different revision.
   • Pick the port language. FF1 Recomp used C99 and z2rs used Rust. The outside Boulder Dash port uses C11.
   • Pick the test method: per-routine fixtures recorded from an emulator, or a lockstep run beside an emulator, frame by frame.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a full port of <GAME> from a byte-matching disassembly to C.
   READ FIRST: `notes/rom-info.txt`, the README of any disassembly I found at <DISASM_URL>.
   FENCE: Edit only `SCOPE.md`. Do not install anything or write code.
   CHECK: `SCOPE.md` names the ROM hashes, the disassembly and the exact ROM it builds, the port language, the test method, the milestones, and what is out of scope. Each claim cites a file or URL.
   BUDGET: Stop after 30 minutes of research.
   IF BLOCKED: Stop. If no disassembly matches my ROM, say so plainly and list the options.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not act on them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the filled `SCOPE.md` table. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '<SHA1>' finds both hashes, the disassembly and test method are named, and your own APPROVED: <date> line is there.

   Proof this works: FF1 Recomp, z2rs, https://github.com/Kryyto/boulder-dash-nes-decomp

2. Set up the assembler and the rebuild check

   You install the cc65 tools and a disassembler. You write one check that rebuilds the ROM from source and compares the hash. That check is your byte match for the rest of the project.

   • Windows: download the cc65 Windows snapshot zip and add its bin folder to PATH. WSL: sudo apt install cc65.
   • Download retrodisasm from its releases page (retrodisasm_v0.4.1_windows_64bit.zip). Unzip it and put retrodisasm.exe on PATH.
   • Lay out the repo: src/ for assembly, port/ for C, tools/, tests/, notes/. Ignore *.nes, build/ and anything made from the ROM.
   • Have Claude write tools/check.py. It assembles with ca65, links with ld65, and compares the SHA-1 with the one in SCOPE.md.
   Prompt for ClaudeCopy

   GOAL: Write `tools/check.py` that rebuilds the ROM from `src/` and prints PASS only if its SHA-1 equals the one in `SCOPE.md`.
   READ FIRST: `SCOPE.md`, the disassembly's own build script, the `ca65` and `ld65` docs at https://cc65.github.io/doc.
   FENCE: Edit only `tools/`, `.gitignore`, `CLAUDE.md` and `PROGRESS.md`. Do not change any `.s` or `.asm` file.
   CHECK: Run `python tools/check.py --rom <ROM_PATH>`. Done means it prints PASS. Then change one byte in a copy of the source and show that it prints FAIL.
   BUDGET: Stop after 3 failed tries on the same error.
   IF BLOCKED: Stop. Tell me the exact assembler or linker error.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the PASS and the planted FAIL. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py prints PASS, and prints FAIL when one byte of source is changed.

   Proof this works: https://github.com/aldonunez/zelda1-disassembly, https://github.com/retroenv/retrodisasm, https://packages.ubuntu.com/noble/cc65

3. Get a disassembly that rebuilds the exact ROM

   If a matching disassembly exists, you use it. If not, a tracing disassembler gives you a first draft that rebuilds byte for byte. You then fix code and data splits and add names, keeping the hash the same.

   • Draft one: retrodisasm -a ca65 -o src/game.asm 'D:\ROMs\Game.nes'. Prove it: retrodisasm -verify 'D:\ROMs\Game.nes'.
   • For a bank-switched game, -split-banks writes each bank to its own file. retrodisasm refuses mappers it does not support.
   • Its banking support is marked experimental. For bank-switched games, check every bank by hand in Ghidra or Mesen.
   • Add names, comments and code or data hints. Rerun python tools/check.py after each batch.
   • Never paste ROM bytes into the repo. Generate src/ from the ROM in a script, as the Boulder Dash port does.
   Prompt for ClaudeCopy

   GOAL: Rename the routines in bank <BANK> of `src/` with names that say what each does, keeping the ROM byte-identical.
   READ FIRST: `CLAUDE.md`, `notes/rom-map.md`, `notes/routines.toml`.
   FENCE: Edit only labels and comments in the bank <BANK> source file and `notes/routines.toml`. Do not change any instruction, byte or data value.
   CHECK: Run `python tools/check.py --rom <ROM_PATH>`. Done means it prints PASS, and every renamed routine has a one-line reason in `notes/routines.toml`.
   BUDGET: Stop after 40 routines or 90 minutes.
   IF BLOCKED: Stop. Name a routine `unk_<ADDR>` rather than guess. Tell me which ones you could not explain.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output. 3) Files changed. 4) Routines left unnamed. 5) New parking-lot items.

   Done whenpython tools/check.py prints PASS and every bank has its routines named or marked unk_.

   Proof this works: https://github.com/retroenv/retrodisasm, https://github.com/FiendsOfTheElements/z2disassembly, https://github.com/Kryyto/boulder-dash-nes-decomp

4. Map every routine into a ledger

   You make a list of every routine with its bank, address, size, callers and status. This list is the to-do list for the whole port. A script fills it; people only change the status and notes.

   • Get labels from the linker with ld65 ... -Ln game.lbl --dbgfile game.dbg.
   • Have Claude write tools/ledger.py that writes notes/routines.toml: name, bank, address, size, callers, callees, status.
   • Mark sound engine, reset and NMI code. These touch hardware most and need special care.
   • Write a coverage command that prints how many routines are ported, per bank.
   Prompt for ClaudeCopy

   GOAL: Write `tools/ledger.py` that builds `notes/routines.toml` from the linker label file and the source, and `tools/coverage.py` that prints totals per bank.
   READ FIRST: `CLAUDE.md`, `notes/rom-map.md`, `build/game.lbl`.
   FENCE: Edit only `tools/ledger.py`, `tools/coverage.py` and `notes/routines.toml`. Do not change source files.
   CHECK: Run `python tools/ledger.py` and `python tools/coverage.py`. Done means every label at a routine start appears once, the sizes add up to the code size of each bank, and `python tools/check.py` still prints PASS.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: Stop. Tell me which routines the script cannot size and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: coverage output. 3) Files changed. 4) Odd cases. 5) New parking-lot items.

   Done whennotes/routines.toml lists every routine with size and status, and tools/coverage.py prints per-bank totals.

   Proof this works: z2rs, FF1 Recomp

5. Build the test rig that compares C with the original

   Your C has no byte check, so this rig is your proof. It runs a routine in the original game and records RAM and every hardware access. Then it runs your C version on the same input and compares.

   • Record fixtures from a real run. Save RAM before and after each routine call, plus every PPU, APU, controller and mapper access in order.
   • Use an emulator you can script. The Boulder Dash port uses its own small Python emulator. z2rs runs the ROM in tetanes-core beside its port.
   • Test the rig on itself first: replay the original against the original and expect zero differences.
   • Write known emulator quirks as named exceptions, not as a looser compare.
   • Make tests that need the ROM skip cleanly when no ROM path is set.
   Prompt for ClaudeCopy

   GOAL: Build `tests/ramdiff` that replays recorded calls of one routine through the C port and compares RAM and the ordered list of hardware accesses.
   READ FIRST: `CLAUDE.md`, `SCOPE.md` test method, the Boulder Dash README section "How the port is checked" at https://github.com/Kryyto/boulder-dash-nes-decomp.
   FENCE: Edit only `tools/record.py`, `tests/` and `port/hw/`. Do not port any game routine yet.
   CHECK: Run `python tools/record.py <ROM_PATH> build/fixtures.bin` then `ctest --test-dir build --output-on-failure`. Done means the self-test (original against original) passes with zero differences, and a planted wrong write fails.
   BUDGET: Stop after 3 failed tries on the same problem.
   IF BLOCKED: Stop. Tell me what the recorder cannot capture.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: self-test output and the planted failure. 3) Files changed. 4) Gaps in what is recorded. 5) New parking-lot items.

   Done whenThe self-test passes with zero differences, and a planted wrong write makes it fail.

   Proof this works: https://github.com/Kryyto/boulder-dash-nes-decomp, z2rs

6. First light: port one small routine

   You port one short routine end to end. It proves the whole chain works: ledger, C file, fixtures and compare. Pick a routine with no hardware access and few callers.

   • Pick a short routine from notes/routines.toml with status todo and no PPU or APU writes.
   • Write it in C with the same integer sizes, the same order of writes, and the same bugs. Name the original routine in a comment.
   • Run its fixtures through tests/ramdiff.
   • Set its status to ported only when the test passes.
   Prompt for ClaudeCopy

   GOAL: Port routine `<ROUTINE>` (bank <BANK>, `<ADDRESS>`) to C so its fixtures pass.
   READ FIRST: `CLAUDE.md`, the routine's source in `src/`, its line in `notes/routines.toml`, `port/README.md`.
   FENCE: Edit only `port/src/<FILE>.c`, its header, and this routine's line in `notes/routines.toml`. Do not change tests, fixtures or other routines.
   CHECK: Run `ctest --test-dir build -R <ROUTINE> --output-on-failure`. Done means every recorded call passes with zero differences.
   BUDGET: Stop after 5 failed tries.
   IF BLOCKED: Stop. Do not loosen the compare. Tell me the first differing byte or access and your theory.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: test output. 3) Files changed. 4) Any original bug you kept. 5) New parking-lot items.

   Done whenThe routine's fixtures pass with zero differences and its ledger status is ported.

   Proof this works: FF1 Recomp, https://github.com/Kryyto/boulder-dash-nes-decomp

7. Grind: port routines in parallel, bank by bank

   Now you run many small cards. Each worker ports one routine or one small group in its own worktree. Leaves of the call tree go first, so callers can be tested on ported parts.

   • Have a script pick the next routines: status todo, all callees already ported, smallest first.
   • Give each worker one card and one worktree: claude --worktree <name>.
   • Merge one routine at a time. Run the full ctest and python tools/check.py after every merge.
   • Keep data tables in the ROM. Read them at start-up through offsets, never typed by hand.
   • Run python tools/coverage.py daily and record the totals in PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Port the routines listed below to C so each one's fixtures pass: <ROUTINE_LIST>.
   READ FIRST: `CLAUDE.md`, each routine's source in `src/`, `notes/routines.toml`, `notes/porting-rules.md`.
   FENCE: Work only in this worktree. Edit only the `port/src/` files named in the list and their lines in `notes/routines.toml`. Never type game data into C; read it from the ROM by offset.
   CHECK: Run `ctest --test-dir build --output-on-failure` and `python tools/check.py --rom <ROM_PATH>`. Done means every listed routine passes, no other test fails, and the ROM check prints PASS.
   BUDGET: Stop after 5 failed tries on one routine; mark it `hard` and move to the next.
   IF BLOCKED: Stop on that routine. Do not loosen a compare or skip a fixture. Note the first difference in `notes/routines.toml`.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: test summary line. 3) Files changed. 4) Routines marked `hard`. 5) New parking-lot items.

   Done whentools/coverage.py shows every routine ported, and the full test run passes on the merged branch.

   Proof this works: z2rs, FF1 Recomp, https://github.com/RodoLy/HarvestMoonSnesDecomp

8. Harden: run the whole game on C alone

   You remove the last link to the original code. The game must boot and play on your C only. Long scripted runs and screenshots prove it matches the original.

   • Turn off any fallback that runs original 6502 code. The build must fail loudly if a routine is missing.
   • Replay long inputs, such as published speedrun movies, and compare RAM and pictures frame by frame.
   • Feed random input from saved states to reach rare states. Fix and add a test for each difference.
   • Write scripted scenes with PASS or FAIL and a screenshot, as FF1 Recomp does with ff1-screenshots.
   Prompt for ClaudeCopy

   GOAL: Make the port boot and play <ROUTE_NAME> on C alone, with no original 6502 code running.
   READ FIRST: `CLAUDE.md`, `PROGRESS.md`, `routes/<ROUTE_NAME>.txt`, `notes/routines.toml`.
   FENCE: Edit only `port/`, `tests/scenes/` and `notes/`. Do not change fixtures or the compare code.
   CHECK: Run `ctest --test-dir build --output-on-failure` and `build/<GAME>-scenes <ROM_PATH>`. Done means all tests pass and every scene prints PASS with the interpreter switched off.
   BUDGET: Stop after 3 failed tries on one scene.
   IF BLOCKED: Stop. Tell me the first frame that differs and which routine wrote it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: test and scene output. 3) Files changed. 4) Scenes not yet covered. 5) New parking-lot items.

   Done whenEvery scripted scene passes with no original code running, on a clean clone.

   Proof this works: FF1 Recomp, z2rs, https://github.com/Kryyto/boulder-dash-nes-decomp

9. Port: move the console parts behind one layer

   You keep game logic free of SDL and the screen. Only a few files touch the window, sound and pads. Then you build for a second system and run the same scenes there.

   • Keep SDL calls in a few files only. FF1 Recomp allows SDL in main.c, input.c and audio.c only.
   • Read the game's RAM as a C struct. Keep the picture model apart from the code that draws to the screen.
   • Build for Linux in WSL first: cmake -S port -B build-linux and cmake --build build-linux.
   • Run the same scenes and tests on the new build. Then try other targets, as z2rs did for browser and Android.
   Prompt for ClaudeCopy

   GOAL: Build the port for Linux in WSL and pass the same tests and scenes as on Windows.
   READ FIRST: `CLAUDE.md`, `port/README.md`, `PROGRESS.md`.
   FENCE: Edit only `port/platform/`, `CMakeLists.txt` files and `notes/`. Do not change game logic files or tests.
   CHECK: In WSL run `cmake -S port -B build-linux && cmake --build build-linux && ctest --test-dir build-linux --output-on-failure`. Done means every test passes, and the scenes print PASS.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: Stop. Tell me which file pulls in a Windows-only call.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: test output from WSL. 3) Files changed. 4) Platform calls left in game code. 5) New parking-lot items.

   Done whenThe Linux build in WSL passes every test and scene that the Windows build passes.

   Proof this works: FF1 Recomp, z2rs, OpenMadoola

Tools you need

Skills and add-ons

Read any skill before you install it. A skill is a set of instructions that Claude will follow. See Tools and Skills for the full list and safety notes.

Claude setup for this system

On Path A, one unit is one dispatch miss or one first difference from Mesen. On Path B, one unit is one routine, or a few small routines from one bank. Every unit has its own check: the miss log, a route result, or a routine's fixtures. Keep game.toml and the merged branch under one owner, so only the lead changes them. Workers report the change they want, with proof.

Which model and effort for each job

The model and effort names come from one shared table, so they stay the same on every guide. See Claude Setup for the reasons.

How many sessions at once

Lines for this project's CLAUDE.md

- Read `SCOPE.md`, `PROGRESS.md` and `notes/dead-ends.md` at the start of every session.
- Never edit or read whole any file in `generated/`. Fix `game.toml`, the recompiler or the runner, then regenerate.
- The one check is `powershell -File tools/check.ps1 -Rom <ROM_PATH>` (Path B: `python tools/check.py --rom <ROM_PATH>` and `ctest --test-dir build`). Done means it prints PASS. Paste the output.
- `nesrecomp/` and `recomp-ui/` are pinned submodules. Never commit inside them. Framework fixes go in `patches/<submodule>/NNNN-<name>.patch`.
- No guessing. Every claim about 6502 code cites a ROM address seen in Ghidra, the disassembly, or an emulator diff. Say 'I don't know yet' otherwise.
- Before any fix, name the cause as one of: codegen, runner, timing, config.
- No printf debugging. Use the TCP debug server (`--tcp <PORT>`) for runtime state.
- When you compare with Mesen, first find the frame offset from a frame before any button press. Never assume frame N is the same in both.
- Test runs use a copied save file and an empty `--mods-root`. Never touch my real settings or saves.
- Check RAM addresses from notes or wikis against the ROM before you rely on them. Record each finding in `notes/findings.md` with address, meaning, how it was checked and date.
- Never commit ROMs, generated C, saves, screenshots or anything made from the ROM.
- Use absolute paths in worktrees. Run the game headless; never open a game window unless I ask.
- Commit and update `PROGRESS.md` after each finished card. A session can end without warning.

Keep the context small

• Point Claude at a bank and an address, not at a pasted listing. Ghidra over MCP or the disassembly file can answer the rest.
• Paste only the last 20 lines of dispatch_misses.log or the first difference from a diff, never whole traces.
• Clear the chat after each card. The ledgers and PROGRESS.md carry the state, not the chat.
• Use a subagent to read a big file, such as a whole bank's source, and report back a short summary.
• Keep CLAUDE.md short. Put the 6502 tricks in notes/patterns.md and let Claude read it only when a card needs it.

More prompts for this system

Each step above has its own prompt. These extra prompts cover the rest of the work. Fill in the parts in <ANGLE_BRACKETS>.

GOAL: Tell me if <GAME> (<ROM_FILE>) is a good NES target, which path fits, and draft `SCOPE.md`.
READ FIRST: `notes/rom-info.txt` (header bytes, SHA-1), the NESRecomp README game list and `runner/cyc/MAPPERS.md`, a GitHub search for `<GAME> nes disassembly`.
FENCE: Edit only `SCOPE.md` and `notes/feasibility.md`. Do not install tools or write code.
CHECK: `notes/feasibility.md` answers: mapper and whether NESRecomp has a public example of it; whether a port or disassembly exists for this exact revision; PRG size; risks. Each answer cites a URL or file.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. If the mapper is not supported or the ROM is a disk game, say so plainly and list my options.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not act on them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the answers with sources. 3) Files changed. 4) Your advice in one sentence. 5) New parking-lot items.

GOAL: Fill `notes/rom-map.md` for bank <BANK>: entry points, jump tables, data ranges and the bank-switch calls it makes.
READ FIRST: `CLAUDE.md`, `notes/rom-map.md`, `nesrecomp/docs/PATTERNS.md`. First check that the Ghidra MCP server answers one simple call; if not, use `src/` from the disassembly.
FENCE: Edit only `notes/rom-map.md`. Do not edit `game.toml` or any source.
CHECK: Every entry has an address and a source line or Ghidra listing. The bank's data ranges plus code ranges cover the whole bank with no overlap.
BUDGET: Stop after 60 minutes or one full pass of the bank.
IF BLOCKED: Stop. List the ranges you could not classify as code or data.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the coverage sum for the bank. 3) Files changed. 4) Unclear ranges. 5) New parking-lot items.

GOAL: Make <BANK>:<ADDRESS> run as native code, so it no longer appears in `dispatch_misses.log`.
READ FIRST: `CLAUDE.md`, `notes/rom-map.md`, `nesrecomp/docs/PATTERNS.md`, `notes/dead-ends.md`.
FENCE: Edit only `game.toml` and `notes/findings.md`. Never edit `generated/` or `nesrecomp/`.
CHECK: Run `powershell -File tools/check.ps1 -Rom <ROM_PATH>`. Done means the address is gone, no new misses appear, and all routes PASS.
BUDGET: Stop after 3 tries.
IF BLOCKED: Stop. Do not add a `[force_interp]` entry to hide it. Tell me what the code does and why the fixes failed.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: miss counts before and after. 3) Files changed. 4) Which `game.toml` entry type you used and why. 5) New parking-lot items.

GOAL: Port `<ROUTINE>` (bank <BANK>, `<ADDRESS>`) to C so all its recorded calls match the original.
READ FIRST: `CLAUDE.md`, `notes/porting-rules.md`, the routine in `src/`, its line in `notes/routines.toml`.
FENCE: Edit only `port/src/<FILE>.c`, its header, and this routine's ledger line. Do not touch tests, fixtures or other routines. Do not type game data into C.
CHECK: Run `ctest --test-dir build -R <ROUTINE> --output-on-failure`. Done means zero differences on every call.
BUDGET: Stop after 5 tries; then set status `hard` with the first difference.
IF BLOCKED: Stop. Do not loosen the compare. Tell me the first differing byte or hardware access.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: test output. 3) Files changed. 4) Original bugs kept. 5) New parking-lot items.

GOAL: Pick the next <N> units and start one worker per unit, each in its own worktree.
READ FIRST: `CLAUDE.md`, `PROGRESS.md`, `notes/routines.toml` (or `dispatch_misses.log`), `notes/dead-ends.md`.
FENCE: You only plan, dispatch and merge. Do not port or fix anything yourself. Only you edit `game.toml`, `notes/routines.toml` and the main branch.
CHECK: After each merge run `ctest --test-dir build --output-on-failure` and `python tools/check.py --rom <ROM_PATH>` (Path A: `tools/check.ps1`). Done means all <N> units are merged or marked `hard`, and the checks PASS on the merged branch.
BUDGET: Stop when <N> units are handled or after <HOURS> hours.
IF BLOCKED: Stop. Tell me which merges failed and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output on the merged branch. 3) Units merged, units marked `hard`. 4) Coverage totals. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> on route `<ROUTE_FILE>` at about frame <FRAME>. Do not fix it yet.
READ FIRST: `CLAUDE.md`, `notes/findings.md`, `notes/dead-ends.md`.
FENCE: Read-only, except `notes/debug-<SYMPTOM>.md`. No printf logging; use the TCP debug server and Ghidra.
CHECK: The note names the first byte that differs from Mesen, the frame, the instruction that wrote it, and the cause class: codegen, runner, timing or config. For pictures, say if tile shapes, positions or colors are wrong.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Tell me what data you would need to go further.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the diff lines. 3) Files changed. 4) The proposed fix and where it goes. 5) New parking-lot items.

GOAL: Check that the work in <COMMIT_RANGE> is real and follows the rules.
READ FIRST: `CLAUDE.md`, `SCOPE.md`, `git diff <COMMIT_RANGE> --stat`.
FENCE: Read-only. Do not fix anything. Write findings only to `notes/verify-<DATE>.md`.
CHECK: On a clean clone, run the full check. Then look for: edits in `generated/`, `nesrecomp/` or `tests/baseline/`; new `[force_interp]` or `nop_jsr` entries with no reason; loosened compares or skipped fixtures; game data typed into C; ROM bytes in git.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. Tell me what you could not check.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the check output from the clean clone. 3) Files changed: only the verify note. 4) Each rule broken, with file and line. 5) New parking-lot items.

GOAL: Give me a status report from the ledgers, with numbers only.
READ FIRST: `PROGRESS.md`, `notes/routines.toml` or `dispatch_misses.log`, `notes/parking-lot.md`.
FENCE: Read-only, except `PROGRESS.md` where you add a dated status block.
CHECK: Run `python tools/coverage.py` (Path B) or count the lines of `dispatch_misses.log` and run `tools/check.ps1` (Path A). Every number in the report comes from that output.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Tell me which ledger is missing or out of date.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the raw counts. 3) Files changed. 4) Top three blockers. 5) Parking-lot items waiting for me.

GOAL: Write `notes/handoff.md` so a new session can carry on with no chat history.
READ FIRST: `PROGRESS.md`, `git log -10 --oneline`, `notes/findings.md`.
FENCE: Edit only `notes/handoff.md` and `PROGRESS.md`.
CHECK: The note has: what is PROVEN (with the check output), what is NOT the problem, the one next question, the files the next session may and may not touch, and the exact commands to run first.
BUDGET: Stop after 10 minutes.
IF BLOCKED: Stop. Tell me what you could not confirm.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste `notes/handoff.md`. 3) Files changed. 4) The next question. 5) New parking-lot items.

GOAL: Give me a plain answer about <UNIT>: can it be done in this project as scoped, yes or no?
READ FIRST: `SCOPE.md`, `notes/dead-ends.md`, the last report for <UNIT>.
FENCE: Read-only, except `notes/dead-ends.md`.
CHECK: Your answer lists each thing tried, the result of each with proof, and the reason it fails. It names whether the blocker is in my game, the recompiler, the runner, or the test rig.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Say BLOCKED and list what you would need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the evidence for each try. 3) Files changed. 4) Two or three options with cost and risk. 5) New parking-lot items.

GOAL: Ask me before you leave the fence. Explain the change you want and why.
READ FIRST: `SCOPE.md`, `CLAUDE.md`, the card you are working on.
FENCE: Do not edit anything. Write the request in `notes/scope-requests.md` only.
CHECK: The request names the file to change, the exact change, the proof that the fence blocks the card, and how we would undo it. For `nesrecomp/` it says if a patch file in `patches/` would do.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop and wait for my yes or no.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) BLOCKED until I answer. 2) Proof: the evidence. 3) Files changed: only the request. 4) Risk if I say yes. 5) New parking-lot items.

Keep Claude on task

These are the detours Claude tends to take on this system, and the rule that stops each one. The full method is on Stay on Task.

Problems other projects hit

How long it takes

What makes it faster or slower

• Whether a NESRecomp port of a sister game, or a disassembly of your exact ROM, already exists.
• The mapper and how much code is bank-switched. A 32 KB NROM game is far less work than a 512 KB MMC1 game.
• How many jump-table tricks the game uses. Each one is a game.toml entry you must find.
• How much of the game your routes reach. Untested modes, endings and two-player play hide misses.
• For Path B, how good your test rig is. Without per-routine fixtures, small bugs hide until late.

The facts behind these numbers

Projects reviewed (14)

We took the top-starred project for each of the top 12 games on RecompLauncher. We added two more that were flagged as made with AI. Final Fantasy has two projects. VKRT is an emulator for several games. No reviewed project came from outside RecompLauncher. Outside repos, such as the Boulder Dash port and the Zelda disassembly, appear only as step or time evidence.

What each project teaches

What we could not check

• Whether GhidraMCP 2.0 (built for Ghidra 12.1.4) and GhidraNes (newest build for Ghidra 12.1) work in the same Ghidra install.
• Whether NESRecomp builds and runs in WSL or on Linux. Its README says Linux 'likely works' and is less tested.
• The Mesen MCP bridge in nesrecomp/tools: its commands were not run or read in full.
• Which Ghidra MCP server Dr. Mario NES Recomp and Yoshi NES Recomp used. Their files only name a tool prefix and a port.
• How long a medium NES game takes with no AI on Path A. No dated pre-agent NES static recomp was found.
• How long a full NES port takes with AI. No dated AI-assisted NES example was found; the range uses a SNES project.
• Whether retrodisasm handles bank-switched games well. Its own docs call banking support experimental.
• The private history of z2rs, FF1 Recomp, OpenMadoola, Bubble Bobble Recomp and Final Fantasy NES Recomp. Their public dates may not show the real work time.
• Which tool the original NES developers used to assemble their games.
• No command in this guide was run here. Every command comes from a tool's own docs or a reviewed project.
• Whether cyc_verify.py works with a full game build and the TriCNES oracle for every mapper. Its docs show test ROMs and four commercial games.
• Whether mesen_shot builds from a MesenCE checkout on Windows without extra steps.
• Which mapper Pac-Man uses. The project's docs do not say.

Sources

• NESRecomp README
• NESRecomp: Your first port (GETTING_STARTED.md)
• NESRecomp CLAUDE.md
• NESRecomp tools README (symbols from ca65, Mesen MCP)
• NESRecomp legacy co-simulation (COSIM.md)
• recomp-ui README
• Mesen Community Edition README
• Mesen 2 archive notice
• GhidraNes README
• GhidraMCP README
• Ghidra README
• cc65 README
• Ubuntu 24.04 cc65 package
• retrodisasm README
• llvm-mingw README
• nesdev wiki: iNES
• nesdev wiki: CPU
• nesdev wiki: CPU memory map
• nesdev wiki: PPU
• nesdev wiki: Mapper
• Retro Game Coders: NES (most production NES code is assembly)
• Zelda 1 disassembly README
• Boulder Dash NES decomp and C port
• SuperMarioBros-C
• Harvest Moon SNES decomp
• Recomp + AI: 5 Months Later
• NESRecomp cycle backend guide (runner/cyc/README.md)
• NESRecomp cycle project reference (PROJECTS.md)
• NESRecomp PERMISSIONS.md
• retrodisasm NES guide
• SDL releases
• Git for Windows