Skip to content
Dave-AgentPublic

About

Byte-identical, commented, relocatable Kick Assembler source from C64 disk and tape images: a Claude Code skill (process, rules, tools)

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

MOSaic

MOS AI deCompiler

Turn an 8-bit game's disk, tape or cartridge image into byte-identical, fully commented, relocatable Kick Assembler source, one piece of evidence at a time.

MOSaic is a Claude Code skill: a process, its rules, and the scripts that check them. The machine is data (platforms/<id>/platform.json): the Commodore 64 is supported end to end, the BBC Micro as far as the hand-off, coverage and phase 1 (see Known limitations), and the NES as a descriptor with mapper files.

What's in it

  • SKILL.md, references/: the process (acquire, phase 1, phase 2), the rules, and the decision log
  • scripts/: refactoring tools, checks, a 6510 tracer, a routine-test simulator, graphics renderer, Ghidra and VICE glue, and Beebium glue for the BBC Micro (scripts/platform/bbc/)
  • platforms/: one descriptor per machine (memory map, chips, vectors, media), NES mapper files, and the hardware libraries of the BBC Micro
  • templates/, framework/, libs/: project scaffold, byte-identity gate, C64 hardware definitions

How it works

  1. Research first. The game's manual, release databases, wikis, reviews and POKE lists are read before any code, and recorded as unconfirmed leads in docs/gameplay.md. Scanned manuals are rendered to images and read. Nothing from the web goes into the source until the code confirms it.
  2. Start from the original medium. A disk or tape image sits in a read-only originals/ folder and is never attached to an emulator directly: VICE runs a scratch copy. A tape's standard loader is decoded to files, and a turbo loader is run in VICE or decoded by a script written for it.
  3. Find the hand-off and derive a clean reference. The game runs to the point where it is fully loaded and about to start. RAM is dumped there several times and the dumps are voted on to cancel emulator noise. Loader and crack bytes are zeroed only when the tracer proves nothing touches them. The result is a game-only image with a recorded SHA-256.
  4. Dynamic and static analysis together. A small 6510 tracer runs the game and records what really executes. Ghidra then follows the code statically from those addresses, separates code from data and records who references what, and an exporter writes Kick Assembler source that assembles to the identical image. Execution tells the analysis where to start; the static pass finds what the run didn't reach.
  5. Phase 1: understand everything while the build stays byte-identical. just verify is the gate. Agents work in scratch copies called slices, merged only after their checks pass, with progress notes while they run.
  6. Names need proof. A name that claims a role needs the code and an observation from a tracer run. What a thing is to a player goes to the owner, with a picture rendered in the game's own colours and modes. Answers are recorded so nobody asks twice.
  7. Rules are enforced by scripts. About twenty checks cover raw addresses, placeholders, echo comments, list end markers, one record per row, banners that tile the image, table sizes, hardware-dependency tags and unreferenced blocks. A source is complete only when the report says so.
  8. Phase 2 begins with a safety net. Routine tests run the original code in a simulator against Python models. Golden traces record the game's state per frame under scripted input, with a timing-tolerant set for when bytes change.
  9. Then it refactors in small, gated steps. The source is split into files, a platform interface is defined with written contracts, layout assumptions become asserts and a relocation sweep, and approved dead blocks are removed without moving live code. The gate then accepts a difference only inside the approved ranges.

Getting started

The full step-by-step, from adding the game's image to a finished phase 2, is in HOWTO.md. The short version:

