PlayStation 2 decomp guide

What this system is like

The PS2 has a MIPS chip, the same family as the N64 and PS1. Good tools can read it. On RecompLauncher, 88 of the 97 PS2 projects had their first release in October or November 2026. 62 of the 97 are flagged for AI use.

For Path A, most projects use static recompilation with PS2Recomp. Ghidra finds the functions, the tool writes C++, and you finish the runtime. The runtime is the stand-in for the console. The CPU code is the easy part. The VU1 vector chip, the graphics chip (the GS) and the sound chip take most of the time.

For Path B, PS2 games were built with known compilers. Sony's ee-gcc and Metrowerks mwcps2 are both on decomp.me. splat supports PS2. With AI agents, Tenkaichi 3 matched 95% of its main program in three days. gt4-decomp matched 98% of its functions in under six weeks. A port of a decomp still needs a full PC layer after that.

Most Path A work runs on Windows. Path B's matching build runs in WSL. You need your own disc. PCSX2 also needs a BIOS dumped from your own console.

Two paths

Path A: Get it running on PC

Ghidra finds every function in the ELF. PS2Recomp turns them into C++. You build that with a runtime that stands in for the console. Then you fix one missing call or crash at a time, and compile VU1 programs ahead of time. Fixes go in overrides, never in the machine-made code.

1. Scope the game and look for prior work

   Pick one game and one exact disc. The boot file on the disc is named after the serial, like SLUS_215.90. Search for work that already exists. Many PS2 games already have a port or a decomp. Write SCOPE.md and get it approved before any code.

   • In WSL, run sudo apt install 7zip. Copy SYSTEM.CNF out of your disc to a folder outside any repo: 7z x mygame.iso SYSTEM.CNF -o$HOME/ps2disc.
   • Read the BOOT2 line in SYSTEM.CNF. It names the boot file. Copy that file out the same way, then hash it: sha1sum $HOME/ps2disc/SLUS_XXX.YY. Put the serial and hash in SCOPE.md.
   • Search GitHub and RecompLauncher for the game name plus recomp, decomp and port. Check sister games on the same engine too.
   • Check for a prototype, demo or debug build. Some keep debug symbols, which the EE add-on for Ghidra can read. The ICO decomp rebuilds a prototype and a demo as well as five retail discs.
   • Write SCOPE.md: goal, serial, hash, technique, first milestone and its check, what is out of scope, what Claude must never edit.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a PC port of <GAME> (serial <SERIAL>) by static recompilation with `PS2Recomp`.
   READ FIRST: `notes/disc-facts.md` (my serial, `SYSTEM.CNF` text and the boot ELF SHA-1). The `PS2Recomp` README at https://github.com/ran-j/PS2Recomp.
   FENCE: Write only `SCOPE.md` and `notes/prior-work.md`. Do not open, copy or upload any game file. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `grep -cE '^## (Goal|Game and hash|Technique|Milestone 1|Out of scope|Never edit)' SCOPE.md`. Done means it prints 6. Each line in `notes/prior-work.md` has a URL you opened.
   BUDGET: Stop after 45 minutes of searching.
   IF BLOCKED: If you cannot tell whether prior work exists, stop and say so. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The prior-work list with URLs. 3) Your recommended technique and why. 4) Open questions for me.

   Done whengrep -cE '^## (Goal|Game and hash|Technique|Milestone 1|Out of scope|Never edit)' SCOPE.md prints 6, the file holds the serial and SHA-1, and its last line is Approved: <date> in your words.

   Proof this works: GTA Vice City Stories recomp (one supported executable, checked by SHA-1), God of War Native PC (games/<id>/game.toml holds the hashes), https://github.com/ran-j/PS2Recomp, Project Cane (the author asks for debug builds with symbols before trying Sly 2 and Sly 3)

