PlayStation 5 decomp guide

What this system is like

The PlayStation 5 uses the same kind of chip as your PC. It is an x86-64 chip. So the game's code can run on your PC with no translation. A tool called AnyPS5 makes this work. Its relinker rewrites the game file into a Windows program. A relinker is a tool that changes how a program is packed, not what it does. AnyPS5 also brings new copies of the console's system parts, such as files, pads, sound and saves.

Graphics are the big job. The PS5 graphics chip gets its own kind of commands and shaders. A shader is a small program that runs on the graphics chip. AnyPS5 turns both into Vulkan, a PC graphics system. One project swapped in the graphics part of KytyPS5 instead, because it ran faster for that game.

This method is very new. AnyPS5 started in August 2026. By mid-November, only a handful of games had their own port repos. RecompLauncher lists one PS5 game: Dead Cells. Most of the work happens inside the shared tool, not in each game's repo.

A full decomp of a PS5 game has never been done. Nobody has the exact Sony compiler, so byte matching is not possible. Path B shows the only real route. You swap the game's code for your own C, one function at a time, while the game keeps running. It is a very long job.

Two paths

Path A: Get it running on PC

You unwrap your dump's eboot.bin into a plain ELF. The AnyPS5 relinker turns it into a Windows .exe. The game then loads AnyPS5's new system libraries as DLL files. You list every import the game needs and fill in the missing ones. Last, you fix crashes and graphics bugs one at a time.

1. Scope the game and dump it

   Pick one game and one exact version. Check if AnyPS5 already runs it. Look for an existing port of the same game. Write the plan in SCOPE.md.

   • Dump your own copy of the game. Note the title ID, such as PPSA28997, and the version from sce_sys/param.json.
   • Save the SHA-256 hash of eboot.bin with py -3 -c "import hashlib;print(hashlib.sha256(open('eboot.bin','rb').read()).hexdigest())". Keep the dump outside your repo.
   • Search the AnyPS5 Game bring-up discussions for your title ID. Each game has one thread with test reports.
   • Check the KytyPS5 compatibility list at https://kytyps5.github.io/ for the same game.
   • Search GitHub for the title ID and the game name. Six games already have PS5 port repos or branches.
   • Write SCOPE.md: game, title ID, version, hash, goal, the first milestone and its check, and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a native PC port of <GAME> (<TITLE_ID>, version <VERSION>) built on AnyPS5.
   READ FIRST: My notes in `notes/dump-info.md` (title ID, version, eboot hash). The AnyPS5 Game bring-up discussion for <TITLE_ID>, if any: <DISCUSSION_URL>. These candidate repos: <REPO_URLS>.
   FENCE: Edit only `SCOPE.md`, `notes/feasibility.md` and `notes/parking-lot.md`. Do not open the game dump. Write no code.
   CHECK: Run `py -3 -c "import re,sys;t=open('SCOPE.md',encoding='utf-8').read();sys.exit(0 if all(h in t for h in ['## Goal','## Game and hash','## Technique','## First milestone and check','## Out of scope','## Never edit']) else 1)"`. Done means it exits 0.
   BUDGET: 45 minutes.
   IF BLOCKED: Stop. Say what you could not find. Do not fill gaps with guesses.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not act on them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The check output. 3) Files changed. 4) Existing ports or branches of this game, with links. 5) Open questions for me.

   Done whenSCOPE.md has all six sections, names the exact version and hash, and you approved it.

   Proof this works: Dead Cells PS5 Native (one tested version, PPSA15552 01.000.000), SonsOfSparta-PS5 Native (one tested version, PPSA28997 01.008.001), Astro Bot native PC port (checked AnyPS5, KytyPS5, SharpEmu and shadPS4 before writing code), https://github.com/boykopovar/AnyPS5 (Game bring-up discussions, one thread per title)

2. Set up the tools and build AnyPS5

   You install the one compiler that works and build AnyPS5 from a pinned commit. You start with the small relinker build and its tests. Then you build the full system libraries. You also write the one check command.

   • Install the tools: winget install Kitware.CMake, winget install Ninja-build.Ninja, winget install Git.Git, winget install Python.Python.3.13.
   • Download WinLibs GCC 15.2.0 (x86_64-ucrt-posix-seh, release 15.2.0posix-14.0.0-ucrt-r7). Unzip it to C:\tools\winlibs.
   • In PowerShell, put the compiler and Git Bash first on PATH: $env:PATH = "C:\tools\winlibs\mingw64\bin;C:\Program Files\Git\cmd;C:\Program Files\Git\usr\bin;$env:PATH".
   • Set $env:SSL_CERT_FILE = "C:\Program Files\Git\ucrt64\etc\ssl\certs\ca-bundle.crt". Without it, the first configure can fail to download FFmpeg with status 60.
   • Clone to a short path: git clone --recursive https://github.com/boykopovar/AnyPS5.git C:\a5. Long paths break the build. Keep your own repo, with your scripts and notes, in a separate folder.
   • In C:\a5, build the relinker alone: cmake -S . -B build-relinker -G Ninja -DCMAKE_BUILD_TYPE=Release -DANYPS5_RELINKER_ONLY=ON -DBUILD_TESTING=ON, then cmake --build build-relinker --parallel.
   • Run its tests: ctest --test-dir build-relinker --output-on-failure --no-tests=error. ctest --test-dir build-relinker -N must list input_magic. If not, CMake did not find Python.
   • Build everything: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DBUILD_TESTING=ON, then cmake --build build --parallel and cmake --build build --target libs --parallel. This makes build\core\relinker\relinker.exe and the system libraries.
   • Copy libgcc_s_seh-1.dll, libstdc++-6.dll and libwinpthread-1.dll from the WinLibs bin folder into C:\a5\build\core\libs\libs.
   • In your repo, write tools/check.py. It rebuilds libs, runs ctest --test-dir C:\a5\build --no-tests=error -R <TEST_PATTERN>, and runs the import audit once step 3 has made registry files. Write CLAUDE.md and docs/PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Make `py -3 tools/check.py` build AnyPS5's relinker and libs at commit <ANYPS5_COMMIT> and run its tests, with one exit code.
   READ FIRST: `SCOPE.md`, AnyPS5 `docs/dev/BUILD.md` (sections Relinker only, Requirements, Commands, Windows setup and troubleshooting), AnyPS5 `AGENTS.md`. AnyPS5 is cloned at `C:\a5`.
   FENCE: Edit only `tools/check.py`, `CLAUDE.md`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Do not edit AnyPS5 source. Do not install anything; tell me what is missing.
   CHECK: Run `py -3 tools/check.py`. Done means exit code 0, the output shows the ctest test count (run with `--no-tests=error`), and `C:\a5\build\core\relinker\relinker.exe` and the `.prx` files in `C:\a5\build\core\libs\libs` exist.
   BUDGET: Stop after 3 failed builds with the same error, or 60 minutes.
   IF BLOCKED: Stop. Paste the first error line and the compiler path from `where g++`. Do not switch compilers on your own.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The last 20 lines of the check output. 3) Files changed. 4) Tool versions found. 5) New parking-lot items.

   Done whenpy -3 tools/check.py exits 0 on a clean clone, and the test count it prints is above zero.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/BUILD.md (WinLibs 15.2.0, relinker-only build, runtime DLLs), Dead Cells PS5 Native (only MinGW-w64 GCC 15.2.0 works for libc.prx), Astro Bot native PC port (full AnyPS5 build about 1 hour, pinned at revision 2199ee0), https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/BUILD.md (Requirements: Python 3, Git Bash, SSL_CERT_FILE for the FFmpeg download)