(a) Install the tools. Python 3, Java 17+, Kick Assembler (the jar in ~/tools/KickAss.jar, or set KICKASS_JAR in project.config), git, just, VICE (x64sc) with its C64 ROMs, Ghidra 11 or 12 (set GHIDRA_HOME if it isn't under ~/ghidra*; Ghidra 12 needs JDK 25 and a one-time support/pyghidraRun -H setup of PyGhidra) and a C compiler. The Ghidra exporter script is fetched automatically on first use. Pillow is needed for pictures. Developed on Linux; macOS should work; on Windows use WSL.

(b) Get the skill and let Claude set you up. Clone it, open Claude Code in the folder and ask:

git clone https://github.com/Dave-Agent/MOSaic.git ~/MOSaic
cd ~/MOSaic
claude

Set up MOSaic for me.

Claude links the skill, checks your tools (and tells you how to get any that are missing), asks for your game's file and name, and creates the project. It changes only ~/.claude/skills/mosaic and the project folder you name, and installs nothing without your yes. If you prefer a terminal script, ./setup.sh asks the same questions, and ./setup.sh --check only checks the tools.

(c) Open Claude Code in the project folder. Claude tells you the exact line, for example cd ~/C64Projects/my-game && claude. The original game file was copied into the project's originals/ folder with its SHA-256. It is never modified and never attached to an emulator directly; VICE only runs scratch copies. MOSaic creates a local git repository in the project and commits after each step. It never pushes.

(d) Ask for the first stage.

Use the MOSaic skill. Create a source that builds and starts this game, without stopping between its parts.

The agent researches the game, extracts the files, finds the point where the game is fully loaded, derives a clean reference image, exports the disassembly from Ghidra, and builds it back byte for byte. A disk takes tens of minutes and a tape longer. VICE opens windows while it dumps memory; don't type in them.

(e) The agent asks you at four points only. After the setup the work is four steps: create a source that builds and starts (step 2), name every routine (step 3), refactor ready for future development (step 4) and remove the dead code (step 5). Steps 2 and 4 are long jobs in several parts that the agent does in the background, telling you each part as it starts, and stopping early only if it needs something from you. When a step ends it says what you now have, how to launch it and which file to read, and asks whether to go on, for example: "Raw disassembly complete: it assembles byte for byte to the original and starts. Launch it with just launch 1; the source is phase1/src/<name>.asm. Start phase 1?" Answer "yes", or say "move to the next stage" at any time and it works out where the project is.

(f) Check where you are with just --list for the commands, python3 ~/.claude/skills/mosaic/scripts/p1_complete.py --root . --phase 1 for how much of phase 1 remains, and docs/ in the project for the research, the boot analysis and the answers recorded from you.

Updates. just status and the tool check print an UPDATE: line when a newer release has been tagged, and say how far behind you are. It is one read-only request to the skill's git remote, at most once a day (cached in ~/.cache/mosaic/); nothing is updated for you, and MOSAIC_NO_UPDATE_CHECK=1 turns it off. python3 scripts/version_check.py shows the details. The installed version is in VERSION. Every push to main is released automatically (a minor release when it closes an enhancement issue, otherwise a patch release; a major release is made by hand), so VERSION and the tags follow the commits.

See results

In a project made with MOSaic (new_project.py), every command takes the phase: 1 is the frozen, byte-identical reconstruction, 2 is the split, refactored source. With no argument it uses ACTIVE_PHASE from project.config.

just verify        # assemble and compare byte for byte with the original image: the gate
just smoke         # boot it headless in VICE and check the screen against a reference picture
just launch        # run it in VICE at real speed, symbols loaded
just check         # everything that must stay green: verify, tests, golden traces
just verify 1      # name the phase: 1 or 2
just --list        # every command with its description

docs/ in the project holds the pictures the process produces (docs/gfx/), the answers recorded from the game's owner, and for phase 2 the file map (docs/phase2_files.md).

Known limitations

  • The tracer, routine tests, golden traces and smoke test are C64-specific. On the BBC Micro the hand-off dump, the stale-byte probe and coverage run in the Beebium emulator (scripts/platform/bbc/emulator/), and DFS discs are read by scripts/platform/bbc/media/dfs.py; the tracer has no BBC machine model, and the machine's OS ROM is supplied by the user, never shipped. For the NES there is a descriptor and the MMC3 and UxROM mapper files (checked against Mesen) but no project tooling.
  • Disk images are read with c1541. A tape's standard-format files are decoded; a turbo or custom tape loader needs a decoder written for that loader (tap_extract.py extracts the stub, reports the rest, and the hand-off dump from VICE gets the game itself). Cartridge images are not handled.
  • The reference comes from a medium with the copy protection removed; analysing a protected original is manual work.
  • The tracer is not a full emulator: it does not draw sprites or characters, model collisions, or produce SID output. Checking pictures and sound needs VICE, and the game's owner.
  • The relocation sweep compares the program's state and its timing; it cannot see where data the VIC reads sits.
  • Naming what a thing is to a player needs someone who knows the game; without one, names stay descriptions of what the code does.

Tests

python3 -B scripts/selftest_tools.py
python3 -B scripts/refactor/selftest.py
python3 -B scripts/render/selftest.py
python3 -B scripts/tape/selftest.py

Licence

MIT (see LICENSE): use it freely, all care and no responsibility, with no warranty and no liability.

About

Byte-identical, commented, relocatable Kick Assembler source from C64 disk and tape images: a Claude Code skill (process, rules, tools)

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages