Nintendo DS decomp guide

What this system is like

The DS has two ARM chips. The big one runs the game. The small one runs sound, touch and wireless. Most games load extra code into the same memory slots at different times. These swappable code blocks are called overlays. Overlays are the main trap on this system.

Tools for the DS got much better in 2024 with dsd. It reads a game file and lists every function, its size and its mode. That list is what both paths need. In 2026 many DS projects used Claude Code. Some shipped a playable PC build within weeks.

Path A turns the machine code into C with a recompiler. A recompiler is a tool that writes C that does the same thing as the machine code. You then write a runtime that stands in for the DS. Path B rebuilds the game as C that compiles back to the exact same bytes. Three DS games reached about 100% that way in 2026. At least two of them say agents helped.

The hard parts are plain. The original compiler, mwccarm, is not free to share, so you must supply it. Byte-exact C still needs real work before it runs on a 64-bit PC. Most steps run on Windows. A few test scripts need WSL, a Linux system inside Windows.

Two paths

Path A: Get it running on PC

You map the game with dsd. A recompiler script turns each game function into one C function. You write a runtime in C that stands in for the DS: memory, timers, 2D, 3D, sound and input. Then you fix one crash or one wrong picture at a time. Six of the 13 reviewed projects took this road.

1. Scope the game and look for prior work

   You pick one game, one region and one exact file hash. Then you check what already exists. A decomp, a symbol list or a sister game can save months.

   • Hash your own dump in WSL: sha1sum game.nds.
   • Search for your game on decomp.wiki, pret.github.io and GitHub. Note any decomp, symbol file or recomp.
   • Check if another region is done. In DQIX Modern, the EU main code sits 0x10 bytes after the USA code. A small script converts the addresses.
   • Ask Claude for a draft SCOPE.md with the prompt below. Edit it yourself and approve it.
   Prompt for ClaudeCopy

   GOAL: Write a draft `SCOPE.md` for a PC build of <GAME> (<REGION>, SHA-1 <HASH>) by static recompilation.
   READ FIRST: `notes/prior-work.md` (my search notes), https://decomp.wiki/platforms/nintendo-ds
   FENCE: Create only `SCOPE.md`. Do not install, download or build anything.
   CHECK: Run `grep "^## " SCOPE.md`. Done means it prints these 7 headings: Goal, Game and hash, Technique, Prior work, Milestone 1 and its check, Out of scope, Never edit.
   BUDGET: 30 minutes.
   IF BLOCKED: Stop. List what you could not find out and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The headings you filled. 3) Each claim about prior work with its URL. 4) Open questions for me.

   Done whengrep -c "^## " SCOPE.md prints 7, grep -q <HASH> SCOPE.md succeeds, and you approved the file.

   Proof this works: Dragon Quest IX Modern, Egg of Time, https://decomp.wiki/platforms/nintendo-ds

2. Set up the repo and extract the game

   You make the repo, keep the game file outside it, and extract the code. You also write one check command. It starts small and grows with the project.

   • Install WSL once. In PowerShell as administrator, run wsl --install, then restart.
   • Install Python 3 and Git for Windows. Git for Windows also gives you Git Bash.
   • Download dsd-windows-x86_64.exe (v0.12.1) from the ds-decomp releases and save it as tools/dsd.exe.
   • Install Python helpers: pip install capstone ndspy.
   • Install build tools: python -m pip install "cmake>=3.21,<4" ninja. Unzip llvm-mingw-20261104-ucrt-x86_64.zip and add its bin folder to PATH. Unzip SDL3-devel-3.4.18-mingw.zip for the window and sound library.
   • Extract: tools/dsd.exe rom extract --rom <ROM_DIR>/game.nds --output-path extract.
   • Add extract/, gen/, build/, *.nds, bios/ and saves to .gitignore.
   • Write tools/check.py. For now it rebuilds and prints OK. Write CLAUDE.md, PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Lay out the repo and one check command for the <GAME> recomp.
   READ FIRST: `SCOPE.md`, `CLAUDE.md`
   FENCE: Edit only `tools/check.py`, `CMakeLists.txt`, `.gitignore`, `PROGRESS.md`. The ROM at <ROM_DIR> and `extract/` are read-only. Do not add features I did not ask for.
   CHECK: Run `python tools/check.py`. Done means it exits 0 and prints OK, and `git status --ignored` shows `extract/` as ignored.
   BUDGET: Stop after 3 failed tries on the same error.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check output. 3) Files changed. 4) What is left.

   Done whenpython tools/check.py exits 0 on a clean clone, and git status --porcelain --ignored lists extract/ only as ignored (!!).

   Proof this works: Egg of Time, https://github.com/AetiasHax/ds-decomp