2. Set up the repo, the tools and one check

   Make a repo that holds only your own code. The disc image and anything taken from it stay in ignored folders. Install PS2Recomp, a compiler, CMake and Ninja. Then write one script that builds and one that checks.

   • Make folders: game/ (your disc files, ignored), config/, overrides/, generated/ (ignored), notes/, tools/.
   • Add game/, generated/, *.iso, *.elf and build/ to .gitignore. Add a pre-commit hook that refuses files from those folders.
   • Pull the boot file into the ignored folder: 7z x mygame.iso SLUS_XXX.YY -ogame.
   • Build PS2Recomp as its README says: git clone --recurse-submodules https://github.com/ran-j/PS2Recomp.git, cd PS2Recomp, cmake -S . -B out/build, then cmake --build out/build --config Debug.
   • First install Visual Studio 2022 Build Tools with the Desktop development with C++ workload. The PS2Recomp README says it is tested mainly with MSVC. The first build fetches its own libraries and took about 8 minutes in this site's test.
   • Write tools/check.py. It checks the ELF hash, builds, and runs the game headless for a set time. It prints PASS or FAIL.
   • Write a short CLAUDE.md and an empty PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Create the repo layout, the build script and the one check command for the <GAME> recomp.
   READ FIRST: `SCOPE.md`, `CLAUDE.md`, the `PS2Recomp` README Build section.
   FENCE: Edit only `tools/`, `.gitignore`, `.githooks/`, `CMakeLists.txt` and `PROGRESS.md`. Never copy anything from `game/` into tracked folders. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --hash-only`. Done means it prints the expected SHA-1 and PASS. Then run `git status --ignored` and show that `game/` is ignored.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: If a tool will not install or build, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --hash-only prints PASS, and git status shows no game file as tracked.

   Proof this works: DW5XL Recomp (.githooks scan for game-derived files; CI check that no game data is tracked), https://github.com/ran-j/PS2Recomp, This site's hands-on test (2026-11-13): PS2Recomp built on Windows with Visual Studio Build Tools 2022 and printed its usage

3. Map the ELF in Ghidra

   The recompiler needs to know where every function starts. Retail games have no names, so Ghidra finds the functions. Load the boot ELF with the Emotion Engine extension. Export the function list with the script that comes with PS2Recomp.

   • Install JDK 21 and Ghidra 12.1.4. Then add the matching ghidra-emotionengine-reloaded zip through File > Install Extensions.
   • Import game/SLUS_XXX.YY with the language r5900:LE:32:default. Run auto-analysis.
   • Run ps2xRecomp/tools/ghidra/ExportPS2Functions.java. Save the CSV map and the TOML in config/.
   • Add functions Ghidra missed. They hide behind pointers and vtables (tables of function pointers). GTA VCS added 833 this way.
   • Feed only real function starts to the recompiler, not branch labels. Labels made GTA VCS output 67k files with copied code.
   • Mark Sony library code (libgraph, libvu0, libvif, libcdvd, libpad, libmc) in notes/functions.csv with a status column.
   Prompt for ClaudeCopy

   GOAL: Produce the function map for <GAME> and a ledger of every function with address, size, library tag and status.
   READ FIRST: `SCOPE.md`, `config/ghidra_export.csv`, `notes/ghidra-setup.md`. Use the Ghidra MCP read-only.
   FENCE: Write only `config/funcmap.csv` and `notes/functions.csv`. Do not rename or retype anything in the Ghidra project. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/validate_map.py config/funcmap.csv`. Done means no overlaps, no starts inside another function, and the count matches the ledger.
   BUDGET: Stop after 2 hours or 3 failed fixes of the same overlap.
   IF BLOCKED: If Ghidra is not reachable, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Function count, library count, and the validator output. 3) Files changed. 4) Addresses you were unsure about. 5) New parking-lot items.

   Done whenconfig/funcmap.csv passes the validator, and notes/functions.csv has one row per function with a status.

   Proof this works: DW5XL Recomp (ExportPS2Functions.java, validate_function_map.py), GTA Vice City Stories recomp (find_missing_functions.py), GT4 Recomp (1,105 entries added from gt4-decomp)

4. Run the recompiler and build

   Now PS2Recomp turns the whole ELF into C++. The output is machine-made and is never edited by hand. You build it with the runtime. The first goal is a clean build, not a running game.

   • Write config/recomp.toml with general.input, general.ghidra_output and general.output = "generated/".
   • Keep general.patch_syscalls = false, as the README recommends.
   • Run ps2_recomp config/recomp.toml.
   • Build the output with the runtime: cmake -S . -B build -G Ninja then cmake --build build.
   • Put the build in a short folder like C:\ps2work. Long Windows paths broke the God of War build.
   • Record the generated file count and build time in PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Recompile the ELF with `ps2_recomp` and get a clean build of the generated C++ with the runtime.
   READ FIRST: `config/recomp.toml`, `config/funcmap.csv`, the `PS2Recomp` README Configuration section.
   FENCE: Edit only `config/recomp.toml` and `CMakeLists.txt`. Never edit files in `generated/`. If generated code is wrong, report which instruction and address. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --build`. Done means the build ends with no errors and you paste the last 20 lines.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: If the recompiler itself crashes or emits code that cannot compile, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --build ends with no errors, and no file in generated/ was edited by hand.

   Proof this works: GoW PC port (ps2_recomp build-gen/recomp.toml; generated runner files never hand-edited), https://github.com/ran-j/PS2Recomp

5. Boot to the first frame

   This is first light. The game starts, the runtime answers its system calls, and a window shows a picture. Expect many missing calls. Fix them one at a time. A stub that just returns success hides a problem, so use one only to learn which calls matter.

   • Run with a minimal config and no aggressive skipping, as the PS2Recomp README says.
   • Fix hard blockers first: function not found, a syscall TODO, or a disc read stub.
   • Bind stripped library calls by address, for example sceCdRead@0x00123456 in stubs.
   • Use ret0@0xADDR only to sort calls by importance. Replace each one with a real version later.
   • Let the game's own SDK code run when you can. DW5XL found the runtime's versions of libgraph, libvu0 and libvif were wrong for its game.
   • Save a screenshot of the first frame and the log line that proves it.
   Prompt for ClaudeCopy

   GOAL: Get <GAME> to show its first frame (the <LOGO_OR_SCREEN>) from a cold start.
   READ FIRST: `PROGRESS.md`, the last run log `logs/run-latest.txt`, the `PS2Recomp` README section Recommended Iteration Loop.
   FENCE: Edit only `overrides/` and the `stubs` list in `config/recomp.toml`. Never edit `generated/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --boot --seconds 60`. Done means it saves `out/first-frame.png` and the log has no fatal error.
   BUDGET: Fix one blocker per try. Stop after 5 tries without a new blocker passed.
   IF BLOCKED: If a blocker needs hardware you cannot model from docs or PCSX2, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --boot --seconds 60 saves a first-frame picture, and every temporary ret0 stub is listed in PROGRESS.md.

   Proof this works: DW5XL Recomp (HLE stubs for libgraph, libvu0, libvif were wrong; game SDK code runs as guest code), https://github.com/ran-j/PS2Recomp

6. Grind: one crash or missing call per task

   Now play further, one problem at a time. Each fix goes in an override bound to a function address, not in generated code. Compare with PCSX2 to see what the real game does. Write each finding down with its address.

   • Write each problem as one issue: what happens, where it stops, the log line.
   • Write a test that fails on the bug first. DW5XL makes this a hard rule.
   • Fix it in overrides/, bound by address. An override calls the original for anything it does not replace. Register it with PS2_REGISTER_GAME_OVERRIDE from ps2xRuntime/include/game_overrides.h.
   • Never rely on code after the original function returns. Recompiled functions can pause and resume mid-way.
   • Run PCSX2 with your own BIOS for reference. Compare screenshots at the same point.
   • Add every address you learn to notes/game-internals.md, with how you found it.
   Prompt for ClaudeCopy

   GOAL: Fix issue <ISSUE_ID>: <ONE_LINE_SYMPTOM>.
   READ FIRST: `notes/issues/<ISSUE_ID>/spec.md`, `notes/game-internals.md`, the failing log `logs/<ISSUE_ID>.txt`.
   FENCE: Edit only `overrides/`, `tests/` and `notes/issues/<ISSUE_ID>/`. Never edit `generated/` or a test's pass rule. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: First show the new test fails. Then run `python tools/check.py --test <ISSUE_ID>` and `python tools/check.py --regress`. Done means both pass.
   BUDGET: Stop after 3 failed fixes or 90 minutes without new evidence.
   IF BLOCKED: If the cause is in the recompiler, not the game, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe issue's test failed before the fix and passes after, and the full regression run still passes.

   Proof this works: DW5XL Recomp (test first, must fail on the bug), GoW PC port (overrides by address call the original), GTA Vice City Stories recomp (hook rule; findings in docs/game-internals.md), https://github.com/ran-j/PS2Recomp (Game Override Hooks section)

7. Make VU1 and the graphics fast and right

   The PS2 draws through VU1, a small vector chip with its own programs called microcode. Interpreting it is slow. Projects compile the microcode ahead of time and keep the interpreter as a checker. Every change must give the same pictures.

   • Record the VU1 programs the game uploads during a scripted run. God of War plays itself hidden for four minutes to do this.
   • Compile them ahead of time. Keep the interpreter and a switch to compare, like PS2X_VU1_LIFT_VERIFY=1 in DW5XL.
   • Save frames from the same scripted run before and after. Compare them pixel by pixel.
   • Try paraLLEl-GS as a reference renderer. GTA VCS kept it opt-in because it hung one GPU.
   • Turn off fused multiply-add: compile with -ffp-contract=off and no fast-math, as ICO PC does. Bit-exact checks depend on it.
   • Measure frame time before and after each change on the same PC.
   Prompt for ClaudeCopy

   GOAL: Compile VU1 program <VU_KEY> ahead of time and prove it draws the same as the interpreter.
   READ FIRST: `notes/vu1-programs.md`, `tools/compare_frames.py --help`, the scripted run `runs/<RUN>.args`.
   FENCE: Edit only `runtime/vu1/` and `tests/vu1/`. Keep the interpreter path and its switch. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --vu-verify <VU_KEY>` and `python tools/compare_frames.py runs/<RUN>`. Done means zero differences in both.
   BUDGET: Stop after 3 failed tries or if frames differ for a reason you cannot explain.
   IF BLOCKED: If an instruction's behaviour is unclear in the docs and in PCSX2, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe verify switch reports no difference, and the frame compare shows zero changed pixels on the scripted run.

   Proof this works: DW5XL Recomp (compare_frames.py, lift verify switches), GT4 Recomp (--vu1-verify), God of War Native PC (recorded VU1 code compiled ahead of time)

8. Harden: regression runs, packaging, no game data

   Lock in what works. Record scripted runs that a machine can replay with no person. Store only picture hashes in the repo. Ship a builder that makes the game on the player's PC from the player's own disc.

   • Record runs with timed button presses. God of War uses GOW_PAD_TEST=1 and a log marker that proves gameplay was reached.
   • Store only picture CRCs (short checksums) for each run. Stuntman keeps 79 for its title-to-stunt run.
   • Run every recorded run after any renderer, memory, DMA or VU change.
   • Never run tests on the player's real memory card. Give each run its own data folder.
   • Package a builder: recompiler, sources and compiler. It checks the disc by hash and compiles locally.
   • Run git ls-files and confirm no ELF, ISO, generated C++ or frame dump is tracked.
   Prompt for ClaudeCopy

   GOAL: Add a regression set of <N> scripted runs and make `python tools/check.py --regress` run them all.
   READ FIRST: `PROGRESS.md`, `runs/README.md`, `CLAUDE.md`.
   FENCE: Edit only `runs/`, `tools/` and `PROGRESS.md`. Store hashes only, never frames or game data. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/check.py --regress` twice on a clean checkout. Done means the same PASS both times.
   BUDGET: Stop after 3 failed tries at one run.
   IF BLOCKED: If a run is not repeatable, stop and show the two differing results. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check.py --regress passes twice in a row on a clean checkout, and git ls-files shows no game-derived file.

   Proof this works: Stuntman (regress.py with recorded picture CRCs), God of War Native PC (scripted smoke run with a log marker), GTA Vice City Stories recomp (VCS_DATA_DIR keeps tests off the user's card)

Path B: Full decomp for porting

splat cuts the ELF into assembly. You write C that the game's own compiler turns back into the same bytes. A per-function diff checks each piece, and the full build must match byte for byte. Then you add a PC layer and port it, as Tenkaichi 3, ICO and RECVX did.

1. Scope: compiler, prior work and size

   A matching decomp needs the game's original compiler. On PS2 that is usually a Sony ee-gcc build or Metrowerks mwcps2. Find which one, and check for a decomp that already exists. Count the functions so you know the size.

   • Search GitHub for <game> decomp and decomp.dev. Many PS2 decomps already exist, like Sly 1, Kingdom Hearts and PaRappa 2.
   • Look at the strings in the ELF for a compiler version. gt4-decomp names ee-gcc 2.96 build 001003-1 with -O2 -G0. Tenkaichi 3 tested its guess against every public ee-gcc and 118 flag sets.
   • Compare with the PS2 compilers on decomp.me. Its list has ee-gcc2.9, ee-gcc2.95, ee-gcc2.96, ee-gcc3.2 and many mwcps2 builds.
   • Note C or C++. C++ games add vtables and name mangling.
   • Write SCOPE.md with the serial, hash, compiler guess and function count.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a matching decomp of <GAME> (serial <SERIAL>) and name the most likely compiler.
   READ FIRST: `notes/disc-facts.md`, the compiler list at https://github.com/decompme/compilers/tree/main/platforms/ps2.
   FENCE: Write only `SCOPE.md` and `notes/prior-work.md`. Do not download compilers or game files. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `grep -cE '^## (Compiler|Evidence|Function count|Prior work)' SCOPE.md`. Done means it prints 4. The file names one compiler with its evidence (a string, a code pattern or a sister game) and a function count from Ghidra.
   BUDGET: Stop after 1 hour.
   IF BLOCKED: If two compilers fit equally, stop and list both with evidence. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Compiler guess and evidence. 3) Prior work with URLs. 4) Function count. 5) Open questions.

   Done whengrep -cE '^## (Compiler|Evidence|Function count|Prior work)' SCOPE.md prints 4, the file holds the hash, and its last line is Approved: <date> in your words.

   Proof this works: gt4-decomp README (compiler identified as ee-gcc 2.96 001003-1), Tenkaichi 3 Decomp (compared its ee-gcc 2.96 with every public ee-gcc), https://github.com/decompme/compilers

2. Set up splat and a byte-exact build in WSL

   splat cuts the ELF into assembly files. Your build puts them back together. The rebuilt file must match the original byte for byte before you write any C. This runs in WSL.

   • In WSL: sudo apt install python3-venv binutils-mips-linux-gnu.
   • Make a venv in the project: python3 -m venv .venv, then .venv/bin/pip install -U "splat64[mips]". Run source .venv/bin/activate in each new shell. This route was tested here on Ubuntu 24.04.
   • Copy SLUS_XXX.YY into the project. Add it, *.rom, asm/ and build/ to .gitignore.
   • Run python3 -m splat create_config SLUS_XXX.YY. It writes the .yaml and the .rom, and prints the objcopy command it used.
   • Put that command in your configure script: mips-linux-gnu-objcopy -O binary --gap-fill=0x00 SLUS_XXX.YY SLUS_XXX.YY.rom.
   • Split: python3 -m splat split SLUS_XXX.YY.yaml.
   • Write configure.py that writes build.ninja. Add a check rule that runs cmp against the original.
   • Get the compiler from the decompme/compilers release named compilers into tools/. Keep it out of git. For an mwcps2 game, run mwccps2.exe through wibo, as recvx-decomp does on Linux.
   • If ee-gcc crashes when it calls its own assembler, compile to assembly first. Then assemble with the MIPS binutils and a prelude file, as Tenkaichi 3 does.
   Prompt for ClaudeCopy

   GOAL: Make `python3 configure.py && ninja` rebuild <SERIAL> from split assembly, byte for byte.
   READ FIRST: `SCOPE.md`, `SLUS_XXX.YY.yaml`, the splat Quickstart-Elf page https://github.com/ethteck/splat/wiki/Quickstart-Elf.
   FENCE: Edit only `configure.py`, the `.yaml`, `symbol_addrs.txt` and `tools/`. Never edit files in `asm/` by hand; change the yaml and split again. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 configure.py && ninja && cmp build/SLUS_XXX.YY.rom SLUS_XXX.YY.rom`. Done means `cmp` prints nothing and exits 0.
   BUDGET: Stop after 3 failed tries at the same mismatch.
   IF BLOCKED: If `splat` cannot split a section, stop and show the error. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenninja then cmp against the original ROM exits 0 with all code still as assembly.

   Proof this works: Tenkaichi 3 Decomp (configure.py, ninja, cmp of SLUS_216.78.rom), https://github.com/ethteck/splat, https://github.com/ethteck/splat/wiki/Quickstart-Elf, This site's hands-on test (2026-11-13): splat 0.50.1 installed in a venv on WSL Ubuntu 24.04 and split a test ROM