3. Unwrap and relink the eboot

   You turn your dump into a plain ELF and relink it into a Windows program. A dry run first shows what will be written. You also ask the relinker for registry files, which list every import.

   • relinker below means C:\a5\build\core\relinker\relinker.exe.
   • Unwrap the main file: py -3 C:\a5\tools\unwrap_self.py <DUMP>\eboot.bin <WORK>\source\eboot.elf. It refuses files that still look encrypted.
   • Unwrap each SELF module in the dump's sce_module folder the same way, into <WORK>\source\sce_module\. The relinker skips SELF modules with a warning.
   • If you need game patches, put them in <WORK>\source\relinker-patches.toml before you relink. The relinker loads that file from the input folder. Each patch lists the expected bytes, so a wrong game version fails safely.
   • Do a dry run: relinker --dry-run --windows --registry <WORK>\source\eboot.elf <WORK>\out\game.exe. It writes nothing. On an Intel CPU, add --to-intel to this and every relink.
   • Relink for real: relinker --windows --registry <WORK>\source\eboot.elf <WORK>\out\game.exe. It writes game.registry.json, one registry per module, and the converted modules as .guest.prx files under out\app0\.
   • Lay out the run folder. Put game.exe at the top. Put the built .prx files and the three DLLs in libs\. Never put the game's own .prx files there. Copy the game's data files, its original eboot.bin and sce_sys\param.json into app0\.
   Prompt for ClaudeCopy

   GOAL: Produce `<WORK>/out/game.exe` and its registry files from my dump of <GAME>, with a script I can re-run.
   READ FIRST: `SCOPE.md`, AnyPS5 `docs/user/USAGE.md` (Input and conversion, Options, Runtime layout, Game patches). The relinker is `C:\a5\build\core\relinker\relinker.exe`. My CPU is <AMD_OR_INTEL>; on Intel, relink with `--to-intel`.
   FENCE: Edit only `tools/prepare.py`, `docs/PROGRESS.md` and `notes/parking-lot.md`. The dump at <DUMP> is read-only. Write outputs only under <WORK>. Never copy game files into the repo.
   CHECK: Run `py -3 tools/prepare.py --dump <DUMP> --work <WORK>`. Done means it exits 0, `<WORK>/out/game.exe` exists, and `<WORK>/out/game.registry.json` exists.
   BUDGET: Stop after 3 failed tries, or 45 minutes.
   IF BLOCKED: Stop. Paste the relinker's error line and exit code. If unwrap says the file looks encrypted, stop and tell me; do not try to decrypt anything.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The script output. 3) Files changed. 4) Modules unwrapped and skipped. 5) New parking-lot items.

   Done whentools/prepare.py exits 0 and makes game.exe plus its registry files from the dump, with the dump unchanged.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/docs/user/USAGE.md (unwrap_self.py, --dry-run, --registry, runtime layout), Astro Bot native PC port (relinker --windows --registry into AstroBot.exe; SELF segments signed, not encrypted), SonsOfSparta-PS5 Native (launcher prepares the game from the user's files on first start)

4. Map the imports into a ledger

   You list every import the game needs and who answers it. The audit sorts them into five groups. You save the result as your work plan. You also trace which imports the game really calls.

   • Run the audit: py -3 C:\a5\tools\import_audit.py <WORK>\out\game.registry.json <WORK>\out\game.<MODULE>.registry.json --libs C:\a5\build\core\libs\libs --modules <WORK>\source\sce_module --json docs\imports.json. Pass every module registry the relinker wrote.
   • Read the five groups: implemented, partial, stub, absent and module. Exit code 1 means something blocks loading, such as an absent import.
   • Look up an unknown NID with py -3 C:\a5\tools\nid_names.py --nid <NID>. It downloads a public name list, aerolib.csv, to a temp folder once. Pass that file to the audit with --names. ps5rs nid <name> turns a name into its NID.
   • Relink with --trace-imports. Run with APS5_TRACE_CALLS=all and APS5_TRACE_CALLS_FILE=calls.txt to see which imports the game calls most.
   • Save a table in docs/imports.md: library, name, group, and how often it is called.
   Prompt for ClaudeCopy

   GOAL: Produce `docs/imports.md`, a table of every import <GAME> needs, grouped as implemented, partial, stub, absent or module.
   READ FIRST: `SCOPE.md`, `docs/imports.json` from the audit, `<WORK>/calls.txt` from a traced run, AnyPS5 `docs/user/USAGE.md` section Import audit.
   FENCE: Edit only `docs/imports.md`, `tools/count_imports.py` and `notes/parking-lot.md`. The dump and AnyPS5 source are read-only.
   CHECK: Run `py -3 tools/count_imports.py`. Done means the five group totals in `docs/imports.md` match the audit's own summary, and every absent or stub row names its library.
   BUDGET: 60 minutes.
   IF BLOCKED: Stop. List the NIDs with no name and where you looked.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The five totals and the check output. 3) Files changed. 4) Absent and stub imports grouped by library, most called first. 5) New parking-lot items.

   Done whendocs/imports.md totals match the audit's summary, and every absent or stub import names its library.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/docs/user/USAGE.md (Import audit and Tracing system library calls), https://github.com/claimore22/ps5rs (NID search and ps5rs nid), Mewgenics-android (address and hash checked hooks into app.elf, analysis in docs/app-elf-arm64-analysis.md)