3. Map every function with dsd

   You let dsd find every function, its size, its mode and its overlay. You name the SDK code so nobody works on it by hand. The result is your function ledger.

   • Run tools/dsd.exe init --rom-config extract/config.yaml --output-path config --build-path build.
   • If it stops on a strange call, add --allow-unknown-function-calls. Egg of Time and khdays-decomp both needed it.
   • Name known SDK functions: tools/dsd.exe sig apply --config-path config/arm9/config.yaml --all.
   • Have Claude turn every symbols.txt into ledger/functions.csv with address, size, mode, module and a status column.
   • Optional: load the ROM in Ghidra 11.2.1 with dsd-ghidra and run SyncDsd.java to see names in Ghidra.
   Prompt for ClaudeCopy

   GOAL: Build `ledger/functions.csv` from the dsd config, one row per function.
   READ FIRST: `config/arm9/config.yaml`, the `symbols.txt` and `relocs.txt` files under `config/`, `SCOPE.md`
   FENCE: Edit only `tools/make_ledger.py` and `ledger/`. Everything under `config/` and `extract/` is read-only.
   CHECK: Run `python tools/make_ledger.py --verify && python tools/check.py`. Done means both exit 0, the CSV row count equals the function count in the `symbols.txt` files, and each row has address, size, mode (ARM or Thumb), module and status.
   BUDGET: Stop after 3 failed tries or 45 minutes with no progress.
   IF BLOCKED: Stop. Show the rows or files that do not fit and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the counts per module. 3) How many functions are SDK. 4) Files changed.

   Done whenpython tools/make_ledger.py --verify exits 0. That means the CSV row count equals the function count in the symbols.txt files. Every row has size, mode, module, status and an SDK flag.

   Proof this works: Egg of Time, DQIX Enhanced, https://github.com/AetiasHax/dsd-ghidra

4. Build and test the recompiler

   You write a script that turns each game function into one C function. You test it alone before you run the game. A bad translation here causes crashes that are very hard to trace later.

   • Use one C shape for every function, like void f_<module>_<addr>(CPU *cpu), plus an address table for calls through pointers. This is the Egg of Time design.
   • Branches inside a function become goto. Known bl and blx calls become direct C calls.
   • Keep special cases in small text files: hooks.txt, hle.txt, interpret.txt, patches.txt. DQIX Enhanced works this way.
   • Test the decoder against LLVM on every instruction, as DQIX did with 0 disagreements.
   • Test behavior: compile small C functions to ARM and Thumb, recompile them, and compare with the native build on random inputs.
   • Run both tests in WSL. They need a Linux clang with an ARM target: sudo apt install clang llvm lld. DQIX Modern could not run them on its Windows PC.
   • Or start from the ndsrecomp framework, which Metroid Prime Hunters used. It is pre-alpha and noncommercial. By default it wants your own DS BIOS and firmware dumps.
   Prompt for ClaudeCopy

   GOAL: Make `tools/recomp.py` translate module <MODULE> and pass the decoder and behavior tests.
   READ FIRST: `CLAUDE.md`, `config/arm9/<MODULE>/symbols.txt`, `tests/README.md`
   FENCE: Edit only `tools/recomp.py`, `tools/recomp/` and `tests/`. Never edit files in `gen/`; they are output. Do not change the test inputs to make them pass.
   CHECK: In WSL, run `python3 tests/decoder_vs_llvm.py <MODULE> && python3 tests/semantics.py 2000`. Done means 0 disagreements and 0 failures.
   BUDGET: Stop after 5 failed tries on one instruction class.
   IF BLOCKED: Stop. Name the instruction, the expected result and the real result.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both test summaries. 3) Files changed. 4) Instruction classes still untested.

   Done whenThe decoder test shows 0 disagreements and the behavior test shows 0 failures for every module you translate.

   Proof this works: DQIX Enhanced, Egg of Time, MetroidPrimeHuntersRecomp, https://github.com/RetroPortingToolKit/ndsrecomp

5. Boot to the first frame

   You write the runtime and link it with the generated C. The goal is one picture on screen. Keep it small: memory, interrupts, timers, the file system and 2D first.

   • Run the recompiler over the ARM9 program and all overlays into gen/. Build with CMake and Ninja.
   • Replace the SDK thread switch (OS_SaveContext, OS_LoadContext) with coroutines, one per game thread. Find it by byte signature. Egg of Time uses minicoro for this.
   • Before any call into an overlay slot, compare the bytes in memory with each overlay's bytes. Run the one that matches.
   • Fake the ARM7's jobs at a high level at first. Egg of Time ships this way.
   • Add debug switches early: scripted keys, timed screenshots and a write watch on one address.
   • Set the right reset values. A wrong POWCNT1 value swapped the two screens in Metroid Prime Hunters.
   Prompt for ClaudeCopy

   GOAL: Boot <GAME> to its first visible frame with no person at the keys.
   READ FIRST: `SCOPE.md`, `CLAUDE.md`, `docs/runtime-plan.md`, GBATEK sections DS Memory Maps and DS Video (https://problemkaputt.de/gbatek.htm)
   FENCE: Edit only `runtime/` and `CMakeLists.txt`. Never edit `gen/`. Fix bad generated code in `tools/recomp.py` and regenerate. No stub may return a fake value: unknown functions must abort and print their DS address.
   CHECK: Run `python tools/check.py --golden boot`. Done means the build passes, the game runs 600 frames with no crash, and `out/boot_0600.png` is not blank.
   BUDGET: Stop after 5 failed tries on one crash, or 60 minutes with no new frame reached.
   IF BLOCKED: Stop. Paste the last log lines, the address and what you think is missing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check output and the screenshot path. 3) Files changed. 4) Stubs that still abort.

   Done whenpython tools/check.py --golden boot runs 600 frames without a crash and saves a non-blank screenshot.

   Proof this works: Egg of Time, DQIX Enhanced, MetroidPrimeHuntersRecomp