3. Map files, symbols and library code

   Cut the code into files the way the developers did. Name what you can prove. Mark Sony SDK and middleware code, like CRI sound and movie code, so nobody decompiles it by hand. Save all of it as a ledger.

   • Find file edges from gaps, alignment and string groups. Add them as subsegments in the .yaml.
   • Put names in symbol_addrs.txt. Mark guesses with // guess, as Tenkaichi 3 does.
   • Tag SDK and middleware objects. Tenkaichi 3 matched them as library objects, not by hand.
   • List VU microcode separately. It is assembled from listings, not compiled from C. Tenkaichi 3 builds its nine VU1 programs with vuasm.py.
   • Write notes/functions.csv: address, size, file, library tag, status.
   Prompt for ClaudeCopy

   GOAL: Split the code into source files and write the function ledger for <SERIAL>.
   READ FIRST: `SLUS_XXX.YY.yaml`, `symbol_addrs.txt`, Ghidra read-only through the MCP.
   FENCE: Edit only the `.yaml`, `symbol_addrs.txt` and `notes/functions.csv`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 configure.py && ninja && cmp build/SLUS_XXX.YY.rom SLUS_XXX.YY.rom`. Done means `cmp` exits 0 and every function is in the ledger once.
   BUDGET: Stop after 2 hours or when `cmp` fails twice in a row.
   IF BLOCKED: If a split breaks the match and you cannot see why, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe byte check still passes, and notes/functions.csv lists every function with a file and a status.

   Proof this works: Tenkaichi 3 Decomp (config/symbols/*.txt with evidence and guesses marked), ICO PC (game code in one folder per original programmer)

4. Match the first unit end to end

   Prove the whole loop on one small file. Write C, compile it with the original compiler, and compare each function. When the file matches and the full build still passes, the tools are right.

   • Pick a small file with few functions and no floats.
   • Get a draft from m2c: python3 <M2C_DIR>/m2c.py -t mipsee-gcc-c -f <func> asm/nonmatchings/<file>/<func>.s. Run m2c.py by its full path or from its own folder.
   • Compare per function with objdiff or a script like Tenkaichi 3's fdiff.py.
   • Replace INCLUDE_ASM lines with C only when the diff is clean.
   • Run the full byte check. A function match alone is not proof.
   Prompt for ClaudeCopy

   GOAL: Match every function in `src/<FILE>.c` against the original.
   READ FIRST: `asm/nonmatchings/<FILE>/`, `include/`, `notes/compiler.md`.
   FENCE: Edit only `src/<FILE>.c` and its header. No inline assembly, no register pins, no edits to `asm/`, the yaml or the expected hash. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 tools/fdiff.py src/<FILE>.c` for each function, then `python3 configure.py && ninja`. Done means every function prints OK and `cmp` passes.
   BUDGET: At most 5 different serious tries per function. Then leave it as `INCLUDE_ASM` with your best try under `#if 0`.
   IF BLOCKED: If the toolchain itself seems wrong, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenEvery function in the file prints OK in the per-function check, and the full cmp check passes.

   Proof this works: Tenkaichi 3 Decomp (fdiff.py OK per function plus the cmp gate), https://github.com/encounter/objdiff, https://github.com/matt-kempster/m2c, This site's hands-on test (2026-11-13): m2c turned a splat MIPS function into C on Windows