5. First light: reach the first frame

   You start the game and get real frames on screen. A repeatable run proves it. A window that opens black does not count.

   • Start it once by hand with a log. In the run folder, run $env:ANYPS5_LOG_FILE = "run.log", then .\game.exe.
   • If the game ends through its own exit, anyps5-report.json appears next to game.exe. Look for firstDraw, firstPresent and framesPresented. A crashed or killed run writes no report.
   • If it stops, read the last lines of run.log. A function that is not built names itself in the error.
   • Make the run repeatable. In your repo, make tools\my-titles.json with one entry, such as {"<TITLE_ID>": {"seconds": 60}}. On an Intel CPU, add "relink": ["--to-intel"] to the entry.
   • Run py -3 C:\a5\tools\title_run.py <TITLE_ID> --games <DUMP_PARENT> --build C:\a5\build --titles tools\my-titles.json --runs 2. It unwraps and relinks the dump by itself, then runs the game twice.
   • Read the lines <TITLE_ID> run1: <outcome>. You want rendering: frames were shown and the last one is not one flat colour. The script always exits 0, so read the outcome, not the exit code.
   Prompt for ClaudeCopy

   GOAL: Get <GAME> to show its first real frame in the relinked build, proven by the run report.
   READ FIRST: `SCOPE.md`, `docs/imports.md`, the last `run.log`, AnyPS5 `docs/user/USAGE.md` sections Run report and Saving the log to a file, `C:\a5\tools\title_run.py --help`.
   FENCE: Edit only the AnyPS5 library files for the one function that stops the boot, plus `docs/PROGRESS.md` and `notes/parking-lot.md`. Never special-case my title ID, a hash or a path. A function you cannot build calls `NotImplemented_nid_no_patch(__func__)`.
   CHECK: Run `py -3 tools/check.py`, then `py -3 C:\a5\tools\title_run.py <TITLE_ID> --games <DUMP_PARENT> --build C:\a5\build --titles tools\my-titles.json --runs 2`. Done means the check exits 0 and both runs print outcome `rendering`. `title_run.py` always exits 0, so read the outcome lines.
   BUDGET: One blocking function per session. Stop after 3 failed tries on it.
   IF BLOCKED: Stop. Paste the last 30 log lines and say which function blocks and what you need.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The title_run outcome lines, and the report fields if a report was written. 3) Files changed. 4) The next blocking function. 5) New parking-lot items.

   Done whentitle_run.py prints outcome rendering for both runs.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/tools/title_run.py (outcomes relink-failed, crashed, exited, stalled, frame-unreadable, blank, rendering; it relinks the dump itself), Astro Bot native PC port (run harness saving stdout, stderr and screenshots), Dead Cells PS5 Native (logs folder; game.err shows what failed)

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

   You fix the game one blocker at a time. Each unit is one missing system function or one crash. Each fix gets a test in AnyPS5's test suite. The import ledger and the golden run show your progress.

   • Before you start a function, run py -3 C:\a5\tools\pr_overlap.py --names <FUNCTION>. It shows whether an open pull request already covers it.
   • Pick the next absent or stub import the game really calls, from docs/imports.md.
   • Find how nearby functions in core/libs/prx/<library>/ are declared, and copy that pattern.
   • Build the behaviour from what the game does in your dump and from open code, never from Sony SDK files.
   • Rebuild with cmake --build build --target libs --parallel in C:\a5. The game loads the .prx files from build\core\libs\libs.
   • For a crash, read the Windows crash report in the log. Set APS5_CRASH_STACK_BYTES=4096 for more stack.
   • Write known gaps in docs/dev/debt/<library>.md, as AnyPS5 asks. Before you push a fix upstream, run py -3 C:\a5\tools\check_conventions.py --base origin/main. Send fixes as small pull requests.
   Prompt for ClaudeCopy

   GOAL: Implement <FUNCTION> in AnyPS5's <LIBRARY> so <GAME> gets past <SCENE>.
   READ FIRST: `docs/imports.md` row for <FUNCTION>, the crash or stop lines in `run.log`, `core/libs/prx/<LIBRARY>/` neighbours, AnyPS5 `AGENTS.md`.
   FENCE: Edit only `core/libs/prx/<LIBRARY>/`, its test, `docs/dev/debt/<LIBRARY>.md`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Never special-case a title ID, value or path. Never return a made-up success. Use no Sony SDK material.
   CHECK: Run `py -3 tools/check.py`, then `py -3 C:\a5\tools\title_run.py <TITLE_ID> --games <DUMP_PARENT> --build C:\a5\build --titles tools\my-titles.json --runs 2`. Done means the check exits 0 with the new test counted, and the run gets past <SCENE> twice.
   BUDGET: Stop after 3 failed tries or 90 minutes.
   IF BLOCKED: Stop. Say what the game passes in and what you cannot work out. Do not stub around it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output and run outcome. 3) Files changed. 4) What the game hits next. 5) New parking-lot items.

   Done whenThe check exits 0 with a new test for the function, and two golden runs get past the scene that stopped before.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/AGENTS.md (NotImplemented rule, no per-title values, debt files), https://github.com/ymatrix1/PortPS5 (implement-prx-function skill: copy neighbours, real error codes, a unit test), Astro Bot native PC port (0xC0000409 exit meant AnyPS5 threw; read stderr)

7. Fix graphics and speed

   Graphics bugs and low frame rates take the longest. AnyPS5 can record a few frames and play them back with no game running. That gives Claude a test it can run alone. Speed claims need measured numbers from the same scene.

   • Record frames: set APS5_FRAME_CAPTURE to an empty folder before you start the game.
   • Build the replay with cmake --build build --target agc_frame_replay. Put C:\a5\build\core\libs\libs\unpatched first on PATH. Then run agc_frame_replay.exe <capture> --frames <dir>. For a capture with reference images, it prints the share of identical pixels.
   • For a GPU hang, set APS5_DUMP_SUBMITS to a folder before you start the game. Build agc_pm4_replay and run agc_pm4_replay.exe <folder>, with the same PATH. It reports waits that never release.
   • Turn on validation with VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation, ANYPS5_REQUIRE_VULKAN=1 and ANYPS5_NO_SHADER_CACHE=1. Use a layer of version 1.4.335 or newer. Look for new VUID- errors, because ctest can pass while they are logged.
   • Measure speed with APS5_TRACE_SUMMARY_EVERY=30 and APS5_TRACE_BENCH=1. Then run py -3 C:\a5\tools\trace_digest.py aps5-summary.jsonl. Compare the same scene on the old and the new build. For detail, build with -DAPS5_ENABLE_TRACY=ON and connect Tracy 0.14.1.
   • If AnyPS5's renderer is too slow for your game, try the KytyPS5 graphics stack as Astro Bot did. Keep it as a patch series.
   Prompt for ClaudeCopy

   GOAL: Fix <VISUAL_BUG> in <SCENE> of <GAME>, proven by a frame replay.
   READ FIRST: `docs/PROGRESS.md` section Ruled out, my capture at <CAPTURE_DIR>, the reference image <REFERENCE_PNG>, AnyPS5 `docs/dev/BUILD.md` sections Frame capture and replay and PM4 submission replay.
   FENCE: Edit only the shader recompiler or AGC driver files that the evidence points to, plus their tests, `docs/PROGRESS.md` and `notes/parking-lot.md`. Never skip a draw or dispatch to hide the bug. Never match on a shader hash or title ID.
   CHECK: Run `py -3 tools/check.py`, then `agc_frame_replay.exe <CAPTURE_DIR> --frames <OUT_DIR>`. Done means the check exits 0, the replay's matching-pixel share rises above <TARGET> and validation logs no new `VUID-` errors.
   BUDGET: Stop after 3 failed hypotheses. Write each one in Ruled out.
   IF BLOCKED: Stop. Show the replay numbers before and after each try, and say what you would need next.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Replay output before and after. 3) Files changed. 4) Ruled-out ideas added. 5) New parking-lot items.

   Done whenThe frame replay of the bad scene shows the target share of matching pixels, with no new validation errors.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/BUILD.md (frame capture and replay, PM4 replay, Tracy), https://github.com/boykopovar/AnyPS5/blob/main/AGENTS.md (validation layer 1.4.335 or newer; speed claims use trace_digest.py from the same machine and scene), Astro Bot native PC port (AnyPS5 renderer about 9 FPS with black tiles; swapped to kyty_gpu.dll), Ghost of Yotei branch (moves forward only when a build renders the 60-frame title reference exactly)