6. Grind: one crash or one missing function at a time

   You play forward and fix one problem per session. Each fix needs proof from a log, a trace or a side-by-side run. Missing functions go back into the recompiler's input, never into the C output.

   • Log every call that misses the address table. Add those addresses to an entry list like faltan.txt and regenerate. DS Kart and Metroid Prime Hunters both did this.
   • Build a lockstep mode. It runs an interpreter and your C side by side and stops at the first difference. SoulSilver Recomp checked 16,000 frames this way.
   • Or compare against melonDS at fixed frame counts, as ndsrecomp does with its ndsref oracle.
   • Record each fix and each dead end in PROGRESS.md and notes/dead-ends.md.
   Prompt for ClaudeCopy

   GOAL: Fix crash <BUG_ID>: <ONE_LINE_SYMPTOM>.
   READ FIRST: `CLAUDE.md`, `PROGRESS.md`, `notes/dead-ends.md`, `logs/<BUG_ID>.log`, `inputs/<BUG_ID>.input`
   FENCE: Edit only `runtime/`, `tools/recomp.py` and its entry lists. Never edit `gen/`. Do not add per-scene hacks or fake events.
   CHECK: Run `python tools/check.py --golden <ROUTE>`. Done means the route passes its last checkpoint and every older golden run still passes.
   BUDGET: Stop after 3 fixes that did not work, or 60 minutes with no new evidence.
   IF BLOCKED: Stop. Do not work around it. Give the first point where the runs differ and your best theory.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The proven cause with the log line or trace. 3) Paste the check output. 4) Files changed. 5) New dead ends.

   Done whenThe route's golden run reaches its last checkpoint and all older golden runs still pass.

   Proof this works: SoulSilver Recomp, DS Kart Recompiled, MetroidPrimeHuntersRecomp

7. Make graphics and sound match the DS

   You build the 2D engines, the 3D engine and the sound mixer. Keep a slow software version as the reference. Check each fast path against it and against melonDS.

   • Write a software 2D and 3D renderer first. KH Days Port kept its software engines as the reference for the GPU path.
   • Save reference frames and your own frames at the same frame number. Compare them with a script, not by eye. Metroid Prime Hunters used ndsref at fixed frame counts. KH Days Port used DeSmuME save states.
   • Hash sound output sample by sample on a fixed input.
   • Test fades, menus and screen changes in motion. SoulSilver Recomp broke these many times.
   • Run lockstep with widescreen off. Widescreen changes the game's own math.
   Prompt for ClaudeCopy

   GOAL: Make scene <SCENE> draw the same as the reference frame `refs/<SCENE>_<N>.png`.
   READ FIRST: `CLAUDE.md`, `docs/graphics.md`, `refs/<SCENE>_<N>.png`, GBATEK section DS 3D Video
   FENCE: Edit only `runtime/gpu2d/`, `runtime/gpu3d/` and `tests/render/`. Reference images are read-only. Do not lower the compare limit.
   CHECK: Run `python tests/render/compare.py <SCENE> <N>`. Done means 0 differing pixels against the reference, and the other render tests still pass.
   BUDGET: Stop after 4 failed tries or 60 minutes with no fewer wrong pixels.
   IF BLOCKED: Stop. Show the diff image path and the register state you suspect.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Pixel count before and after. 3) Files changed. 4) Scenes still wrong.

   Done whenThe render compare script reports 0 differing pixels for the scene, and older render tests still pass.

   Proof this works: KH Days Port, SoulSilver Recomp, MetroidPrimeHuntersRecomp

8. Harden and package

   You build a set of replayed runs so old fixes stay fixed. Then you package the build so it ships no game code. The game is rebuilt on the player's PC from their own dump.

   • Record input files from a save. Replay them and compare key frames with references. DQIX Modern expects a 0.00 difference on every region before a merge.
   • Make the runtime fully repeatable: fixed clock, fixed random seed, recorded input.
   • Ship the runtime, the recompiler and a pinned compiler. Build the game on first start from the hashed ROM, like Egg of Time and DS Kart.
   • Check that no ROM, gen/ output, BIOS or save is in the release zip.
   Prompt for ClaudeCopy

   GOAL: Add a smoke test that replays <N> recorded routes and compares key frames.
   READ FIRST: `CLAUDE.md`, `tests/smoke/README.md`, `PROGRESS.md`
   FENCE: Edit only `tests/smoke/` and `tools/check.py`. Reference frames and saves stay outside the repo at <REF_DIR> and are read-only.
   CHECK: Run `python tools/check.py --smoke` on a clean clone. Done means every route reports difference 0.00.
   BUDGET: Stop after 3 failed tries on one route.
   IF BLOCKED: Stop. Name the route, the frame and the difference.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the smoke output. 3) Files changed. 4) Routes not covered.

   Done whenpython tools/check.py --smoke passes on a clean clone, and the release zip holds no game data.

   Proof this works: Dragon Quest IX Modern, Egg of Time, DS Kart Recompiled

Path B: Full decomp for porting

You split the game with dsd, then write C that mwccarm compiles back to the exact bytes. objdiff scores each function. dsd check modules checks the whole program. Three DS games reached about 100% this way in 2026, at least two with stated agent help. A port then compiles the same C for PC with a layer that stands in for the SDK.