5. Grind: many workers on separate address ranges

   Now the bulk work. Give each worker its own file list and address range. Workers run only the per-function check. One lead session owns the full build, splat and git. This is how Tenkaichi 3 reached 95% in three days.

   • Write one shared brief: rules, compiler notes, report format.
   • Give each worker its own git worktree and a disjoint set of files.
   • Workers run only fdiff.py. They never run configure.py, splat, ninja or git.
   • Workers read assembly from a frozen copy, not the live asm/ folder.
   • The lead merges, runs the full cmp gate, then commits.
   • Order work easy first. Later, pick functions most like ones already matched.
   Prompt for ClaudeCopy

   GOAL: Lead session: hand out the next <N> files from `notes/functions.csv` to <N> workers and merge their verified results.
   READ FIRST: `notes/functions.csv`, `docs/agent_rules.md`, `docs/brief.md`.
   FENCE: Workers edit only their own files in their own worktree. Only you run `configure.py`, `ninja` and git. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: After each merge run `python3 configure.py && ninja && python3 scripts/progress.py`. Done means `cmp` passes and the ledger matches the progress numbers.
   BUDGET: Stop the batch when 2 merges in a row fail the gate.
   IF BLOCKED: If two workers touched the same file, stop and tell me. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Gate output and new progress percent. 3) Files merged. 4) Files sent back. 5) New parking-lot items.

   Done whenAfter each batch, the full cmp gate passes and notes/functions.csv shows the new matches.

   Proof this works: Tenkaichi 3 Decomp (one integrator, up to 10 agents, per-function checker only), gt4-decomp (98.0% of functions matched with AI agents)