8. Harden: golden runs, patches and release

   You build a set of golden runs so old fixes stay fixed. A golden run plays a set route with recorded pad input and must reach the same point. Then you package a launcher that builds the game from the player's own dump.

   • Make one titles file per scene, such as tools\scenes\boss.json. Each holds your title ID with a pad timeline, in the format C:\a5\tools\titles.json uses. One file can hold only one entry per title ID.
   • Run each scene after every change: py -3 C:\a5\tools\title_run.py <TITLE_ID> --games <DUMP_PARENT> --build C:\a5\build --titles tools\scenes\<SCENE>.json --runs 2.
   • Timelines run on wall-clock time, so a slow run can miss a press. Run a failed scene again before you call it broken.
   • Compare with an earlier run: add --compare <OLD_RUN>\summary.json. Runs are saved under C:\a5\build\title-runs\.
   • Check every byte patch with relinker --verify-patches relinker-patches.toml <WORK>\source\eboot.elf. A wrong version must fail, not corrupt.
   • Ship a launcher that builds the game from the player's own dump, as Dead Cells and SonsOfSparta do. Model your packaging script on Dead Cells' tools\package_release.ps1. Ship no game files.
   • Tell players to add an antivirus exclusion only for the build folder. Relinked programs get flagged.
   Prompt for ClaudeCopy

   GOAL: Make `py -3 tools/golden.py` run every golden scene of <GAME> and fail if any outcome is not `rendering`.
   READ FIRST: `SCOPE.md`, `docs/PROGRESS.md`, my scene list in `docs/golden-scenes.md`, `C:\a5\tools\title_run.py --help`, AnyPS5 `docs/user/INPUT_MAPPING.md` section Controller timelines.
   FENCE: Edit only `tools/golden.py`, my scene files in `tools/scenes/`, `docs/golden-scenes.md` and `notes/parking-lot.md`. Do not change game code or libraries in this task. Do not loosen a scene's goal to make it pass.
   CHECK: Run `py -3 tools/golden.py`. Done means it exits 0 on the current build, and exits 1 when I break one scene on purpose (rename one data file in the run folder).
   BUDGET: 90 minutes.
   IF BLOCKED: Stop. Say which scene cannot be reached by pad input alone.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Output of the passing run and the broken run. 3) Files changed. 4) Scenes covered. 5) New parking-lot items.

   Done whentools/golden.py passes on the current build and fails when one scene is broken on purpose.

   Proof this works: https://github.com/boykopovar/AnyPS5/blob/main/tools/titles.json (pad timelines per title), Astro Bot native PC port (A/B benchmarks in fixed scenes, byte patches that switch off on other versions), Dead Cells PS5 Native (package_release.ps1, launcher builds from the user's own files), https://github.com/boykopovar/AnyPS5/blob/main/docs/user/INPUT_MAPPING.md (Controller timelines run on wall-clock time)

Path B: Full decomp for porting

No one has decompiled a PS5 game. Byte matching is not possible, because Sony's exact compiler is not public. The real route is the one OpenRCT2 used on PC. You keep the original game running inside your Path A port. You replace one function at a time with your own C. A test runs the same scene with and without your function and compares the results.

1. Scope: decide if a decomp is worth it

   You measure how big the job is before you start. You count the game's functions and find the engine. If the game uses a known engine, much of the code is not the game's own. Write the numbers in SCOPE.md.

   • Run ps5rs strings <WORK>/source/eboot.elf --detect. It names the engine and middleware it finds.
   • Run ps5rs middleware <DUMP_PARENT> to list third-party modules, such as FMOD or Wwise. You do not rewrite those.
   • Count functions in Ghidra after the next step. Note the count and the total code size in SCOPE.md.
   • Check for faster ways to reach your target system first: box64 for Android, or ps5-native-mac for Apple silicon Macs.
   • Write the stop rule: what share of functions you must replace before you try a build without the eboot.
   Prompt for ClaudeCopy

   GOAL: Write `notes/decomp-feasibility.md`: function count, code size, engine and middleware, and a yes or no on starting Path B for <GAME>.
   READ FIRST: `SCOPE.md`, output of `ps5rs strings <WORK>/source/eboot.elf --detect` saved in `notes/detect.txt`, `docs/ledger.csv` if it exists.
   FENCE: Edit only `notes/decomp-feasibility.md` and `notes/parking-lot.md`. Write no code. Do not open the dump directly.
   CHECK: Run `py -3 -c "import sys;t=open('notes/decomp-feasibility.md',encoding='utf-8').read();sys.exit(0 if all(h in t for h in ['## Size','## Engine','## Faster routes','## Verdict']) else 1)"`. Done means it exits 0 and Size gives numbers, not words.
   BUDGET: 45 minutes.
   IF BLOCKED: Stop. Say which number you could not measure.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The numbers. 3) Files changed. 4) Verdict and the main risk. 5) Questions for me.

   Done whennotes/decomp-feasibility.md gives a measured function count, the engine, and a verdict you approved.

   Proof this works: https://github.com/claimore22/ps5rs (engine and middleware detection), https://github.com/error9098x/ps5-native-mac (Sons of Sparta runs on Apple M5 without a decomp), Mewgenics-android (Android through box64, with some routines made native)

2. Load the eboot into Ghidra

   You open the unwrapped ELF in Ghidra with a PS5 loader. The loader names imports by NID and marks function edges. A good load is the base for every later step.

   • Install Ghidra 12.1.3 for the PS5 loader plugin. It needs JDK 21: winget install EclipseAdoptium.Temurin.21.JDK. The newest Ghidra, 12.2, needs JDK 25 instead.
   • Clone the plugin. In its folder, set GHIDRA_INSTALL_DIR in gradle.properties to your Ghidra 12.1.3 folder. Then run <GHIDRA_DIR>\support\gradle\gradlew.bat buildExtension. The plugin has no gradlew.bat of its own.
   • In Ghidra use File, Install Extensions, and pick the zip. The analyzer is called ps5-elf-analyzer.
   • Import <WORK>\source\eboot.elf (the unwrapped file, not the relinked .exe). Run auto analysis.
   • Check the import count against the audit's count from Path A step 4.
   • GhidraMCP needs Ghidra 12.1.4. To use both, keep two Ghidra folders, or try to build the plugin for 12.1.4. Nobody here has tested that.
   Prompt for ClaudeCopy

   GOAL: Confirm my Ghidra project of <GAME>'s eboot.elf is loaded well enough to build a function ledger.
   READ FIRST: `notes/ghidra-export.txt` (my export of the function list and import labels), `docs/imports.md` from Path A.
   FENCE: Edit only `tools/compare_imports.py`, `notes/ghidra-check.md` and `notes/parking-lot.md`. Do not change the Ghidra project. Do not open the dump.
   CHECK: Run `py -3 tools/compare_imports.py notes/ghidra-export.txt docs/imports.json`. Done means every import in the audit appears as a named label in the export.
   BUDGET: 30 minutes.
   IF BLOCKED: Stop. List the imports that are missing in Ghidra and the addresses where they should be.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The compare output. 3) Files changed. 4) Functions found and any odd regions. 5) New parking-lot items.

   Done whenEvery import from the audit appears as a named label in Ghidra, and the function count is saved.

   Proof this works: https://github.com/boazvdwansem/ghidra_ps5_elf_plugin (PS5 ELF analyzer for Ghidra 12.1.3), Astro Bot native PC port (Ghidra 12.1.4, self2elf.py and dyninfo.py helpers), https://github.com/NationalSecurityAgency/ghidra/blob/Ghidra_12.1.3_build/README.md (Ghidra 12.1.3 needs JDK 21)

