C64 Reverse Engineering MCP

C64RE is a reverse-engineering workbench for Commodore 64 software. It pairs a human reverse engineer with an LLM and gives them a shared, controllable C64 — a headless runtime you can snapshot, rewind, replay, and inspect cycle by cycle — fused with a disassembly pipeline that turns raw bytes into explained, named, semantic source.

The aim isn't to boot software. It's understanding: turning disks, cartridges, PRGs, traces, and screenshots into durable project knowledge, built by a human and an LLM together — the LLM proposes structure and meaning, the human steers and confirms, and the runtime proves or refutes every claim against a real execution.

Leitregel: Capability → TRX64, Meaning/Memory → C64RE.

The Combination is more than sum of its parts

Semantic disassembly tells you what code means. A controllable runtime lets you watch it happen. C64RE puts both on one timeline:

• rewind to the exact cycle a fastloader flips a bank,
• overlay the named, explained routine onto the live execution,
• replay that moment with findings and labels attached.

Plain emulators run code but don't know what it means. Disassemblers describe code but can't run it. Meaning + execution, human + LLM — that's the point.

The Runtime

A controllable, inspectable C64 + 1541 + cartridge runtime — in ways neither real hardware nor a normal emulator offers:

• time travel — snapshot / .c64re persistence, checkpoint ring, rewind & replay
• reverse-debug — an always-on ring keeps the last ~10 s of instructions + writes: step backwards (rstep), ask who wrote this address (whowrote — the stack-crash shortcut), auto-triage a JAM into its causal chain (crash → wild jump → stack corruptor), and carve a trace for an exact cycle window straight from the scrub bar
• code overlay — map live execution onto disassembly and findings
• observation — DuckDB traces, swimlanes, monitor, frozen-frame exploration
• live browser workbench — the backend owns the clock, monitor, media, trace, and audio; the browser commands and visualizes
• frame-locked audio, media ingress, mutable disks & cartridges

TRX64 — a native (Rust), cycle-exact port of VICE — is the default runtime: far faster, and the home of the reverse-debug features above. The original TypeScript runtime is now the fallback + parity oracle (it declines the TRX64-only features cleanly); force it with C64RE_RUNTIME_TS=1 ./ui.sh restart. Both serve the same WebSocket protocol and the same .c64re / .c64retrace formats. (TRX64 is auto-found as the sibling ../TRX64/target/release/trx64-daemon; C64RE_RUNTIME_BIN / C64RE_TRX64_BIN point elsewhere.)

It already boots real scene software end-to-end — multi-stage cracks, custom fastloaders, EasyFlash cartridges — and its fidelity is gated on every change.

The Disassembly Pipeline

Bytes → structure → meaning:

1. deterministic extraction (PRG / CRT / D64 / G64; banks, sectors, xrefs, candidate segments)
2. heuristic disassembly (full 6502 ISA incl. undocumented opcodes)
3. semantic annotation — the heart of it: the LLM reads the whole listing and proposes segment reclassifications, labels, and routine explanations; the human reviews
4. verification: byte-identical rebuild (cmp -l)

The valuable phase is the semantic one — where segment $7C21-$7F4F contains code becomes loader-side dispatcher: switches KERNAL serial → custom fastloader, hands control to scene init.

Human + LLM, With A Contract

The collaboration has structure, not just chat. Work moves through a defined workflow, and the LLM operates under explicit roles:

• analyst — forms and tests hypotheses
• cartographer — maps structure, memory, and flows
• implementer — writes and verifies

Progress persists as entities, findings, relations, flows, tasks, and open questions — durable knowledge that survives across sessions, not console logs. The Workspace UI renders that knowledge; it never becomes a second analysis engine.

The first-level model is a five-phase lifecycle — Onboarding · Discovery · Reverse Engineering · Build · Release — navigated freely via the left rail (not a gate); the seven-phase per-artifact pipeline nests inside Discovery + RE. Onboarding is agent-led: the dialogue runs in the coding harness (Claude Code / Codex) over MCP and C64RE records the brief — it is not a second LLM runtime.

Details: workflow · roles · per-artifact pipeline · product vision.

Architecture

Two repos, two roles — the Leitregel split. C64RE turns bytes/events/state into meaning; TRX64 (a separate Rust process) provides the runtime capability.

┌────────────────────────────────────────────────────────────────────┐
│ Human + LLM                                                         │
│   Claude Code · Codex · Cursor   run the agents/flows + onboarding   │
│   Browser Workbench UI           visualizes knowledge; not an LLM    │
└──────────────┬──────────────────────────────────┬───────────────────┘
               │ MCP: knowledge / workflow          │ MCP + WebSocket: runtime
               ▼                                     ▼