1. Scope the decomp and find the compiler versions

   You confirm no decomp of your game exists, and you learn which compiler versions it needs. One game can use several mwccarm versions. Getting this wrong wastes weeks.

   • Search decomp.wiki, pret.github.io and GitHub for your game and its sister games.
   • Read the version list of a similar decomp. aletheia uses six mwccarm versions and lists one per function. khdays-decomp uses mwccarm 3.0 build 139 for almost everything.
   • Check the project rules of any decomp you build on. pret does not accept AI-written code.
   • Write SCOPE.md with the game hash, the region and the compiler versions you expect.
   Prompt for ClaudeCopy

   GOAL: Write a draft `SCOPE.md` for a matching decomp of <GAME> (<REGION>, SHA-1 <HASH>).
   READ FIRST: `notes/prior-work.md`, https://decomp.wiki/platforms/nintendo-ds
   FENCE: Create only `SCOPE.md`. Do not download or install anything.
   CHECK: Run `grep "^## " SCOPE.md`. Done means it prints these 7 headings: Goal, Game and hash, Compiler versions and how we will confirm them, Prior work with URLs, Milestone 1 and its check, Out of scope, Never edit.
   BUDGET: 30 minutes.
   IF BLOCKED: Stop. List 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) Each prior-work claim with its URL. 3) Open questions for me.

   Done whengrep -c "^## " SCOPE.md prints 7, grep -q <HASH> SCOPE.md succeeds, and you approved the file.

   Proof this works: https://github.com/Project-Holon/aletheia, pokeheartgold Single Screen, https://decomp.wiki/platforms/nintendo-ds

2. Set up dsd, the compiler and the gate

   You extract, split and relink the game so it rebuilds byte for byte before any C exists. That proves your pipeline. The one check is dsd check modules.

   • tools/dsd.exe rom extract --rom <ROM_DIR>/game.nds --output-path extract
   • tools/dsd.exe init --rom-config extract/config.yaml --output-path config --build-path build --allow-unknown-function-calls
   • tools/dsd.exe delink --config-path config/arm9/config.yaml and tools/dsd.exe lcf --config-path config/arm9/config.yaml --lcf-file build/linker.lcf --objects-file build/objects.txt
   • Put your own mwccarm.exe and mwldarm.exe under tools/mwccarm/<VERSION>/. On Windows they run as is. In WSL use Wine or wibo.
   • Unzip xpack-arm-none-eabi-gcc-15.2.1-1.1-win32-x64.zip into tools/gcc-arm/, as aletheia does. It gives arm-none-eabi-as for library assembly.
   • Run pip install capstone pyelftools ndspy, the list khdays-decomp gives.
   • Write tools/configure.py to make build.ninja, like khdays-decomp does. Write tools/gate.sh: run ninja, then tools/dsd.exe check modules --config-path config/arm9/config.yaml -f. Run it in Git Bash.
   Prompt for ClaudeCopy

   GOAL: Make `tools/gate.sh` rebuild every module byte for byte from the delinked objects.
   READ FIRST: `SCOPE.md`, `CLAUDE.md`, https://github.com/AetiasHax/ds-decomp (README commands)
   FENCE: Edit only `tools/configure.py`, `tools/gate.sh` and `.gitignore`. `extract/`, `config/` and `tools/mwccarm/` are read-only. Do not edit checksums.
   CHECK: Run `bash tools/gate.sh`. Done means `dsd check modules` passes every module with exit code 0.
   BUDGET: Stop after 3 failed tries on one module.
   IF BLOCKED: Stop. Paste the failing module and the first wrong offset.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the gate output. 3) Files changed.

   Done whenbash tools/gate.sh exits 0 and dsd check modules reports every module as matching.

   Proof this works: https://github.com/Yokimitsuro/khdays-decomp, https://github.com/AetiasHax/ds-decomp

3. Map the code and mark the SDK

   You build the ledger and set the SDK aside. SDK code is the same across many games. Name it by signature so nobody decompiles it by hand.

   • tools/dsd.exe sig apply --config-path config/arm9/config.yaml --all names known SDK functions.
   • Compare SDK code with the matched NitroSDK in pret's pokediamond. khdays-decomp did this.
   • Make ledger/functions.csv: address, size, mode, module, SDK yes or no, status, owner.
   • Load the ROM in Ghidra 11.2.1 with dsd-ghidra. Do not auto-analyze. Run SyncDsd.java.
   • Set up objdiff with tools/dsd.exe objdiff --config-path config/arm9/config.yaml. It writes objdiff.json.
   • Write the assembly files once with tools/dsd.exe dis --config-path config/arm9/config.yaml --asm-path asm/. Workers read these, not the ROM.
   Prompt for ClaudeCopy

   GOAL: Fill `ledger/functions.csv` and mark every SDK and library function.
   READ FIRST: `config/` (read-only), `SCOPE.md`, `CLAUDE.md`
   FENCE: Edit only `tools/make_ledger.py`, `ledger/` and `config/*/symbols.txt` name fields that `dsd sig apply` changed. Do not rename by guess.
   CHECK: Run `python tools/make_ledger.py && bash tools/gate.sh`. Done means the gate still passes and every row has a status and an SDK flag.
   BUDGET: Stop after 45 minutes with no progress.
   IF BLOCKED: Stop. List the ranges you could not classify.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Counts: game, SDK, library, unknown. 3) Paste the gate output. 4) Files changed.

   Done whenEvery function has a row with status and SDK flag, and bash tools/gate.sh still passes.

   Proof this works: https://github.com/Yokimitsuro/khdays-decomp, Egg of Time, https://github.com/AetiasHax/dsd-ghidra