3. Map the binary into a ledger

   You make one file that lists every function with its address, size and status. You mark library and engine code so nobody rewrites it by hand. This file is how you and Claude track the whole job.

   • Export functions with the ghidra-headless skill or a Ghidra script. Save address, name, size and callers.
   • Mark code from the C library, the C++ library and the engine as library. Do not rewrite it.
   • Use the executable load ranges, not only the .text section. Mewgenics found game code outside .text.
   • Save docs/ledger.csv with columns: address, name, size, kind, status, owner, test.
   • Sort the game's own functions by size and by how many other functions call them.
   Prompt for ClaudeCopy

   GOAL: Build `docs/ledger.csv` with one row per function in <GAME>'s eboot.elf.
   READ FIRST: `notes/ghidra-functions.csv` (headless export), `notes/detect.txt`, `SCOPE.md`.
   FENCE: Edit only `docs/ledger.csv`, `tools/ledger.py` and `notes/parking-lot.md`. Do not open the dump. Do not write any C yet.
   CHECK: Run `py -3 tools/ledger.py --check`. Done means the row count equals the Ghidra function count, every row has a kind (game, library or engine), and sizes add up to the executable code size.
   BUDGET: 60 minutes.
   IF BLOCKED: Stop. List the address ranges you could not classify.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output with counts per kind. 3) Files changed. 4) The 20 smallest game leaf functions. 5) New parking-lot items.

   Done whentools/ledger.py --check passes: one row per function, every row has a kind, sizes add up.

   Proof this works: Mewgenics-android (use executable PT_LOAD ranges; .text alone misses game code), https://www.skills.sh/trailofbits/skills-curated/ghidra-headless, research/topics/ai-decomp-practice.md C1 (a script picks the task; small units first)

4. Build the swap-and-compare harness

   You make a way to run one of your C functions in place of the game's own. The hook checks the original bytes first, so it only fires on the right game version. Then a test runs the same scene twice and compares. No PS5 project has built this harness yet. The hash-guarded hooks of Mewgenics-android are the closest.

   • Add a hook layer in your patch series. Guard each hook by a hash of the function's first 64 bytes, as Mewgenics does.
   • Give each hook a switch so you can turn it off for the compare run.
   • Drive both runs with the same pad timeline. Set APS5_PAD_INPUT_FILE and queue the timeline with C:\a5\tools\pad_timeline.py.
   • Compare the run report, the traced calls from APS5_TRACE_CALLS_FILE, and frames from APS5_FRAME_CAPTURE.
   • Prove the harness first: plant a wrong version of one function and check that the compare fails.
   Prompt for ClaudeCopy

   GOAL: Make `py -3 tools/swaptest.py <FUNCTION_ADDR>` run <SCENE> with the hook on and off, and fail on any difference.
   READ FIRST: `SCOPE.md`, `docs/ledger.csv`, Mewgenics-android's hook design notes in my `notes/hooks.md`, AnyPS5 `docs/user/USAGE.md` sections Controller input for test runs and Tracing system library calls.
   FENCE: Edit only `patches/`, `tools/swaptest.py`, `docs/PROGRESS.md` and `notes/parking-lot.md`. The dump is read-only. Every hook checks the original bytes before it fires.
   CHECK: Run `py -3 tools/swaptest.py --selftest`. Done means a correct copy of a small function passes, and a planted wrong copy fails.
   BUDGET: 2 hours. Plan first; wait for my okay before you write code.
   IF BLOCKED: Stop. Say which difference you cannot control, such as timing or random seeds.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Self-test output for both cases. 3) Files changed. 4) Known sources of noise. 5) New parking-lot items.

   Done whenThe self-test passes a correct swap and fails a planted wrong one, on the same scene and pad timeline.

   Proof this works: Mewgenics-android (FNV-1a code-signature guards; hooks fire only on the matching executable), https://github.com/benpye/OpenRCT2 (procedures rewritten in C one by one inside the running original), research/topics/ai-decomp-practice.md C3 (calibrate the check first: break a file and confirm it fails)

5. First light: replace one small function

   You pick one small leaf function and write it in C. A leaf function calls no other game function. It passes the swap test and the golden runs. This proves the whole loop works end to end.

   • Pick the smallest game leaf function in docs/ledger.csv.
   • Read it in Ghidra. Write the C in src/game/<address>.c.
   • Build, then run py -3 tools/swaptest.py <ADDRESS> and the golden runs from Path A.
   • Mark the row replaced in the ledger with the test name.
   Prompt for ClaudeCopy

   GOAL: Replace the function at <ADDRESS> in <GAME> with readable C that passes the swap test.
   READ FIRST: `docs/ledger.csv` row <ADDRESS>, my Ghidra export of it in `notes/fn/<ADDRESS>.txt`, `docs/PROGRESS.md` section Ruled out.
   FENCE: Edit only `src/game/<ADDRESS>.c`, its hook entry in `patches/`, the ledger row and `notes/parking-lot.md`. No inline assembly, no copied byte arrays, no calls back into the original function.
   CHECK: Run `py -3 tools/swaptest.py <ADDRESS>`, then `py -3 tools/golden.py`. Done means both exit 0.
   BUDGET: Stop after 5 failed tries.
   IF BLOCKED: Stop. Paste the first difference the swap test reports.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Both check outputs. 3) Files changed. 4) Anything the C had to guess. 5) New parking-lot items.

   Done whenOne function runs as your C, the swap test passes, and every golden run still passes.

   Proof this works: Mewgenics-android (replaced the inner LZ4 block decoder, kept the wrapper; checked with test vectors), https://github.com/benpye/OpenRCT2 (each procedure re-written in C and called from the patched original)

6. Grind: many workers, one function each

   Now you scale up. A lead session hands out small functions, one per worker. Each worker has its own worktree and its own build folder. Only verified work lands.

   • Have a script pick the next units: small leaf functions first, then functions whose callees are all replaced.
   • Give each worker one card from the Path B unit loop prompt.
   • Run each worker in its own git worktree with absolute paths and its own build folder.
   • Merge only after a fresh verify session re-runs the swap test and the golden runs on the merged branch.
   • Update docs/ledger.csv and docs/PROGRESS.md after each merge.
   Prompt for ClaudeCopy

   GOAL: Hand out the next <N> functions from `docs/ledger.csv` to <N> workers and merge only verified results.
   READ FIRST: `docs/ledger.csv`, `docs/PROGRESS.md`, the Path B unit loop card in `notes/cards/unit-b.md`.
   FENCE: As lead, edit only `docs/ledger.csv`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Workers edit only their own `src/game/<ADDRESS>.c` and hook entry. One owner per file.
   CHECK: After merging, run `py -3 tools/swaptest.py --all-replaced`, then `py -3 tools/golden.py`. Done means both exit 0 on the merged branch.
   BUDGET: <N> units, each with at most 5 tries. Stop the batch if two merges fail in a row.
   IF BLOCKED: Stop. List each unit as merged, failed or skipped, with the reason.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Merged check output. 3) Files changed. 4) Ledger counts before and after. 5) New parking-lot items.

   Done whenThe ledger's replaced count went up, and the swap tests and golden runs pass on the merged branch.

   Proof this works: https://github.com/mattias800/prosper (agents work in their own worktrees; independent review before merge), research/topics/ai-decomp-practice.md C1 and C2 (worktrees, one owner per file, a match in a worktree is not a match on the merged branch)

