Skip to main content
skill CX Codex

console-backend — Claude Code skill: what it does, install

console-backend is a Claude Code skill that ranks missing PS2Recomp backend pieces from runtime logs. It activates after a stop or a request about syscalls, the IOP, or stubs.

MIT ★ 449 updated 2026-10-22

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Jakeschincariol/console-skill
/plugin install console-skill@console-skill
Open on GitHub

What console-backend does

The console-backend skill reads PS2Recomp runtime logs and turns missing stubs, pending syscalls, failed IOP RPC calls, disc-read errors, and untranslated instructions into an ordered fix list. Each entry includes its count, first PC and RA, plus the matching remedy: a TOML binding, a runtime .cpp file, an entry point followed by recompilation, or a game override.

The skill does not modify the checkout. It prints a table for console/STATE.md. With --repo, it reads the actual handler names and syscall numbers; without it, the tool falls back to a built-in EE kernel syscall table and guesses file locations. The commands require python3, a runtime log such as console/runs/latest.log, and a PS2Recomp checkout for repository-aware results.

What it helps with

  • rank missing PS2 stubs from a runtime log
  • map a syscall number to its handler
  • trace a failed disc-file lookup
  • separate an IOP RPC issue from a runtime issue
  • prepare a fix table for console/STATE.md