4. Match one small function end to end

   You prove the whole loop on one tiny function. Write C, compile it with the right mwccarm, link it, and pass the gate. This also tests that your check can fail.

   • Pick a small leaf function, one that calls nothing.
   • Get a first draft from m2c or Ghidra, then fix it by hand or with Claude.
   • Check the score with objdiff-cli diff -u <UNIT> -o - <FUNC>. It prints JSON, and match_percent must be 100.
   • Always pass -o. Without it, objdiff-cli diff opens an interactive screen that Claude cannot use.
   • Add the file to the build and run bash tools/gate.sh.
   • Break the file on purpose and confirm the gate fails. Then undo it.
   Prompt for ClaudeCopy

   GOAL: Match function <FUNC> at <ADDR> in C and link it into the build.
   READ FIRST: `CLAUDE.md`, the `asm/` file that holds <FUNC>, `ledger/functions.csv` row for <ADDR>
   FENCE: Edit only `src/<MODULE>/<FUNC>.c` and the build file list. `asm/`, `config/` and the gate are read-only. No inline assembly.
   CHECK: Run `objdiff-cli diff -u <UNIT> -o - <FUNC>` then `bash tools/gate.sh`. Done means `match_percent` is 100 in the JSON and the gate passes. Then break the file once and show the gate fails.
   BUDGET: Stop after 8 attempts with no better score.
   IF BLOCKED: Stop. Paste the best score and the differing lines.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both check outputs and the failed-on-purpose output. 3) Files changed.

   Done whenThe function scores 100% in objdiff, the gate passes with it linked, and a broken copy makes the gate fail.

   Proof this works: https://github.com/encounter/objdiff, https://github.com/matt-kempster/m2c

5. Run the bulk matching loop

   Workers match functions in packets of neighbors from one module. Each worker has its own git worktree and build folder. After each batch the lead rebuilds the whole game and checks every module.

   • Cut the ledger into packets of next-door functions from one module, as aletheia does.
   • Give each worker one packet and one worktree: git worktree add ../wt-<id> -b match/<id>.
   • Workers run objdiff-cli diff -u <UNIT> -o - <FUNC> per function and park near misses in src/pending/ with notes.
   • The lead merges one packet at a time and runs bash tools/gate.sh after each merge.
   • Bigger packets pay off. Three workers on big batches did about 323 bytes a minute in pokeheartgold Single Screen.
   Prompt for ClaudeCopy

   GOAL: Match the open functions in packet <PACKET_ID> (<MODULE> <START>-<END>).
   READ FIRST: `CLAUDE.md`, `docs/compiler-notes.md`, `ledger/functions.csv` rows for the packet
   FENCE: Work only in worktree <WORKTREE_PATH> with build folder `build-<PACKET_ID>`. Edit only `src/<MODULE>/` files for addresses in the packet. Never edit `asm/`, `config/`, headers others own, or the gate. No inline assembly or register pins.
   CHECK: For each function run `objdiff-cli diff -u <UNIT> -o - <FUNC>`. Then run `bash tools/gate.sh`. Done means each claimed function shows `match_percent` 100 and the gate passes in your worktree.
   BUDGET: At most 6 attempts per function. Stop the packet after 3 hours.
   IF BLOCKED: Park the best attempt in `src/pending/` with a note on the differing lines. Move to the next function.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Table: function, result, attempts. 3) Paste the gate output. 4) Files changed.

   Done whenEvery claimed function scores 100%, and bash tools/gate.sh passes on the merged main branch.

   Proof this works: https://github.com/Project-Holon/aletheia, pokeheartgold Single Screen, https://github.com/tangosdev/sm64ds-decomp

6. Work the hard tail

   Some functions resist. You hand them to the hard job type with all past attempts. You also keep a shared file of compiler habits.

   • Collect each near miss with its best attempt and its diff.
   • Try changing the order of local variables. mwccarm often gives registers in that order.
   • Look for a small helper the compiler folded inline.
   • Write each new compiler habit in docs/compiler-notes.md, not in one function's notes.
   • A few functions need an instruction C cannot make, like clz. khdays-decomp has two such game functions. Mark those as allowed assembly and count them apart.
   Prompt for ClaudeCopy

   GOAL: Match hard function <FUNC> at <ADDR>, or prove what blocks it.
   READ FIRST: `CLAUDE.md`, `docs/compiler-notes.md`, `src/pending/<FUNC>.c`, `docs/notes/<FUNC>.txt`
   FENCE: Edit only `src/<MODULE>/<FUNC>.c`, `src/pending/<FUNC>.c` and `docs/notes/<FUNC>.txt`. No inline assembly, no `asm("")` barriers, no forced registers.
   CHECK: Run `objdiff-cli diff -u <UNIT> -o - <FUNC>` then `bash tools/gate.sh`. Done means `match_percent` is 100 and the gate passes.
   BUDGET: Stop after 10 attempts with no better score.
   IF BLOCKED: Stop. Name the exact differing instructions and which cause you think it is.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Best score and attempt count. 3) Any new compiler habit for `docs/compiler-notes.md`.

   Done whenThe function matches and the gate passes, or the notes name the exact blocking instructions.

   Proof this works: pokeheartgold Single Screen, https://github.com/Yokimitsuro/khdays-decomp