7. Hard units: classes and data layouts

   Big C++ classes and shared data are the slow part. Claude must work out the layout of each structure first. A wrong layout breaks many functions at once. Write each layout down before any code uses it.

   • Write each structure in include/game/<name>.h with its size checked by static_assert.
   • Find layouts from how the code reads memory, from the run traces, and from engine headers if the engine is open.
   • Mark guesses with a confidence tag, such as CONFIDENCE: LOW, as prosper does.
   • Send units that failed three times in bulk to a hard-unit session.
   Prompt for ClaudeCopy

   GOAL: Write the layout of <STRUCT> used by the functions <ADDRESS_LIST> in <GAME>, and replace <ADDRESS> using it.
   READ FIRST: `docs/ledger.csv`, the Ghidra exports in `notes/fn/`, `docs/PROGRESS.md` section Ruled out, `include/game/`.
   FENCE: Edit only `include/game/<STRUCT>.h`, `src/game/<ADDRESS>.c`, its hook entry and `notes/parking-lot.md`. Every field has an offset comment and a confidence tag.
   CHECK: Run `py -3 tools/check.py`, `py -3 tools/swaptest.py <ADDRESS>` and `py -3 tools/golden.py`. Done means all exit 0, and `static_assert` checks the struct size.
   BUDGET: Stop after 3 failed layouts. Plan first; wait for my okay.
   IF BLOCKED: Stop. List the fields you are not sure of and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check outputs. 3) Files changed. 4) Fields marked LOW. 5) New parking-lot items.

   Done whenThe struct header has a size check, and the function that uses it passes its swap test and the golden runs.

   Proof this works: https://github.com/mattias800/prosper (CONFIDENCE: HIGH/MED/LOW tags; evidence order), https://github.com/ymatrix1/PortPS5 (static_assert on the size and offsets of any struct the guest can see)

8. Harden: all swaps on, many scenes

   You turn every replaced function on at once. You run every golden scene and longer play sessions. Bugs that only show when many swaps mix appear here.

   • Run py -3 tools/golden.py with all hooks on, after every merge.
   • Add longer scenes with pad timelines, such as a full level.
   • Compare frame replays of key scenes with all hooks on and all off.
   • Bisect any new failure by turning hooks off in halves.
   Prompt for ClaudeCopy

   GOAL: Find which replaced function breaks <SCENE> when all hooks are on.
   READ FIRST: `docs/ledger.csv`, the failing golden output in `notes/golden-fail.txt`, `docs/PROGRESS.md` section Ruled out.
   FENCE: Edit only `tools/bisect_hooks.py`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Do not change any replaced function in this task.
   CHECK: Run `py -3 tools/bisect_hooks.py <SCENE>`. Done means it names one hook, and the scene passes with only that hook off.
   BUDGET: 2 hours.
   IF BLOCKED: Stop. Say if the failure needs two hooks together to appear.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The bisect log. 3) Files changed. 4) The guilty hook and its ledger row. 5) New parking-lot items.

   Done whenEvery golden scene passes with all hooks on, on a clean checkout.

   Proof this works: https://github.com/benpye/OpenRCT2 (the project stays a DLL until all procedures are re-written), Astro Bot native PC port (A/B runs on the same scene; kept and rejected results logged)

9. Port: drop the eboot

   Once every game function is your C, the original eboot is no longer needed. You build your C as a normal program for the new system. Then you swap the PS5 system parts for that system's own.

   • Build a version that loads no eboot code. Every call must land in your C.
   • Put the PS5 system calls behind your own interface: files, pads, sound, saves and graphics.
   • Fix 64-bit and pointer-size problems for the new system.
   • Build for the new system and run the same golden scenes there.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> from my C alone, with no eboot code loaded, and pass the golden scenes on <TARGET_SYSTEM>.
   READ FIRST: `docs/ledger.csv` (all rows replaced or library), `SCOPE.md`, `docs/PROGRESS.md`.
   FENCE: Edit only `src/platform/`, the build files and `notes/parking-lot.md`. Do not change game logic in `src/game/` in this task.
   CHECK: Run `py -3 tools/golden.py --target <TARGET_SYSTEM>`. Done means every golden scene passes there.
   BUDGET: Plan first; wait for my okay. Then one system part per session.
   IF BLOCKED: Stop. Name the system part that has no match on the new system.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Golden output on the target. 3) Files changed. 4) System parts still missing. 5) New parking-lot items.

   Done whenThe game runs on the new system from your C alone and passes the same golden scenes.

   Proof this works: https://github.com/error9098x/ps5-native-mac (Metal backend and own system runtime on Apple silicon), Mewgenics-android (native Vulkan backend replaced the game's PS5 Agc backend)

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

Cut Path A into one missing function, one crash, or one graphics bug per session. Each unit has a check. The audit loses one absent row, the golden run gets further, or the frame replay matches better. Cut Path B into one function per session, checked by the swap test and the golden runs. Keep a ledger file for each: docs/imports.md, docs/PROGRESS.md and docs/ledger.csv. Never hand Claude the whole game at once.

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`, `docs/STATUS.md` and the newest entry in `docs/PROGRESS.md` before any change.
- The one check is `py -3 tools/check.py`. Work is not done until it exits 0. Paste its output.
- The dump at <DUMP> is read-only. Never copy `eboot.bin`, `.prx` files, `sce_sys`, shaders, saves, frames or recorded input into the repo, an issue or a cloud session.
- A system function you cannot build calls `NotImplemented_nid_no_patch(__func__)`. Never return a made-up success.
- Never special-case a title ID, hash, value or path in shared library code. Per-game changes go only in `patches/` or the game's patch TOML.
- In `AnyPS5` code, write no comments. Put known gaps in `docs/dev/debt/<library>.md`. (AnyPS5 `AGENTS.md`)
- After any library change, rebuild with `cmake --build build --target libs`. The game loads its `.prx` files from `build/core/libs/libs`.
- Quote test results from `ctest --no-tests=error` with the test count. A green run with zero tests is not a pass.
- A byte patch lists the `expected` bytes and is checked with `relinker --verify-patches`. Never write to a fixed address without that check.
- Start the game at most once per build, through `C:\a5\tools\title_run.py`. Never launch it in a loop. It always exits 0, so read its outcome lines.
- Never skip a draw, a dispatch or a system call to get past a bug. Log it and fail visibly.
- Write every dead end in the `## Ruled out` section of `docs/PROGRESS.md`, with the evidence, in the same commit.
- In a worktree, use absolute paths and your own build folder. Never build in the main checkout.
- A pipeline's exit code is its last stage's. Save the real exit code before you pipe to `tail` or `grep`.
- Never write this machine's user name or local paths into committed files.