┌────────────────────────────────┐   ┌───────────────────────────────────┐
│ c64re-mcp — MEANING (this repo)│   │ trx64-mcp / Runtime Daemon         │
│                                │   │   — CAPABILITY  (../TRX64, Rust)   │
│ · disasm pipeline: extract →   │   │                                    │
│   heuristic → semantic →       │◄─►│ · cycle-exact C64 + 1541 + cart    │
│   byte-verify rebuild          │WS │ · trace · reverse-debug · rewind   │
│ · findings/entities/relations  │   │ · checkpoint ring · snapshots      │
│ · flows/tasks/open-questions   │   │ · .c64re / .c64retrace             │
│ · project memory · UI views    │   │ · DuckDB trace store · monitor     │
│ · agents/flows (BMAD, private) │   │                                    │
└────────────────────────────────┘   │  TS runtime = fallback / oracle    │
   Meaning / Memory → C64RE          │  VICE       = internal-dev oracle  │
                                      └───────────────────────────────────┘
                                         Capability → TRX64

Today the split is mid-transition (Spec 771): c64re-mcp still hosts the runtime_* tools as a thin proxy to the Runtime Daemon; a separate trx64-mcp server is the endstate. The daemon (WS :4312, Spec 744.4c) is already the one runtime both the UI and MCP are clients of — TRX64 by default, the TS runtime as fallback/parity oracle, VICE as internal-dev correctness oracle only.

The flow across the lifecycle — which actor acts in each phase, and the handoffs between them (renders on GitHub):

flowchart LR
    subgraph HU["🧑 Human"]
        direction LR
        H1[set goal] --> H2[steer / confirm] --> H3[sign-off]
    end
    subgraph LL["🤖 LLM + Harness — Claude Code / Codex"]
        direction LR
        L1[kickoff dialogue] --> L2[disasm + annotate] --> L3[build loops] --> L4[QA]
    end
    subgraph CR["📚 C64RE — meaning / memory"]
        direction LR
        C1[record brief] --> C2[findings / payloads] --> C3[byte-verify rebuild] --> C4[package]
    end
    subgraph TX["⚙️ TRX64 — runtime capability"]
        direction LR
        T1[play / watch] --> T2[trace / reverse-debug] --> T3[runtime-validate] --> T4[quality gate]
    end

    H1 -. goal .-> L1
    L1 ==> C1
    T2 -. evidence .-> L2
    L2 ==> C2
    T3 -. validate .-> C3
    C4 -. release .-> H3

Loading

Lanes = actors; left → right = the five phases (Onboarding · Discovery · Reverse Engineering · Build · Release).

Setup

git clone https://github.com/Jondalar/C64ReverseEngineeringMCP.git
cd C64ReverseEngineeringMCP
npm install
npm run build

The bundled TRXDis pipeline is built automatically.

Environment Variables

Variable	Description	Required
C64RE_PROJECT_DIR	Working directory for the RE project	Yes
C64RE_RUNTIME_ENDPOINT	WS endpoint of the product Runtime Daemon (Spec 744.4c) — e.g. ws://127.0.0.1:4312. When set, MCP runtime_* tools are clients of the daemon (the same runtime the UI uses). The MCP auto-starts the daemon (detached) on first use — you do NOT start the backend by hand; it outlives the MCP, so reconnect / browser reload do not reset sessions. npm run runtime:daemon is an optional explicit/foreground launch. Unset → in-process runtime (dev/test, no UI sharing).	Recommended for shared human+LLM runtime
C64RE_RUNTIME_ENDPOINT daemon backend	The daemon resolver picks: C64RE_RUNTIME_BIN (explicit) > the sibling TRX64 daemon (default) > built TS dist > tsx. C64RE_RUNTIME_TS=1 forces the TS parity oracle; C64RE_TRX64_BIN points at a TRX64 daemon elsewhere.	No
C64RE_RUNTIME_AUTOSTART	Set to 0 to disable the MCP auto-starting the daemon (then run npm run runtime:daemon yourself).	No
C64RE_RUNTIME_WS	RETIRED 744.4b MCP co-host port. It reset sessions on MCP reconnect — superseded by the Runtime Daemon (C64RE_RUNTIME_ENDPOINT). Setting it now only logs a deprecation.	No (retired)
C64RE_TOOLS_DIR	Override: external TRXDis build instead of bundled	No
C64RE_KICKASS_JAR	Override path to KickAssembler jar	No
C64RE_64TASS_BIN	Override path to 64tass	No
C64RE_EXOMIZER_BIN	Override path to exomizer	No
C64RE_BYTEBOOZER_BIN	Override path to b2 / ByteBoozer 2	No
C64RE_VICE_BIN	Override path to x64sc (internal-dev oracle only)	No
C64RE_VICE_CONFIG_PATH	Override source vicerc copied into VICE sessions	No
C64RE_VICE_CONFIG_DIR	Override source VICE config dir, with vicerc inside	No

Claude Code

Add .mcp.json at the RE-project root:

{
  "mcpServers": {
    "c64-re": {
      "command": "npx",
      "args": ["tsx", "/path/to/C64ReverseEngineeringMCP/src/cli.ts"],
      "env": {
        "C64RE_PROJECT_DIR": "/path/to/your/re-project",
        "C64RE_RUNTIME_ENDPOINT": "ws://127.0.0.1:4312"
      }
    }
  }
}

Use a full path to npx if your shell uses nvm.