6. The hard tail: permuter and behaviour tests

   Some functions will not match after real effort. Try the permuter on near misses. For the rest, prove the C behaves the same instead. A behaviour test runs the original bytes and your C on the same random inputs and compares.

   • In WSL, add permuter_settings.toml to the project root with build_system = "ninja". Its default assembler flags are for the N64, so also set assembler_command for your PS2 as.
   • Import a near miss: ./import.py src/<file>.c asm/nonmatchings/<file>/<func>.s. Then run ./permuter.py -j <N> nonmatchings/<func>/.
   • Check every permuter result by hand. Tenkaichi 3 found a score of 0 that was wrong.
   • Build a behaviour test like Tenkaichi 3's gdt.py. Run each unmatched function on 4,000 seeds.
   • Compare return value, outgoing calls and memory writes.
   • Mark these functions as behaviour-checked, not matched, in the ledger.
   Prompt for ClaudeCopy

   GOAL: Resolve function <FUNC> in `src/<FILE>.c`: match it, or prove its C behaves the same.
   READ FIRST: `notes/hard/<FUNC>.md` (earlier tries), the diff from `tools/fdiff.py`.
   FENCE: Edit only `src/<FILE>.c` and `notes/hard/<FUNC>.md`. No inline assembly. No changes to the checker or its masks. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 tools/fdiff.py src/<FILE>.c <FUNC>`. If it is not OK, run `python3 tools/difftest.py src/<FILE>.c <FUNC> 4000`. Done means OK, or 4,000 seeds with no difference.
   BUDGET: Stop after 60 serious variants without progress. Write what you learned.
   IF BLOCKED: If the function reads data the test cannot model, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe function prints OK, or the behaviour test passes 4,000 seeds and the ledger says behaviour-checked.

   Proof this works: Tenkaichi 3 Decomp (permuter, differential interpreter, 60-variant rule), https://github.com/simonlindholm/decomp-permuter

7. Harden: the gate, data sections and a second check

   Make the build the only judge. Run the full gate before every commit. Check data and float constants, because the per-function diff cannot see them. Have a fresh session hunt for cheats.

   • Run the cmp gate before every commit outside docs/. Tenkaichi 3 added this after two broken commits.
   • Compare the bits of every float constant with the original data.
   • Block edits to asm/, the expected hash and the check script with a PreToolUse hook. When the hook exits with code 2, Claude Code blocks the edit.
   • Grep for banned tricks: inline asm and changed checker settings. Also count FAKE MATCH tags. Tenkaichi 3 marks about 21 openly, so a person can review them.
   • Write the progress numbers from the build, never by hand.
   Prompt for ClaudeCopy

   GOAL: Audit the last <N> commits for fake matches and broken rules.
   READ FIRST: `git log -<N> --stat`, `CLAUDE.md`, `docs/agent_rules.md`.
   FENCE: Read only. Write findings to `notes/audit-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 configure.py && ninja` from a clean checkout and grep for inline asm and checker edits. Done means the gate passes and each finding cites a file and line.
   BUDGET: Stop after 1 hour.
   IF BLOCKED: If the gate fails on a clean checkout, stop at once. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Gate output. 3) Findings with file and line. 4) Commits to revert. 5) New parking-lot items.

   Done whenA fresh checkout passes the gate, and the audit file lists every finding with a file and line.

   Proof this works: Tenkaichi 3 Decomp (gate before every commit; float constant rule), gt4-decomp (progress written by tools/update_readme.py, never by hand), https://code.claude.com/docs/en/hooks (exit code 2 blocks a PreToolUse call)

8. Port: compile the decomp for PC

   Matching PS2 code does not run on a PC by itself. You add a port layer: one module for each piece of PS2 hardware or Sony library. Every change to game code sits behind a flag, with the PS2 original kept.

   • Wrap every game code change in #ifdef TARGET_PC with the original under #else.
   • Make one stand-in per piece: libcdvd, libpad, libmc, SIF, SPU2, GS and VU1.
   • Compile game code with -fno-strict-aliasing -fwrapv -ffp-contract=off -fsigned-char, as ICO and RECVX do.
   • Keep pointers 4 bytes or audit every struct. ICO found records grew from 0xC0 to 0xF0 bytes.
   • Model PS2 floats. The EE FPU has no infinities or NaNs. Tenkaichi 3 got NaNs on the first battle frame with plain PC floats.
   • Build with GCC or Clang with the GNU ABI. RECVX found MSVC and Clang lay out its data wrong; ICO bans MSVC.
   Prompt for ClaudeCopy

   GOAL: Make the port layer stand-in for <MODULE> (for example `libpad`) and boot the PC build past it.
   READ FIRST: `port/README.md`, `notes/functions.csv`, the ps2tek section on the hardware under <MODULE> at https://psi-rockin.github.io/ps2tek/.
   FENCE: Edit only `port/<MODULE>/` and lines inside `#ifdef TARGET_PC` blocks. Keep the PS2 original under `#else`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `cmake --build build-pc && ctest --test-dir build-pc` and `python3 tools/golden.py --until <MARKER>`. Done means tests pass and the marker appears.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: If the game relies on hardware you cannot model from docs, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe PC build passes its tests and reaches the named point in a scripted run, and the PS2 build still passes cmp.

   Proof this works: ICO PC (port layer per hardware module; EE semantics flags), RECVX Enhanced Port (#ifdef TARGET_PC, GCC only), Tenkaichi 3 Decomp (soft-float PS2 model, __ptr32 pointers)

9. Port golden runs against PCSX2

   Prove the PC build plays the same as the console. Record a replay in PCSX2 and play it back on the PC build. Compare game state frame by frame. Also rebuild with a different memory layout and check nothing changes.

   • Record inputs and a save state in PCSX2. Tenkaichi 3 compared health and positions bit for bit.
   • Hash key game state each frame and compare builds, like BT3_HASH.
   • Build twice with padding before code and data. RECVX compares every 10th frame up to frame 1800.
   • A layout difference can mean retail code reads memory it never wrote. RECVX found two such bugs and fixed them on PC. Keep the game's own bugs in the matching code; Tenkaichi 3 logs them in docs/known_bugs.md.
   • Add each run to CI with synthetic data, or to a local regression set that needs your disc.
   Prompt for ClaudeCopy

   GOAL: Make the PC build replay <REPLAY> with the same per-frame state as PCSX2.
   READ FIRST: `runs/<REPLAY>/`, `tools/compare_hash.py --help`, `docs/known_bugs.md`.
   FENCE: Edit only `port/` and `TARGET_PC` blocks. Never change the replay or the reference hashes. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python3 tools/compare_hash.py runs/<REPLAY>`. Done means every frame's hash matches.
   BUDGET: Stop after 3 failed fixes of the first differing frame.
   IF BLOCKED: If the first difference comes from a retail bug, stop and describe it. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython3 tools/compare_hash.py runs/<REPLAY> reports zero differing frames, and the layout test shows identical frames.

   Proof this works: Tenkaichi 3 Decomp (PCSX2 replay compare, BT3_HASH), RECVX Enhanced Port (layout_check.sh with a padded build)

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 PS2 the natural unit is small. For Path A, one task is one crash, one missing system call, or one VU1 program. For Path B, one task is one source file inside one address range. Every unit has its own check: a failing test that turns green, a frame compare, or the per-function diff. One lead session owns the full build, the game runs and git. Workers never run the whole game or the full gate.

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` and `PROGRESS.md` at the start of every session.
- Never edit files in `generated/`. Fix the config, an override, or the recompiler instead.
- The one check is `python tools/check.py`. A claim of PASS must paste its output and name its log.
- Never change a test's pass rule, a reference hash or a recorded picture CRC to make a check pass.
- Game files stay in `game/` and are never committed: no ISO, ELF, IRX, generated C++, disassembly or frame dumps.
- Overrides are bound by function address and call the original for anything they do not replace.
- Do not add a stub that returns success for missing hardware. Implement it from docs and PCSX2, with a test.
- Ghidra is read-only for workers. Do not rename, retype or save the project.
- Write every address you learn into `notes/game-internals.md`, with how you found it. Mark it verified or guess.
- Workers run only `tools/fdiff.py`. Only the lead runs `configure.py`, `splat`, `ninja` and git.
- In a worktree, use absolute paths and your own scratch folder. Kill only the process ID you started.
- Ask before launching the game if another copy is running. Never test on my real memory card.

Keep the context small

• Give Claude an address and a file path, not pasted disassembly. Let it read the one function it needs.
• Keep CLAUDE.md short and point to docs/ by topic. Long rule files get skipped.
• Use a subagent to read a big log or the Ghidra export, and have it report ten lines back.
• Clear the chat after each task. State lives in PROGRESS.md and the ledger, not in the chat.
• Batch Ghidra lookups. Headless Ghidra takes 30 to 60 seconds to start each time.
• Turn off verbose logging and frame dumps unless the task needs them. They slow the game and fill the disk.

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> (serial <SERIAL>) can be ported to PC, by which technique, and what already exists.
READ FIRST: `notes/disc-facts.md`, https://github.com/ran-j/PS2Recomp, https://github.com/decompme/compilers/tree/main/platforms/ps2.
FENCE: Write only `notes/feasibility.md` and a draft `SCOPE.md`. Do not touch game files. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Write one claim per line starting with `- `. Run `grep -c '^- ' notes/feasibility.md` and `grep -cE '^- .*(https://|disc-facts)' notes/feasibility.md`. Done means both print the same number.
BUDGET: Stop after 1 hour.
IF BLOCKED: If the game uses a custom language or an unknown compiler, stop and say so. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Recommended path: recomp, matching decomp, or port of an existing decomp. 3) Prior work with URLs. 4) Risks: VU1 code, overlays, C++. 5) Questions for me.