Keep the context small

• Send big run logs to a read-only subagent. Get back only the first error and the function it names.
• Give Claude a function name or an address and a short Ghidra export, not a wall of machine code.
• Do not let Claude read the whole AnyPS5 tree. Name the one library folder it needs.
• Keep docs/STATUS.md to one page. Put history in docs/PROGRESS.md.
• Clear the chat between units. The ledger files 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> (<TITLE_ID>, version <VERSION>) can get a native PC port on AnyPS5, and what blocks it today. Write it in `notes/feasibility.md`.
READ FIRST: The AnyPS5 Game bring-up thread for <TITLE_ID>: <DISCUSSION_URL>. The KytyPS5 compatibility entry, if any. These repos: <REPO_URLS>.
FENCE: Edit only `notes/feasibility.md` and `notes/parking-lot.md`. Do not open the game dump. Write no code.
CHECK: Run `py -3 -c "import sys;t=open('notes/feasibility.md',encoding='utf-8').read();sys.exit(0 if all(h in t for h in ['## Existing ports','## Furthest point reported','## Known blockers','## First milestone and its check','## Out of scope']) else 1)"`. Done means it exits 0 and each existing port has a link.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say what you could not find. Do not fill gaps with guesses.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A one-line verdict: start, join an existing effort, or wait. 3) Files changed. 4) Risks. 5) Questions for me.

GOAL: Update `docs/imports.md` from a fresh import audit of <GAME> and list what changed since the last audit.
READ FIRST: `docs/imports.json` (new audit), `docs/imports-prev.json` (last audit), `<WORK>/calls.txt`.
FENCE: Edit only `docs/imports.md`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Do not change code.
CHECK: Run `py -3 tools/count_imports.py`. Done means the five totals match the audit's summary.
BUDGET: 30 minutes.
IF BLOCKED: Stop. Say which audit file is missing or unreadable.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Totals now and before. 3) Files changed. 4) Imports that moved between groups. 5) New parking-lot items.

GOAL: Implement <FUNCTION> (<NID>) in AnyPS5's <LIBRARY> with a unit test.
READ FIRST: `docs/imports.md` row for <FUNCTION>, how the game calls it in `notes/fn/<FUNCTION>.txt`, neighbours in `core/libs/prx/<LIBRARY>/`, AnyPS5 `AGENTS.md`.
FENCE: Edit only `core/libs/prx/<LIBRARY>/`, its test, `docs/dev/debt/<LIBRARY>.md` and `notes/parking-lot.md`. No Sony SDK material. No title-specific branches. Unknown cases throw.
CHECK: Run `py -3 tools/check.py`. Done means it exits 0, the new test is in the count, and the audit shows <FUNCTION> as implemented or partial.
BUDGET: Stop after 3 failed builds or 60 minutes.
IF BLOCKED: Stop. Say which argument or return value you cannot work out.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Check output and audit line. 3) Files changed. 4) Cases that still throw. 5) New parking-lot items.

GOAL: Find and fix the cause of the crash in <SCENE> of <GAME>.
READ FIRST: The crash report in `logs/<RUN>.log`, the last traced calls, `docs/PROGRESS.md` section Ruled out.
FENCE: Edit only the files the evidence points to, their tests, `docs/PROGRESS.md` and `notes/parking-lot.md`. No fix until the cause is proven. Never catch and hide the error.
CHECK: Run `py -3 tools/check.py`, then `py -3 tools/golden.py`. Done means both exit 0 and the golden scene passes <SCENE>.
BUDGET: Stop after 3 failed hypotheses. Write each one in Ruled out.
IF BLOCKED: Stop. Show the evidence you have and what you need, such as a capture or a longer stack dump.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The cause, with the log lines that prove it. 3) Files changed. 4) Check and golden output. 5) New parking-lot items.

GOAL: Replace the function at <ADDRESS> in <GAME> with readable C that passes its swap test.
READ FIRST: `docs/ledger.csv` row <ADDRESS>, `notes/fn/<ADDRESS>.txt`, the headers it needs in `include/game/`.
FENCE: Edit only `src/game/<ADDRESS>.c`, its hook entry in `patches/`, its ledger row and `notes/parking-lot.md`. No inline assembly. No byte arrays copied from the game. No calls back into the original.
CHECK: Run `py -3 tools/swaptest.py <ADDRESS>`. Done means it exits 0 on the scene in the ledger row.
BUDGET: Stop after 5 failed tries.
IF BLOCKED: Stop. Paste the first difference and say what you think causes it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Swap test output. 3) Files changed. 4) Guesses in the C. 5) New parking-lot items.

GOAL: Run the next <N> units from <LEDGER_FILE> in parallel, one worker each, and merge only verified ones.
READ FIRST: <LEDGER_FILE>, the unit card in `notes/cards/<CARD>.md`, `docs/PROGRESS.md`.
FENCE: As lead, edit only <LEDGER_FILE>, `docs/PROGRESS.md` and `notes/parking-lot.md`. Each worker uses its own worktree with absolute paths and its own build folder. No two workers touch the same file.
CHECK: After merging, run `py -3 tools/check.py` and `py -3 tools/golden.py`. Done means both exit 0 on the merged branch.
BUDGET: <N> units. Each worker stops after 3 to 5 failed tries.
IF BLOCKED: Stop the batch if two merges fail in a row. Report each unit as merged, failed or skipped.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Merged check output. 3) Files changed. 4) Ledger counts before and after. 5) New parking-lot items.

GOAL: Prove the cause of <SYMPTOM> in <GAME>. Do not fix it yet.
READ FIRST: `docs/PROGRESS.md` section Ruled out, `logs/<RUN>.log`, the PM4 capture in <SUBMITS_DIR> or the frame capture in <CAPTURE_DIR>.
FENCE: Edit only `notes/debug/<BUG>.md` and `notes/parking-lot.md`. You may add log lines behind a switch, but no fixes.
CHECK: Run `py -3 -c "import sys;t=open('notes/debug/<BUG>.md',encoding='utf-8').read();sys.exit(0 if all(h in t for h in ['## Cause','## Proof','## Ruled out']) else 1)"`. Then run the on and off commands under Proof yourself. Done means the check exits 0 and the symptom shows only with the switch on.
BUDGET: 90 minutes or 3 hypotheses.
IF BLOCKED: Stop. List what you ruled out, with evidence, and what you need next.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The cause and the proof. 3) Files changed. 4) Hypotheses ruled out. 5) New parking-lot items.