With C64RE_RUNTIME_ENDPOINT set, the MCP and the browser UI are clients of one shared Runtime Daemon (Spec 744.4c, auto-started on first use — see Running The UI); an MCP reconnect or browser reload never resets a session. Do not use the retired C64RE_RUNTIME_WS. Design: docs/runtime-daemon-solution-design.md.

Codex

[mcp_servers.c64re]
command = "zsh"
args = ["-lc", "cd /path/to/C64ReverseEngineeringMCP && NODE_NO_WARNINGS=1 ./node_modules/.bin/tsx src/cli.ts"]
env = { C64RE_PROJECT_DIR = "/path/to/your/re-project" }

Running The UI

One workbench bundle (Spec 757) — the workflow cockpit (project knowledge: artifacts, findings, memory maps, media, disassembly) and the Live runtime view are the same app. The backend is a Runtime Daemon (Spec 744.4c) that owns the C64/1541 clock, monitor, media, trace and checkpoints; the browser UI and MCP tools are clients, so a reload or MCP reconnect never resets a session. With C64RE_RUNTIME_ENDPOINT set (see above) the MCP auto-starts the daemon on first use — you don't launch the backend by hand.

npm run ui:serve            # API + built UI on http://127.0.0.1:4310
npm run ui:dev              # Vite live reload on http://127.0.0.1:4311
npm run ui:build            # rebuild the production bundle (ui/dist)
npm run runtime:daemon -- --project <dir>   # optional explicit/foreground daemon

Backend / runtime / UI details: docs/tools/headless.md.

Tools by lifecycle phase

Tools serve the phases, not a flat catalog — Disk and Cartridge stay first-class and directly reachable. Per-area reference docs linked below.

Phase	Tools + evidence
Onboarding	project init / audit · goal capture · agent-team (BMAD) · play & watch via TRX64
Discovery	media extraction (CRT / D64 / G64) · payload inventory · loader + packer/depack analysis · disk & cartridge forensics (first-class)
Reverse Eng	heuristic + semantic disassembly · annotation · flow / xref · payload classification · runtime evidence (trace / reverse-debug / code-overlay, from TRX64)
Build	assemble (KickAssembler / 64tass) · byte-verify rebuild · patch-recipes · new medium / loader
Release	QA gates · docs / reports · package & export
Cross-phase	project knowledge (findings / entities / relations / questions) · artifacts · inspector · memory maps

Per-area reference docs: analysis · disk · CRT · compression · c64ref · TRX64 runtime · VICE oracle · 6502 sandbox · knowledge · artifacts · agent doctrine · product vision.

Workflow — the RE lifecycle

The first-level experience is a five-phase project lifecycle, navigated freely via the left rail (navigation, not a hard gate):

1. Onboarding — start / audit the project; play & watch with TRX64; capture the goal (EF port · cheat / trainer · enhancement · loader-replacement · docs). Agent-led kickoff over the coding harness; C64RE records the brief.
2. Discovery — media extraction + payload inventory; loader + packer analysis; define the agent team + flows. Disk & cartridge forensics live here.
3. Reverse Engineering — heuristic + semantic disassembly; annotation; payload classification; TRX64 runtime evidence, C64RE owns the interpretation.
4. Build — new medium / loader / feature in loops; decision ↔ code ↔ runtime-validation, byte-verified rebuild.
5. Release — local QA gates; external-tester loops; reports; final package.

The seven-phase per-artifact analysis pipeline nests inside Discovery + RE. Runtime evidence (TRX64 by default; VICE as internal oracle) is registered as artifacts and linked to findings/entities — never left as loose logs or console output.

Details: product vision · workflow · per-artifact pipeline · lifecycle spec 773.

Planning & Status

• PLAN.md — roadmap + working baseline + step gates
• specs/README.md — the cross-repo spec board (C64RE + TRX64 share one number range; the single registry of what's ACTIVE / DONE / CLOSED)
• specs/715-runtime-product-proof-baseline.md
  • docs/runtime-product-baseline-2026-05-24.md — the current product proof authority (the single "is this green" source; migrates to the enforced TRX64 quality gate, Spec 783). Run npm run proof:product (full) or npm run proof:capability -- <cap> (focused); npm run proof:list shows the manifest. Specs 600/601 are retained as the historical seven-game 1541 bring-up gate, superseded as product authority.
• CLAUDE.md — working doctrine for contributors and agents

License & Credits

C64RE MCP is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE.

VICE is C64RE's correctness oracle: where the runtime ports C64, 1541, VIC-II, CIA, VIA, IEC, GCR, monitor, or trace behavior, it does so faithfully and validates against VICE, the Versatile Commodore Emulator. VICE is licensed under the GNU General Public License version 2 or later; C64RE uses the "or later" permission and distributes under GPL-3.0-or-later. Thank you to the VICE project and its contributors.

Additional notices are in THIRD_PARTY_NOTICES.md.

ROMs And Third-Party Media

Commodore ROM images, commercial disks, cartridges, and other copyrighted media are not part of this project license. If runtime tests or examples need ROMs, provide them locally through your own legally obtained copies or through files whose licenses permit redistribution.