C64RE

A reverse-engineering workbench for Commodore 64 software via MCP. Turns disks, cartridges and PRGs into explained, named source, and keeps learning as project knowledge.

User and LLM share the project. The LLM brings structure and mines meaning, the human steers and confirms, a C64 runtime is used to validate findings.

Sibling project: TRX64 is the runtime — a cycle-accurate C64 + 1541 + cartridge daemon. Capability lives there, meaning and memory live here. C64RE carries no emulator; it is a client.

The disassembly pipeline

Bytes → structure → meaning, and the third step is the one that matters.

1. Extraction — PRG / CRT / D64 / G64: banks, sectors, directory, xrefs, candidate segments, including disk and cartridge forensics.
2. Heuristic disassembly — the full 6502 ISA including undocumented opcodes. Nine analyzers in parallel: code discovery, text, sprites, charsets, screen RAM, bitmaps, pointer tables, SID, probable code. Overlaps get resolved.
3. Semantic annotation — the LLM reads the whole listing and proposes segment reclassifications, labels and routine explanations. Where segment $7C21-$7F4F contains code becomes loader-side dispatcher: switches KERNAL serial → custom fastloader.
4. Verification — assemble with KickAssembler/64tass and rebuild the original byte for byte. cmp -l decides; annotations never touch bytes.

A BASIC V2 program is not machine code and is not disassembled as if it were: basic_list walks its line records, detokenises against the table the ROM itself carries, names the PETSCII control codes, and reports which SYS hands control to which address — so a BASIC loader and the machine code it starts are one story. basic_tokenize is the inverse, and the round trip is byte-identical.

Step 3: a game engine's jump table, named — and verified byte-identical.

Step 1: block attribution per track and sector, a file's sector chain, its sources.

The knowledge base

Findings, entities, relations, payloads, flows, open questions — linked to the artifacts and addresses they came from. Runtime evidence is registered as an artifact and attached to a finding.

Since Spec 822.2 all of it lives in one graph per project (knowledge/graph.sqlite), not in a folder of JSON files. Two layers: what the analysers derived and what a human asserted, kept apart and never overwriting each other. Routines carry a computed signature — which registers they take, return, clobber and preserve, and what they do to the stack — because assembler declares no interface and the answer has to be computed rather than guessed. The Graph tab draws the whole project four ways: force, layers, rings from a focus, and along the address axis with a lane per bank.

• Every claim carries its evidence and the address range it covers.
• Artifacts are versioned with lineage.

The agentic flow

Work moves through a five-phase lifecycle under explicit roles — analyst forms and tests hypotheses, cartographer maps structure and flow, implementer writes and verifies. Each step is recorded, so a later session resumes instead of restarting.

flowchart LR
    subgraph HU["🧑 Human"]
        H1[goal] --> H2[steer · confirm] --> H3[sign-off]
    end
    subgraph LL["🤖 LLM in Claude Code / Codex"]
        L1[kickoff] --> L2[disasm · annotate] --> L3[build] --> L4[QA]
    end
    subgraph CR["📚 C64RE"]
        C1[brief] --> C2[findings] --> C3[byte-verify] --> C4[package]
    end
    subgraph TX["⚙️ TRX64"]
        T1[play] --> T2[trace · reverse-debug] --> T3[validate]
    end
    H1 -. goal .-> L1
    T2 -. evidence .-> L2
    L2 ==> C2
    T3 -. validate .-> C3
    C4 -. release .-> H3

Onboarding · Discovery · Reverse Engineering · Build · Release, navigated freely from the left rail. The kickoff dialogue runs in the coding harness; C64RE records the brief.

What the phase knows: established, blocked, next action — derived, not typed in.

Details: workflow · roles · pipeline · tools.

Setup

npx -y @trex64/c64re          # the server
npx @trex64/c64re runtime install   # the machine it drives

Then point your harness at it and give it a project directory:

{
  "mcpServers": {
    "c64-re": {
      "command": "npx",
      "args": ["-y", "@trex64/c64re"],
      "env": { "C64RE_PROJECT_DIR": "/path/to/your/re-project" }
    }
  }
}

ROM images are yours to supply — they are Commodore's property and are in no package.

Full setup, including a source checkout, Codex, Windows, WSL2 and containers, plus what to do when it does not work: INSTALL.md.

The workbench

npx -y @trex64/c64re ui --project /path/to/your/re-project   # from the package
npm run workspace -- --project /path/to/your/re-project      # from a checkout
npm run ui:dev                                               # Vite live reload on :4311

It opens on http://127.0.0.1:4310. The bundle ships with the package, so the first line needs no build. From a checkout it does: ui/dist/ is not in git, so npm run ui:build once, and npm run workspace compiles the server on every start.

One bundle: project knowledge — artifacts, findings, memory maps, media, disassembly — and the live runtime view are the same app. The daemon owns the clock, monitor, media and traces; browser and MCP are both clients, so a reload never resets a session.

In the project folder itself, project_init leaves launchers so nobody has to remember any of the above:

| | | |---|---| | macOS / Linux | ./ui.sh start · restart · stop · status · logs · build-ui | | Windows | double-click ui-start.cmd / ui-stop.cmd / ui-restart.cmd, or powershell -ExecutionPolicy Bypass -File .\ui.ps1 <action> |

Both sets are written into every project, because a project folder travels between machines, and they take the project from their own location so the folder can be copied or renamed. What they invoke depends on where they were written: beside an installed package they call c64re ui — nothing at all is baked, because under npx the package sits in a cache directory that moves. Beside a checkout they run the workspace script there, and that one path is baked with C64RE_REPO overriding it (setx C64RE_REPO "C:\path\to\C64ReverseEngineeringMCP"). start waits for the port and then opens the browser. For a project that predates the launchers:

npm run launchers -- --project /path/to/project

Windows, start to finish: docs/windows-setup.md.

Working on a smaller plan

contrib/claude/skills/model-router is the doctrine for spending model capacity when the session runs Sonnet: /deep answers one hard turn on Opus without changing the session model, /cheap puts a mechanical turn on Haiku, and the reasoner (Opus) / bulk (Haiku) subagents let Claude route a sub-question by itself. The skill carries the install command and is honest about what it does not save.

What to expect

This is my (dkl / Jondalar) personal Reverse Engineering Toolbox packaged along my own needs when reverse engineering C64 games. You might need different features or things - and you are invited to contribute.

Use issues here on GitHub please. PRs only to contributors, please reach out if you want to send code.

I will not answer feature requests without sample code / structured requirements and I have no capabilities to give real support.

License

GPL-3.0-or-later — see LICENSE. C64RE contains no emulator. It does carry work read from VICE — the monitor's verb set and expression syntax, and the cartridge type table, whose every row cites the source it was read from. VICE is GPL-2.0-or-later; C64RE uses the "or later" permission. Thank you to the VICE project.

The Live tab's VIC view — a raster line cycle by cycle, and the grid of line × cycle over the frozen picture — takes its layout from vicspector by elysium64 (MIT), an interactive VIC-II guide for C64 coders. Thank you. vicspector builds on Linus Åkesson's VIC-II timing chart and MISC notes and Christian Bauer's VIC-II article, and the raster techniques the view names (FLI, FLD, linecrunch, DMA delay, open borders, sprite crunch) are named after them. The data in the view is the emulation's own, not a model.

Further notices: THIRD_PARTY_NOTICES.md. ROMs and third-party media are not part of this license. Commodore ROM images, commercial disks and cartridges must come from your own legally obtained copies.