7. Make the C readable and portable

   Matched C is often full of address names and copied structs. You name things, share structs in headers, and fix pointer types. Every change must keep the bytes the same.

   • Move each shared struct into one header. Keep a change only if the file still compiles to the same bytes.
   • Rename func_0201xxxx names from evidence such as strings, callers or SDK names.
   • Turn integer stand-ins for pointers into real pointer types. aletheia did this for its port.
   • Count only real C as progress. Count assembly apart, like khdays-decomp does.
   Prompt for ClaudeCopy

   GOAL: Move struct <STRUCT> into `include/<HEADER>.h` and use it in all its files.
   READ FIRST: `CLAUDE.md`, `docs/naming.md`, the file list from `grep -rl <STRUCT_HINT> src/`
   FENCE: Edit only those files and `include/<HEADER>.h`. Do not change behavior. Do not touch files outside the list.
   CHECK: Run `bash tools/gate.sh`. Done means every module still matches byte for byte.
   BUDGET: Stop after 3 failed tries on one file.
   IF BLOCKED: Stop. Name the file and the field that breaks the match.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the gate output. 3) Files changed. 4) Files skipped and why.

   Done whenThe struct lives in one header, all users include it, and the gate still passes.

   Proof this works: https://github.com/Project-Holon/aletheia, https://github.com/Yokimitsuro/khdays-decomp

8. Port the decomp to PC

   You compile the matched C for PC with a layer that stands in for the DS SDK and hardware. The decomp stays read-only and pinned. Build 32-bit first, then fix pointers for 64-bit.

   • Add the decomp as a pinned, read-only submodule. Port changes go in your port layer or a build-time source rewrite.
   • Write shims for NitroSDK and NitroSystem, one file per module. Unknown functions abort and print their DS address.
   • Build 32-bit first so structs keep DS layout. DQIV and early KH Days Port did this.
   • Fix DS habits: signed char, divide by zero returns 0, calls that pass too few arguments.
   • Use a read-only Ghidra script to record register values at bad calls. KH Days Port fixed those calls from that list.
   • Replay scripted input and compare key frames with a reference before you trust a fix. KH Days Port used DeSmuME save states as its reference.
   Prompt for ClaudeCopy

   GOAL: Make the PC build reach <MILESTONE> (for example, the title menu) with golden run <ROUTE>.
   READ FIRST: `CLAUDE.md`, `docs/port-plan.md`, `PROGRESS.md`, `external/<DECOMP>/` (read-only)
   FENCE: Edit only `port/`, `sdk_shims/`, `stubs/` and `CMakeLists.txt`. Never edit `external/<DECOMP>/`. A stub must abort and print its DS address.
   CHECK: Run `python tools/check.py --golden <ROUTE>`. Done means the route reaches <MILESTONE>, its key frames match the reference, and all unit tests pass.
   BUDGET: Stop after 3 failed fixes on one crash, or 60 minutes with no new evidence.
   IF BLOCKED: Stop. If a fix needs a decomp change, say which file and why. Do not make it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check output. 3) Files changed. 4) Stubs still aborting.

   Done whenpython tools/check.py --golden <ROUTE> passes, and git -C external/<DECOMP> status --porcelain prints nothing.

   Proof this works: KH Days Port, Eidos, Pokémon Platinum PC Port, DQIV Recompiled

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

Path A: one crash, one missing function, or one wrong scene is one unit. Each unit has a golden run that must pass. Recompiler changes are one unit at a time, because every change regenerates all of gen/. Path B: one packet of next-door functions from one module is one unit. Its check is 100% in objdiff, then dsd check modules on the merged branch.

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

- At the start of every session, read `SCOPE.md`, `PROGRESS.md` and `notes/dead-ends.md`. Only the owner edits `SCOPE.md`.
- Never edit files in `gen/`. They are output. Fix `tools/recomp.py` or its entry lists and regenerate.
- The Path A check is `python tools/check.py`. A speed-up that changes lockstep or a golden run is a bug.
- The Path B verdict is `bash tools/gate.sh`, which ends with `dsd check modules -f`. An `objdiff` score is evidence, not proof.
- `external/`, `asm/`, `config/`, `extract/`, reference images and checksum files are read-only.
- Never pick overlay code by address alone. Every call into an overlay slot goes through the live-byte check.
- A stub must abort and print its DS address. Never return a made-up value to get past a screen.
- No inline assembly, `asm("")` barriers or forced registers in matched C. Allowed assembly exceptions are listed in `docs/asm-exceptions.md`.
- Never commit ROMs, `extract/`, `gen/`, BIOS, firmware, saves or compiler binaries. Run `git status` before every commit.
- Never say a test ran if it did not. Paste the exact command and its real output.
- Run at most one gameplay test per change unless I ask for more. Builds and file checks are always fine.
- In a worktree, use absolute paths and your own `build-<id>` folder.
- Write every failed idea with what you measured in `notes/dead-ends.md`.
- Do not send AI-written code to pret or any project whose rules forbid it.

Keep the context small