GOAL: Build `notes/functions.csv` for <SERIAL> with address, size, library tag and status for every function.
READ FIRST: `config/ghidra_export.csv`, Ghidra through the MCP (read-only), `SCOPE.md`.
FENCE: Write only `notes/functions.csv` and `notes/map-notes.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python tools/validate_map.py notes/functions.csv`. Done means no overlaps and the count matches the export plus any added entries.
BUDGET: Stop after 2 hours.
IF BLOCKED: If more than 5% of the code has no function, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Fix one issue: <SYMPTOM> at <ADDRESS_OR_LOG_LINE>.
READ FIRST: `notes/issues/<ID>/spec.md`, `logs/<ID>.txt`, `notes/game-internals.md`.
FENCE: Edit only `overrides/`, `tests/` and `notes/issues/<ID>/`. Never edit `generated/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Show the new test failing first. Then run `python tools/check.py --test <ID>` and `python tools/check.py --regress`. Done means both pass.
BUDGET: Stop after 3 failed fixes.
IF BLOCKED: If the bug is in the recompiler, stop and describe the instruction. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Match the functions in `src/<FILE>.c` (address range <START>-<END>).
READ FIRST: `docs/agent_rules.md`, `notes/compiler.md`, the frozen asm snapshot `snap/<DATE>/asm/`.
FENCE: Edit only `src/<FILE>.c` and your own symbol file. No inline asm. Do not run `configure.py`, `splat`, `ninja` or git. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python3 tools/fdiff.py src/<FILE>.c`. Done means OK for each function you claim.
BUDGET: Five serious tries per function. Then `INCLUDE_ASM` with your best try under `#if 0` and a note.
IF BLOCKED: If a header change is needed, stop and ask. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) fdiff output. 3) Functions OK versus `INCLUDE_ASM`. 4) Guessed names. 5) Doc notes marked verified or inferred.

GOAL: Pick the next <N> unmatched files from `notes/functions.csv` and start one worker per file in its own worktree.
READ FIRST: `notes/functions.csv`, `docs/agent_rules.md`, `docs/brief.md`.
FENCE: Assign disjoint files only. Edit only `notes/assignments.md`. Workers follow `docs/agent_rules.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: When workers report, merge one at a time and run `python3 configure.py && ninja`. Done means `cmp` passes after every merge.
BUDGET: Stop the batch if two merges in a row fail the gate.
IF BLOCKED: If a worker reports a toolchain problem, pause the batch. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Gate output after the last merge. 3) Files merged and files returned. 4) New progress percent. 5) Parking-lot items.

GOAL: Find the cause of <SYMPTOM>. Do not fix it yet.
READ FIRST: `logs/<RUN>.txt`, the GS frame dump `dumps/<FRAME>`, the PCSX2 screenshot `ref/<FRAME>.png`.
FENCE: Read only, plus new files in `notes/debug/<ID>/`. Turn on tracing only for the one subsystem you test. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Name the first address or frame where the PC build and PCSX2 differ, with the log lines that prove it.
BUDGET: Stop after 2 hours or 3 disproved theories.
IF BLOCKED: If you cannot reproduce it twice, stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The proven cause with evidence. 3) Theories ruled out and how. 4) The smallest fix you propose. 5) Parking-lot items.

GOAL: Check that the work in commits <RANGE> is real.
READ FIRST: `git log <RANGE> --stat`, `CLAUDE.md`, `tools/check.py`.
FENCE: Read only. Write findings to `notes/verify-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: From a clean checkout run `python tools/check.py --regress` (Path A) or `python3 configure.py && ninja` (Path B). Look for edited tests, hashes, CRCs, generated files, inline asm and new success stubs.
BUDGET: Stop after 1 hour.
IF BLOCKED: If the check fails on a clean checkout, stop and report that first. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output. 3) Each finding with file and line. 4) Commits to revert. 5) Parking-lot items.

