Programmatic C64 analysis and system emulation
TREX64 combines three tools. TRX64 provides cycle-accurate C64, 1541, and 1581 emulation with rewind and JSON-RPC control. C64RE imports deterministic analysis into a persistent typed 6502 graph, provides pre-edit impact queries, and verifies rebuilt output byte for byte. External LLM agents query the graph through MCP and add semantic annotations and evidence. The C64U / UE2 Emulator provides the Ultimate target environment for firmware validation and Made for Ultimate software development: unmodified firmware, UCI, turbo modes up to 64 MHz, Ultimate Audio, and modeled board hardware backed by TRX64.
Semantic analysis / C64RE
C64RE imports deterministic reports to build typed control-flow and memory-access relations and infer routine contracts. Agents add semantic annotations; reassembly verifies output byte for byte.
System / C64U / UE2 Emulator
UE2 runs unmodified firmware and C64 software that uses UCI, turbo modes, REU, Ultimate Audio, and other C64U-specific interfaces. MCP, scripts, REST, and CI provide control.
Emulation runtime / TRX64
TRX64 emulates the C64, 1541, and 1581 with cycle-accurate execution, rewind, headless operation, and JSON-RPC control.
01 / Interfaces
C64RE uses MCP and calls the TRX64 daemon for runtime evidence. TRX64 exposes JSON-RPC and an embeddable Rust core. The C64U / UE2 Emulator embeds that core and adds MCP, REST, scripts, and headless control.
The agent instructs C64RE to extract media and run deterministic analyzers, queries the resulting typed 6502 graph, reads complete listings, writes semantic annotations, and records evidence.
The CLI, C64RE, scripts, and agents control a reversible session through JSON-RPC. The C64U / UE2 Emulator links the Rust core directly.
Automation boots firmware, loads C64 software, sends UI and C64 input, inspects video and UART state, calls REST services, asserts results, and shuts down the instance.
TRX64 does not own the reverse-engineering analysis pipeline. C64RE contains no emulator and uses the TRX64 daemon when static evidence requires runtime validation.
01 · Runtime / TRX64
TRX64 is a Rust runtime for the C64, 1541, and 1581. The CLI, JSON-RPC daemon, and embeddable library use one command-dispatch path.
02 · Knowledge / C64RE
C64RE is an MCP workbench for media extraction, deterministic disassembly, typed graph construction, semantic annotation, pre-edit impact queries, and byte-for-byte comparison of rebuilt output with the imported artifact. A user defines the objective; an external LLM agent reads complete listings, labels segments and routines, and records evidence.
change_impact query reports incoming control flow, shared-state dependencies, claims affected by the change, inferred state-preservation requirements, and unresolved control-flow paths
03 · Ultimate target / C64U / UE2
C64U / UE2 combines unmodified Ultimate 64 Elite II or C64 Ultimate firmware, modeled board hardware, and the TRX64 core. C64 programs can use UCI, the Ultimate speed registers, REU, Ultimate Audio, and other C64U-specific interfaces. The system runs interactively, headlessly, or under CI.
C64RE / Analysis output
Deterministic results and human assertions are stored in separate layers in knowledge/graph.sqlite.
Applied semantic annotations are stored in the human layer and retained across re-analysis. Trace imports
add observed execution and memory-access edges without replacing static evidence. MCP tools resolve nodes,
traverse typed edges, find control-flow paths, and execute impact queries against the same graph.
01 / Typed relations
The graph stores routine, label, address, zero-page, ROM, and hardware-register nodes. Typed edges represent calls, ROM calls, jumps, branches, reads, writes, indirect accesses, and pointer references. Artifact, cartridge-bank, and drive-CPU identifiers distinguish identical 16-bit addresses. Each edge stores supporting evidence and a confidence value.
02 / Routine contracts
C64RE infers inputs, outputs, clobbers, preserved registers and flags, stack effects, call-site arguments, patched operands, and unresolved exits. Analysis includes known ROM ABIs and recursive call relationships; unresolved callees leave contracts partial.
03 / Change impact
change_impact traverses incoming call, jump, and branch edges; identifies readers of written addresses and references through pointer and jump tables; and finds claims that may be invalidated. It reports inferred state-preservation requirements. If trace data is available, the report includes observed raster-line timing, worst observed line occupancy, and remaining margin. Unresolved indirect jumps, self-modifying-code paths, and drive-CPU paths are reported as UNKNOWN rather than low risk.
Graph views: force-directed layout · structural layers · concentric rings centered on a selected node · address axis with one lane per bank
The human defines the objective and approves decisions. An LLM agent invokes C64RE through MCP, interprets the resulting evidence, and persists project knowledge. C64RE performs deterministic analysis and byte comparison. TRX64 supplies runtime evidence for hypotheses derived from static analysis.
Create or resume the project, record the human objective, and select a workflow profile.
Extract and register every payload, analyze the loader and packer chain, and map medium locations to load addresses.
Generate deterministic first-pass source and import its analysis report into the typed 6502 graph. Inspect each non-trivial segment, add semantic annotations, connect artifacts, and validate each interpretation against recorded evidence.
Run change_impact before changing bytes. Apply patches or implement the target medium, loader, or feature; record the rationale, modified byte ranges, and validation evidence.
Run local and external tests, record known issues, create release candidates, and package the final artifact with its documentation.
Phases 1–2 run during Discovery. Phases 3–7 run during Reverse Engineering. Each phase has an explicit completion criterion.
Extract payload bytes and register every source and generated artifact. Complete when no visible payload remains unregistered.
Statically disassemble and annotate loader and drive code. Record entry points, load contexts, and the flow to runtime addresses.
Run deterministic analysis and import the report into the typed 6502 graph. Generate first-pass source for KickAssembler and 64tass without semantic annotations, then attempt a rebuild.
The LLM agent inspects each non-trivial segment, classifies it from static evidence, or records an open question.
The LLM agent proposes labels, routine explanations, and segment annotations. After application, C64RE stores them in the human graph layer, re-disassembles the artifact, and compares rebuilt output with the imported artifact byte for byte.
The LLM agent links entities and records cross-artifact relations and flows. C64RE preserves artifact lineage and refuted hypotheses.
Refine annotations with project-wide context, perform final rebuild verification, render documentation, and complete the artifact checklist.
C64 ROMs, Ultimate firmware, and third-party media are not distributed with these projects. Supply files from legally obtained copies.
TRX64 / macOS
Homebrew installs trx64cli and trx64-daemon. Place C64 ROMs in ~/.trx64/roms or pass --rom-dir.
C64RE / npm · Node 22+
npx fetches the MCP server @trex64/c64re on first use. runtime install downloads the pinned TRX64 daemon and verifies its checksum. The MCP client runs npx -y @trex64/c64re with C64RE_PROJECT_DIR set. ui serves the workbench on 127.0.0.1:4310.
C64U / UE2 · macOS
Create a flash image from update.ue2, supply the roms directory from a 1541ultimate checkout, and start the firmware.