• Give Claude one packet or one crash per session, with addresses and file paths. Do not paste whole assembly files.
• Use a subagent to read big logs or traces and report the first difference only.
• Keep CLAUDE.md short. Point to docs/compiler-notes.md and docs/runtime-plan.md by topic.
• Generated C is hundreds of megabytes. Tell Claude to search gen/ with grep, never to open it whole.
• Clear the chat between units. The ledger and PROGRESS.md carry the state.

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> (<REGION>, SHA-1 <HASH>) can be done, by which path, and what exists already.
READ FIRST: https://decomp.wiki/platforms/nintendo-ds, https://pret.github.io/, `notes/prior-work.md`
FENCE: Read and search only. Create only `notes/feasibility.md`. Do not download game files or tools.
CHECK: Run `grep "^## " notes/feasibility.md` and `git status --porcelain`. Done means only that file is new, and it has one heading for each of: prior decomps, prior recomps, sister games, likely `mwccarm` versions, ARM7 needs, online or wireless parts, and a yes or no for Path A and Path B.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say which question has no answer and what would answer it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Your advice in three lines. 3) Every claim with its URL. 4) Risks.

GOAL: Write `docs/overlays.md` and fill the module column of `ledger/functions.csv`.
READ FIRST: `config/arm9/config.yaml`, `config/arm9/overlays/` (read-only), `extract/arm9_overlays/`
FENCE: Edit only `docs/overlays.md`, `ledger/functions.csv` and `tools/make_ledger.py`. Do not rename symbols.
CHECK: Run `python tools/make_ledger.py --verify`. Done means every overlay is listed with its load address and size, and overlays that share an address are grouped.
BUDGET: Stop after 45 minutes with no progress.
IF BLOCKED: Stop. List overlays you could not place.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Number of overlays and shared-address groups. 3) Paste the verify output.

GOAL: Clear the dispatch misses listed in `logs/dispatch_misses.log` for route <ROUTE>.
READ FIRST: `CLAUDE.md`, `logs/dispatch_misses.log`, `docs/overlays.md`
FENCE: Edit only the entry lists (`faltan.txt`, `faltan7.txt` or `config/*.toml`). Never edit `gen/`. Do not add addresses you cannot tie to a real call.
CHECK: Regenerate, rebuild, and run `python tools/check.py --golden <ROUTE>`. Done means the miss log is empty for that route and older golden runs still pass.
BUDGET: Stop after 3 regenerate rounds with no fewer misses.
IF BLOCKED: Stop. List the addresses that keep missing and which overlay they belong to.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Misses before and after. 3) Paste the check output. 4) Files changed.

GOAL: Match <FUNC> at <ADDR> in <MODULE>.
READ FIRST: `CLAUDE.md`, `docs/compiler-notes.md`, the `asm/` file that holds <FUNC>, two matched functions that call it or that it calls
FENCE: Edit only `src/<MODULE>/<FUNC>.c`. Make each attempt a new file in `scratch/<FUNC>/`. No inline assembly, no forced registers.
CHECK: Run `objdiff-cli diff -u <UNIT> -o - <FUNC>`. Done means `match_percent` is 100 in the JSON. Then run `bash tools/gate.sh`, which must pass.
BUDGET: At most 6 attempts. Change one thing per attempt.
IF BLOCKED: Stop. Keep the best attempt in `src/pending/` and note the differing lines.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Best score and attempt count. 3) Paste both outputs. 4) Files changed.

GOAL: Start <N> workers on the next <N> open packets.
READ FIRST: `CLAUDE.md`, `ledger/functions.csv`, `ledger/claims.csv`
FENCE: Edit only `ledger/claims.csv`. Each worker gets its own worktree at <WT_ROOT>/<PACKET_ID> and its own `build-<PACKET_ID>` folder. Do not give two workers the same module.
CHECK: Run `python tools/claims.py check`. Done means no two claims overlap, and each worker got the Path B unit card with its packet filled in.
BUDGET: Stop after 20 minutes of setup.
IF BLOCKED: Stop. Say which packet or worktree failed.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Table: worker, packet, worktree path. 3) Paste the claims check.

GOAL: Find the cause of <SYMPTOM> on route <ROUTE>. Do not fix it yet.
READ FIRST: `CLAUDE.md`, `notes/dead-ends.md`, `logs/<ROUTE>.log`
FENCE: Read code and run tools only. You may add logging under `runtime/debug/`. Do not change behavior.
CHECK: Run your lockstep or frame compare for <ROUTE>, for example `python tools/check.py --lockstep <ROUTE>`. Done means you name the first frame and address where the runs differ, with the log lines that prove it.
BUDGET: 60 minutes or 3 theories, whichever comes first.
IF BLOCKED: Stop. List the theories you ruled out and how.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) First difference with frame, CPU and address. 3) The proven cause or the best theory. 4) A fix plan for me to approve.

GOAL: Check that the work on branch <BRANCH> is real.
READ FIRST: `CLAUDE.md`, `git diff main...<BRANCH>`
FENCE: Read and run checks only. Do not edit files.
CHECK: Rerun `bash tools/gate.sh` (Path B) or `python tools/check.py` (Path A) yourself. Search the diff for: edits in `gen/`, `asm/`, `config/` or checksum files; inline assembly; stubs that return fixed values; disabled tests; files outside the fence.
BUDGET: 30 minutes.
IF BLOCKED: Stop. Say what you could not check.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) PASS or FAIL. 2) Paste your own check output. 3) Each problem with file and line.

GOAL: Give me a status report from the ledger, not from memory.
READ FIRST: `ledger/functions.csv`, `PROGRESS.md`, `notes/parking-lot.md`
FENCE: Read only. Do not edit files.
CHECK: Run `python tools/make_ledger.py --summary` and the gate or golden runs. Use only their numbers.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say which number you could not get.
REPORT: 1) Matched or fixed counts per module. 2) Gate or golden run result pasted. 3) Open blockers. 4) Top three next units.