GOAL: Report project status with numbers from the ledgers only.
READ FIRST: `PROGRESS.md`, `notes/functions.csv`, `notes/parking-lot.md`, the last regress log.
FENCE: Read only. Write only `notes/status-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Every number cites the file it came from. Run `python tools/check.py --regress` and paste the summary line.
BUDGET: Stop after 20 minutes.
IF BLOCKED: If two files disagree, stop and show both. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Milestone status. 3) Counts: matched, stubs left, open issues. 4) Top three blockers. 5) Parking-lot size.

GOAL: Write what the next session needs into the ledger files.
READ FIRST: `PROGRESS.md`, `notes/handoff.md`, this session's work.
FENCE: Edit only `PROGRESS.md`, `notes/handoff.md` and `notes/dead-ends.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the project check (`python tools/check.py --regress` or `python3 configure.py && ninja`) and `git status --short`. Paste both into `notes/handoff.md`. Done means it also names the next task and every dead end tried.
BUDGET: Stop after 15 minutes.
IF BLOCKED: If you are unsure what is done, mark it PARTIAL and say why. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Next task in one line. 3) Last check output. 4) Dead ends added. 5) Files changed.

GOAL: Give me a plain answer on <TASK>: can it be done now, and if not, why.
READ FIRST: `notes/issues/<ID>/work.md`, the last three check outputs.
FENCE: Read only. Write only `notes/issues/<ID>/blocked.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the task's own check command once more and paste its output. Start with DONE, PARTIAL or BLOCKED. Every claim cites a log or file.
BUDGET: Stop after 20 minutes.
IF BLOCKED: If the honest answer is no, say no first. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) Outcome word. 2) What cannot be done and why. 3) What was tried. 4) Two or three options with cost. 5) What you need from me.

GOAL: Ask me before leaving the fence for <CHANGE>.
READ FIRST: `SCOPE.md`, the issue that led here.
FENCE: Change nothing. Write only `notes/scope-requests.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `git status --short`. Done means only `notes/scope-requests.md` changed, and the request names the files, the reason, the risk and the check.
BUDGET: Stop after 15 minutes.
IF BLOCKED: If the change touches `generated/` or the check script, say so in the first line. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) The change in one line. 2) Why it is needed now. 3) Files it touches. 4) Its check. 5) What happens if I say no.

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

• Prior work. A game with an existing decomp, a sister game or a working runtime fork can take days instead of weeks.
• VU1 microcode and the GS. Games that draw through many VU1 programs need recording, compiling and frame checks.
• C or C++. C++ games add vtables, hidden functions and harder matching.
• The original compiler. A known ee-gcc build on decomp.me is fast to set up. An odd one can block Path B.
• Overlays and extra binaries. Tenkaichi 3 had a second binary; DW5XL had three overlays.
• Your machine. A full build of the generated C++ took 10 to 90 minutes in the reviewed projects.

The facts behind these numbers

Projects reviewed (15)

The top-starred project for each of the top 12 PS2 games on RecompLauncher, plus three AI-flagged projects. RecompLauncher lists 97 PS2 projects for 76 games. Two of the 15 cover God of War and one is a launcher.

What each project teaches

What we could not check

• Whether 7z reads every PS2 disc image, such as dual-layer DVDs. Tenkaichi 3 uses it; DW5XL uses bsdtar.
• How many hours a week the dated projects took, and how much private work came before their first public commit.
• Whether the ICO decomp used AI. Its README does not say.
• Whether Windows users can run the ee-gcc compiler builds natively. This guide assumes WSL, as the reviewed decomps do.
• The tools/check.py, validate_map.py, difftest.py, golden.py and compare_hash.py scripts are ones you write. Their names follow the reviewed projects but are not standard tools.
• Which other compilers PS2 games used besides ee-gcc and mwcps2. SN Systems tools were not checked.
• No step was run on a real PS2 game here. PS2Recomp, splat, m2c, wibo and the permuter were only installed and started, or run on test files.
• PS2Recomp was built on Windows only. Its CI also builds on Ubuntu, but WSL was not tested here.
• The assembler_command the permuter needs for PS2 code. Its defaults are for the N64; the right PS2 flags were not worked out here.
• The Path B time ranges. Only one dated AI project (Tenkaichi 3) reached a playable port, so the confidence is low.

Sources

• PS2Recomp README
• Ghidra README
• ghidra-emotionengine-reloaded README
• GhidraMCP README
• PCSX2 README
• PCSX2 BIOS setup page
• ps2tek hardware reference
• splat README
• splat Quickstart-Elf (PS2)
• decomp.me PS2 compilers
• binutils-mips-ps2-decompals
• objdiff README
• m2c README
• decomp-permuter README
• ps2-port-engine README
• paraLLEl-GS README
• llvm-mingw README
• gt4-decomp README
• recvx-decomp README
• Sly 1 decomp README
• ICO decomp README
• Ubuntu 7zip package
• Tenkaichi 3 agent rules
• DW5XL Recomp
• Ghidra 12.1.4 README (JDK 21)
• PS2Recomp analyzer and Ghidra workflow
• wibo README
• Claude Code hooks reference
• 7-Zip output folder switch
• Visual Studio downloads