Example prompts for the agent

  • Scan console/runs/latest.log against the checkout at ../PS2Recomp and rank the fixes: python3 console-backend/stubs.py scan console/runs/latest.log --repo ../PS2Recomp
  • Turn the logs in console/runs/*.log into a Markdown table: python3 console-backend/stubs.py scan console/runs/*.log --markdown
  • Find the handler for syscall 0x3C: python3 console-backend/stubs.py syscall 0x3C --repo ../PS2Recomp

How to install console-backend

1Plugin marketplace

/plugin marketplace add Jakeschincariol/console-skill
/plugin install console-skill@console-skill

This installs the whole console-skill plugin with all its skills

2Skills CLI (Vercel)

npx skills add Jakeschincariol/console-skill --skill console-backend -a claude-code

3Manually: put the files in place

~/.claude/skills/console-backend/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/console-backend/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about console-backend

How do I install console-backend in Claude Code?

Run /plugin marketplace add Jakeschincariol/console-skill, then run /plugin install console-skill@console-skill in Claude Code.

What does console-backend do?

It scans PS2Recomp runtime logs, ranks missing stubs, syscalls, IOP failures, and disc errors, then points to the fix type and relevant file.

What does console-backend need to work?

It needs python3 and a runtime log such as console/runs/latest.log. A PS2Recomp checkout passed with --repo supplies real handler names and syscall numbers.

Source text

SKILL.md · MIT
---
name: console-backend
description: >-
  Backend Engineer. Builds the engine room the recompiled game runs on: syscalls, kernel stubs, file
  and disc I/O, the IOP. Reads PS2Recomp runtime logs and turns every "Unimplemented PS2 stub",
  "[Syscall TODO]", missing function, unhandled IOP RPC, failed disc read and untranslated
  instruction into a ranked fix list: count, first PC and RA, and the exact fix tool (a TOML binding,
  the runtime .cpp file to implement it in, an entry point and a recompile, or a game override).
  With the user's PS2Recomp checkout it reads the real handler names and syscall numbers. Writes
  nothing into the checkout; prints a table for console/STATE.md. Use when the user says
  "unimplemented stub", "syscall TODO", "it crashes at boot", "fix the backend", "it can't find a
  file", "the IOP", "what is syscall 0x3C", or after /console-tester reports a stop.
argument-hint: "scan <log> [--repo PATH] [--markdown] | handlers --repo PATH | syscall <num>"
---

# console-backend

The Backend Engineer makes the runtime under the recompiled game complete enough for it to run.
The generated code is a literal translation of the game; everything it expects from the PS2 (the
kernel, the SDK libraries, the disc, the I/O processor) has to exist in `ps2xRuntime` and `ps2xIOP`.
Every missing piece shows up as a log line. This skill reads those lines, ranks them, and says which
of the four fix tools applies and in which file.

Honest limits: the tool reads logs and the checkout; it does not write C++ for you. Some fixes are a
one-line `case` in the dispatcher, others are a whole subsystem. A game usually stops at the first
missing piece, so expect one fix per run early on, and fix in order.

`${CLAUDE_SKILL_DIR}` below is this skill's folder (where this SKILL.md lives).

```bash
python3 "${CLAUDE_SKILL_DIR}/stubs.py" scan console/runs/latest.log --repo ../PS2Recomp   # ranked fixes
python3 "${CLAUDE_SKILL_DIR}/stubs.py" scan console/runs/*.log --markdown                # table for STATE.md
python3 "${CLAUDE_SKILL_DIR}/stubs.py" handlers --repo ../PS2Recomp --grep sceCd         # real handler names
python3 "${CLAUDE_SKILL_DIR}/stubs.py" handlers --repo ../PS2Recomp --todo               # handlers still TODO
python3 "${CLAUDE_SKILL_DIR}/stubs.py" syscall 0x3C --repo ../PS2Recomp                  # name a syscall
python3 "${CLAUDE_SKILL_DIR}/stubs.py" syscall -0x1A                                     # interrupt variant
```

`scan` exits 1 when it finds something to fix and 0 on a clean log; every command takes `--json`.

## What it reads and writes

| File | What |
| --- | --- |
| runtime logs (`console/runs/*.log` from /console-tester, or saved stdout+stderr) | read, line by line, any size |
| `ps2xRuntime/include/ps2_call_list.h` (with `--repo`) | `PS2_SYSCALL_LIST` and `PS2_STUB_LIST`: the handler names a binding may use |
| `ps2xRuntime/src/lib/Kernel/Syscalls/Dispatcher.cpp` (with `--repo`) | which syscall number goes to which handler |
| `ps2xRuntime/src/lib/Kernel/**/*.cpp` (with `--repo`) | where each handler lives and which are still `TODO_NAMED` |
| stdout | the ranked list, or a Markdown table to paste into STATE.md's "Stubs and syscalls" |

Without `--repo` it uses a built-in table of standard EE kernel syscalls and guesses files from
names, and says so. Read `reference/runtime-layers.md` before the first fix of a session: the three
layers, how a call reaches a handler, triage stubs, the IOP, disc I/O and the subsystem file map.

## The layers, in short

| Layer | What | Rule |
| --- | --- | --- |
| Recompiled code | `ps2xRuntime/src/runner/*.cpp`, one C++ function per game function, dispatched by guest ADDRESS through one function table | never edited, never listed |
| Runtime | `ps2xRuntime/src/lib/`: kernel syscalls (`Kernel/Syscalls/`), SDK stubs (`Kernel/Stubs/`), memory, GS, VU, audio, pad, files; `ps2xIOP/`: the game's IRX modules | your fixes go in its `.cpp` files |
| Host | raylib (window, input, sound), the file system, FFmpeg | untouched |

A bound stub calls a named handler; an unbound or skipped one logs `Unimplemented PS2 stub called`
and throws; a `syscall` goes through `Kernel/Syscalls/Dispatcher.cpp` and an unknown number logs
`[Syscall TODO]` and returns 0. Subsystem by subsystem, the first file to open is in section 7 of
`reference/runtime-layers.md` (threads and semaphores, interrupts, SIF and modules, `fio*`, `sceCd*`,
memory card, pad, audio, GS, movies, libc).

## The method

1. **Read STATE.md first** (`state.py show` from /console-reverse): the phase, the runner command,
   the stub table, the open strikes.
2. **Get one log per run.** /console-tester (`run.py boot`) keeps them in `console/runs/`; by hand,
   run the command from STATE.md with a short timeout and save stdout and stderr.
3. **Scan it**: `stubs.py scan <log> --repo <PS2Recomp>`. Issues come in the order they first
   appeared. The first one usually caused the stop ("ended the run"); later ones can be
   consequences. Note that unknown syscalls do not stop the game (the runtime returns 0), so an
   early `[Syscall TODO]` is a prime suspect for a strange crash later.
4. **Pick the fix tool the scan names, then check it in the source** before writing anything:

| The log says | Fix tool | Where |
| --- | --- | --- |
| a handler that is still `TODO_NAMED` | Runtime C++ | its `Kernel/Stubs/<File>.cpp` |
| `sub_XXXXXXXX` or a name with no handler | TOML | bind `"<Handler>@0xADDR"`, or recompile it if it is game code, or `ret0@` for one run to classify it |
| a handler that works but logged anyway | TOML | it is in `skip`: move it to `stubs` |
| `[Syscall TODO]` | Runtime C++ | a `case` in `Kernel/Syscalls/Dispatcher.cpp` (+ the handler in `Kernel/Syscalls/<File>.cpp`) |
| missing function, `codeRegion=yes` | Recompiler | `entry_points` hint in the TOML, then re-run `ps2_recomp` (batch them) |
| missing function, `codeRegion=no` | Investigate | overlay, second program or bad pointer: the caller at RA-8 |
| `[IOP/RPC trace:unhandled]` | IOP | is the IRX on the extracted disc and loaded? then ps2xIOP imports |
| `sceCdSearchFile failed` | Disc files | the file, the extraction, the run path |
| `sceCdRead unresolved LBN` | Game override | point `cdImage` at the user's own plain `.iso` |
| `fatal exception: Unhandled ... at 0x.. raw=0x..` | Game override | replace that function; record it as an upstream issue |

5. **Triage stubs are temporary.** `ret0@`/`ret1@`/`reta0@` only answer "does it get further if this
   succeeds?". Record each one in STATE.md as TEMPORARY and promote it: bind the real handler,
   implement the TODO handler, or write an override. Never leave one on a function that allocates
   memory, creates a thread or carries game logic.
6. **Prefer fixes that do not touch headers.** Implementing an existing TODO handler or adding a
   dispatcher `case` rebuilds the runtime library only. A new name in `PS2_STUB_LIST`
   (`ps2_call_list.h`) rebuilds every generated file: ask first, or put the body in a game override
   with `runtime.replaceFunction(addr, fn)` instead.
7. **Every replacement function returns with `ctx->pc = getRegU32(ctx, 31);`** unless it calls the
   original. Arguments are `getRegU32(ctx, 4..7)`, results `setReturnU32/S32`, guest pointers
   `getMemPtr(rdram, addr)` (null when invalid).
8. **Build through /console-reverse's build gate, run, scan again**, and compare with the previous
   log (/console-tester `triage.py compare`). Fixed: update the row in STATE.md and log one line.
   Same stop after a fix: `state.py strike`; at three strikes, stop guessing (circuit breaker).

Write C++ only after the adversarial check from /console-reverse: what you will change, why it fixes
the cause, what it could break, and whether you read the code or remembered it.

## IOP and disc I/O in one paragraph each

**IOP.** ps2xIOP runs the game's own IRX modules from the extracted disc on an R3000A interpreter,
with generic HLE services only for MCSERV, LIBSD and DBCMAN. `[SIF module] load-emulated ...` lines
show what loaded. An unhandled SID means the serving module is missing, failed to load, or needs an
import the virtual IOP kernel lacks (`ps2xIOP/src/emulator/`). No BIOS is involved or wanted.

**Disc and files.** `cdrom0:` is the folder of the ELF passed to the runner, `mc0/` sits beside it,
and the runtime matches names as written (on Linux, case matters). Replacing a file in the extracted
folder swaps it in the game, no ISO rebuild. Games that read raw sectors need a plain 2048-byte
`.iso` of the user's own disc set as `cdImage` in a game override (`reference/runtime-layers.md`
has the snippet; `iso.py plain` in /console-reverse converts a raw `.bin`).

## Guard rails

- **Bring your own game.** Only games the user owns, dumped from their own disc. Never download
  ISOs, ELFs, IRX modules or BIOS files, never help find them, never ask for them. PS2Recomp needs no
  BIOS, and neither do these fixes.
- **Nothing from the game gets published.** Logs can quote game strings and paths: keep them local.
  The disc, the ELF, the IRX modules and the recompiled C++ stay on the user's machine; runtime fixes
  you write are yours to share (they contain no game code), as are overrides that only hold addresses
  and your own logic. Upstream issues carry an address and an instruction word, never game files.
- **Not affiliated with Sony.** PlayStation is a trademark of Sony Interactive Entertainment.
- **Skill-specific:** never edit generated `runner/*.cpp` or list `runner/`; never edit a header
  without the user's OK; never clean the build; read-only access to the checkout from these tools.

## Hands off to

`/console-tester` to run again and compare logs, `/console-reverse` for entry points, re-exports,
recompiles and the build gate, `/console-mod` when the fix is a game-specific override,
`/console-controller`, `/console-graphics`, `/console-sound` and `/console-saves` when the first
issue sits in their subsystem.

© Jake Schincariol · MIT · Jakeschincariol/console-skill

Similar skills

All skills for Backend and APIs →

From the same set12

The whole set →
console-levels console-levels is a Claude Code skill that maps an extracted PS2 disc, unpacks the archives holding levels and repacks them after edits. It fires on requests like "unpack this archive". CX Codex +1 ★ 449repo stars console-anywhere console-anywhere is a Claude Code skill that prepares a PS2Recomp build for a target device and packages it for players. It runs on requests to build for Steam Deck, Android, Mac, or another supported target. CX Codex +1 ★ 449repo stars console-sound Console-sound is a Claude Code skill that rips game audio and injects custom tracks back into the files. It decodes PS2 VAG and SPU2 ADPCM formats into WAV for easy editing. CX Codex +1 ★ 449repo stars console-controller console-controller is a Claude Code skill that maps gamepads, keyboard, and touch input into PS2Recomp. It handles remapping, sticks, triggers, and two players. CX Codex +1 ★ 449repo stars console-tester console-tester is a Claude Code skill that automates playtesting for PS2 game ports. It executes ELFs via ps2EntryRunner, categorizes crashes, maps PCs to Ghidra symbols, and diffs PCSX2 dumps. CX Codex +1 ★ 449repo stars console-mod console-mod is a Claude Code skill that ports PCSX2 patches and builds game overrides for PS2Recomp ports. It triggers when you ask to add cheats, adapt a .pnach, or alter gameplay mechanics. CX Codex +1 ★ 449repo stars console-graphics console-graphics is a Claude Code skill for rebuilding PS2 textures and finding widescreen patches. It responds to 16:9 requests and rendering failures. CX Codex +1 ★ 449repo stars console-reverse console-reverse is a Claude Code skill that drives PlayStation 2 game porting with PS2Recomp. It streams disc images, extracts boot ELFs, and maintains project state. CX Codex +1 ★ 449repo stars

Project sponsors

Companies that keep this analytics open