GOAL: Write what the next session needs into the repo files.
READ FIRST: `PROGRESS.md`, `notes/dead-ends.md`, `git status`, `git log -5`
FENCE: Edit only `PROGRESS.md` and `notes/dead-ends.md`. Do not change code.
CHECK: Run `git status --porcelain`. Done means only `PROGRESS.md` and `notes/dead-ends.md` changed, and `PROGRESS.md` has: branch and commit, what was done, last check output, open unit, exact next command, and blockers.
BUDGET: 10 minutes.
IF BLOCKED: Stop. Say what you could not record.
REPORT: 1) DONE or PARTIAL. 2) Paste the new `PROGRESS.md` section.

GOAL: Give me a plain answer on <UNIT>: can it be done now, yes or no?
READ FIRST: `PROGRESS.md`, `notes/dead-ends.md`, the last three reports for <UNIT>
FENCE: Read only. Do not try another fix.
CHECK: Run `git status --porcelain`. Done means it prints nothing, and each statement points to a log, a diff or a check output.
BUDGET: 15 minutes.
IF BLOCKED: Say so. That is a valid answer.
REPORT: 1) BLOCKED or NOT BLOCKED. 2) What exactly cannot be done and why. 3) Two or three options, each with its cost. 4) What you need from me.

GOAL: Ask me before you leave the fence for <UNIT>.
READ FIRST: `SCOPE.md`, `CLAUDE.md`
FENCE: Do not make the change. Write the request only.
CHECK: Run `git status --porcelain`. Done means it prints nothing, and the request names the file, the exact change, why the fence blocks the work, and how we will check it.
BUDGET: 10 minutes.
IF BLOCKED: Stop and tell me.
REPORT: 1) The file and change. 2) Why it is needed, with proof. 3) The risk. 4) The check that will prove it safe.

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 decomp or symbol list already exists. With one, Path A can start from known function edges.
• How many overlays and functions the game has. Games in this guide range from about 9,000 functions (Chrono Trigger) to 35,197 (Pokemon Black).
• How much the game uses 3D, wireless or the ARM7. Each adds runtime work.
• How many mwccarm versions the game mixes, and whether you can get each one.
• How strong your check is. Lockstep and frame compares save weeks of guessing.

The facts behind these numbers

Projects reviewed (13)

The top-starred project for each of the top 12 DS games on RecompLauncher, plus one more project whose developer says AI was used. RecompLauncher lists 24 DS projects for 20 games.

What each project teaches

What we could not check

• The dates when sm64ds-decomp, khdays-decomp and aletheia reached 100% were not found. Only their state on 2026-11-13 was read.
• Whether khdays-decomp used Claude. Only an indirect sign was seen: a .claude memory link in its CONTRIBUTING.md. The aletheia README does say Claude Code helps.
• How much work DS Kart Recompiled, SoulSilver Recomp and Egg of Time did before their first public commit.
• Whether m2c reads the assembly that dsd dis writes. The m2c README expects GNU as format, and the dsd README says dis targets no assembler. The -t arm-mwcc-c pairing was not tested.
• The list of DS compilers on decomp.me. Its API did not answer a plain download.
• Nothing in this guide was installed or run on this machine. Commands were checked against READMEs, release pages and source code only.
• The objdiff-cli diff -u <UNIT> -o - <FUNC> form was read from the v3.8.3 source, not run.
• Whether dsd, objdiff and the Windows compilers work the same inside WSL2 as on Windows.
• Whether the WSL2 problem with mwldarm still happens. Only the pokeheartgold Single Screen INSTALL.md reports it. Upstream pret recommends WSL2.
• How to save a melonDS frame at an exact frame number. No card shows it. The reviewed projects used ndsref, DeSmuME save states or their own interpreter.
• Whether llvm-mingw clang on Windows can build the ARM test functions. DQIX Modern ran those tests only on Linux.
• Whether dsd rom extract needs the ARM7 BIOS for some games. Its README lists --arm7-bios for decryption. Egg of Time extracted without it.
• Where you can legally get mwccarm. This guide only says you must supply your own copy.
• The tools/check.py, tools/gate.sh, tools/make_ledger.py and tools/claims.py scripts in the steps are ones you write. Their names follow the reviewed projects, but they are not ready-made tools.
• The time ranges for one person at 10 to 15 hours a week are estimates. No reviewed project reports hours worked.

Sources

• ds-decomp (dsd) README and releases
• dsd-ghidra README
• objdiff README
• ndsrecomp README
• melonDS README
• Decompedia: Nintendo DS
• Rodrigo Copetti: Nintendo DS Architecture
• GBATEK hardware reference
• aletheia README (Pokemon Black matching decomp)
• khdays-decomp README
• sm64ds-decomp README
• pret/pokeplatinum README and AGENTS.md
• pret/pokediamond README
• m2c README
• wibo README
• ndspy README
• GhidraMCP README
• llvm-mingw releases
• metroskrew repository
• skills.sh matching-decomp (DS notes)
• dsd init options in source (v0.12.1)
• objdiff-cli diff options in source (v3.8.3)
• khdays-decomp CONTRIBUTING.md
• pokeheartgold Single Screen INSTALL.md
• Decompedia: Metrowerks (MWCC)
• Microsoft: Install WSL
• xPack arm-none-eabi-gcc
• minicoro README
• Git for Windows