GOAL: Check that the work in commits <COMMIT_RANGE> is real and stays inside its fence.
READ FIRST: `git diff <COMMIT_RANGE>`, the task card in `notes/cards/<CARD>.md`, `CLAUDE.md`.
FENCE: Edit only `notes/verify/<DATE>.md`. Change no code.
CHECK: Re-run `py -3 tools/check.py` and `py -3 tools/golden.py` yourself. Then search the diff for: returns of success with no work, new title IDs or hashes in shared code, skipped draws or dispatches, changed tests or expected values, changes outside the fence, and copied game bytes. Done means every item has a yes or no with a file and line.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say what you could not re-run.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) PASS or FAIL. 2) Check outputs from your own run. 3) Files changed. 4) Each finding with file and line. 5) New parking-lot items.

GOAL: Write a status report for <GAME> from the ledgers only.
READ FIRST: `docs/imports.md`, `docs/ledger.csv` (Path B), `docs/PROGRESS.md`, the last golden output in `logs/golden-latest.txt`.
FENCE: Edit only `docs/STATUS.md`. Change no code. Do not guess numbers.
CHECK: Run `py -3 tools/count_imports.py`, then `py -3 -c "import sys;t=open('docs/STATUS.md',encoding='utf-8').read();sys.exit(0 if len(t.splitlines())<=60 and 'Source:' in t else 1)"`. Done means both exit 0, and every number names its ledger file after `Source:`.
BUDGET: 20 minutes.
IF BLOCKED: Stop. Say which ledger is missing or out of date.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The numbers with their sources. 3) Files changed. 4) Top three blockers. 5) Parking-lot items that need my decision.

GOAL: Save everything the next session needs to carry on <TASK> without this chat.
READ FIRST: `docs/STATUS.md`, `docs/PROGRESS.md`, `git status`, `git log -5 --oneline`.
FENCE: Edit only `docs/STATUS.md`, `docs/PROGRESS.md` and `notes/parking-lot.md`. Do not start new work.
CHECK: Run `py -3 -c "import sys,datetime;t=open('docs/PROGRESS.md',encoding='utf-8').read();sys.exit(0 if datetime.date.today().isoformat() in t and all(h in t for h in ['Works:','Does not work:','Next step:','Uncommitted:']) else 1)"`. Done means it exits 0, the Works lines hold pasted check output, and new dead ends are in Ruled out.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say what state you could not save.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The new PROGRESS entry. 3) Files changed. 4) The next step as one task card. 5) New parking-lot items.

GOAL: Give me a plain answer on <TASK>: can it be done now, and if not, why not.
READ FIRST: Your last report, `docs/PROGRESS.md` section Ruled out, the failing check output.
FENCE: Edit only `notes/blocked/<TASK>.md`. Change no code. Try nothing new.
CHECK: Run `py -3 -c "import sys;l=open('notes/blocked/<TASK>.md',encoding='utf-8').readline().strip();sys.exit(0 if l in ('CAN','CANNOT','CANNOT YET') else 1)"`. Done means it exits 0, and the note gives the evidence and two or three options with their cost.
BUDGET: 15 minutes.
IF BLOCKED: Say so in the first line. That is a valid answer.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) BLOCKED or PARTIAL. 2) What fails, with output. 3) Files changed. 4) Options: wait for an AnyPS5 update, try KytyPS5 for this part, change the milestone, or stop. 5) What you need from me.

GOAL: Ask me before you leave the fence of <TASK>.
READ FIRST: The task card for <TASK>, `SCOPE.md`.
FENCE: Edit only `notes/scope-requests.md`. Change no code until I answer.
CHECK: Run `git status --porcelain`. Done means it lists only `notes/scope-requests.md`, and the request names the files you want to touch, why the fence is not enough, the risk, and how you will check it.
BUDGET: 10 minutes.
IF BLOCKED: Stop and wait for my answer.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) BLOCKED (waiting for approval). 2) The evidence that the fix is outside the fence. 3) Files you want to change. 4) The check you will run. 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

• Whether AnyPS5 already runs your game. Then a port took days. If not, you work inside the shared tool for weeks.
• How many imports are absent or stubs at the start.
• Graphics: shader bugs, GPU waits and slow draw handling take the longest.
• How fast the shared tools change. Updates can fix your bug or break your patches.
• For Path B: the number of game functions and how much is C++ classes with unknown layouts.

The facts behind these numbers

Projects reviewed (14)

RecompLauncher lists one PS5 game, so there are fewer than 10 games on RecompLauncher. All 3 review cards are here. 11 more were reviewed live: one RecompLauncher entry filed under another system, and 10 from outside it. Fewer than 10 real per-game PS5 projects exist anywhere. So five entries are shared tools, marked 'Many games'.

What each project teaches

What we could not check

• No command in this guide was run for this check, and no PS5 dump was used. Commands were checked against each tool's docs and source code only.
• title_run.py behaviour (its outcomes, and that it always exits 0) was read from its source code, not run.
• 11 of the 14 projects have no review card. They were checked live against their READMEs and GitHub data on 2026-11-14 UTC.
• The Path B swap-and-compare harness is a plan. No PS5 project has built one.
• --to-intel was not tried on an Intel CPU.
• Whether Dead Cells PS5 Native, SonsOfSparta-PS5 Native or the Astro Bot PC port used AI. None of them say.
• Which exact AnyPS5 commit Dead Cells PS5 Native is built from.
• Whether ghidra_ps5_elf_plugin builds against Ghidra 12.1.4 or 12.2. Its README names 12.1.3, and GhidraMCP needs 12.1.4. No reviewed project used the plugin.
• The ps5rs install needs Rust 1.85 or newer. I did not check the Rust install steps.
• That the PS5 graphics chip is RDNA 2. This comes from AnyPS5's shader badges and prosper's notes, not from a Sony page. psdevwiki.com returned an error page (HTTP 403).
• The 60 FPS claim of Mewgenics-android was not measured by anyone else.
• The PvZ: Replanted Android AI count is from AI co-author lines in commits. The project does not state it in words.
• The no-AI time for Path A is a guess. No PS5 port predates AI agents.
• The box64 build steps were not read in full. Only the compile doc link and Mewgenics' -DANDROID=ON note were checked.
• The NebulaAPU status line is dated 2026-10-01. Whether work went on elsewhere is unknown.
• The share of AnyPS5 pull requests marked as AI-assisted could not be counted reliably with GitHub search.

Sources

• AnyPS5 README
• AnyPS5 build instructions
• AnyPS5 relinker usage
• AnyPS5 AGENTS.md
• AnyPS5 title_run.py
• Dead Cells PS5 Native README
• SonsOfSparta-PS5 Native README
• Astro Bot native PC port README
• Mewgenics-android README
• PvZ: Replanted Android README
• Ghost of Yotei on AnyPS5 README
• KytyPS5 README
• PortPS5 AGENTS.md
• prosper CLAUDE.md
• ps5-native-mac README
• ps5rs README
• ghidra_ps5_elf_plugin README
• Ghidra README
• WinLibs GCC 15.2.0 release
• Clang PS4 and PS5 toolchain header
• box64 README
• Tracy releases
• OpenRCT2 early fork README
• winget-pkgs manifests (CMake, Ninja, Git, Vulkan SDK)
• AnyPS5 controller timelines
• AnyPS5 Game bring-up discussions
• Ghidra 12.1.3 README (JDK 21)
• GhidraMCP README
• prosper releases
• Dead Cells packaging script
• PC first-person shooter decomp with agents