The kit was built to be driven by an AI agent. A one-page brief tells the agent the rules (measure, never guess; game data stays out of git), how to set the kit up and the order of the steps. Claude Code reads it as CLAUDE.md; any other agent takes it as the first message.
Download the brief (arek-agent.md)
Four steps, nothing else to configure. The agent asks you for the path to your disk image; the image stays on your machine.
pip install "amiga-re-kit[mcp]"
mkdir mygame && cd mygame && arek init .
# put the .adf path into local.conf (ADF1=…)
# save arek-agent.md here as CLAUDE.md
claude # "Read CLAUDE.md and measure the disk."Each step produces a measurement the next step is checked against. Nothing downstream rests on a guess, which is why documents built this way can be trusted by someone who has never seen the game.
Size, SHA-256, boot block. Every later claim refers to this exact image; cracked dumps differ.
Where the code is, where the packed blob is, how many files there probably are — before one instruction is decoded.
Walk the boot block, follow the trackloader to the next stage, find packers by signature or by reading the decrunch routine. Verify each unpacker byte for byte against the emulator's RAM.
Read the file table the way the loader reads it. Data formats have many plausible readings; code has one.
Which routines are pure computation and which really drive Agnus, Denise and Paula. Usually most of a game is the former.
68k to C, routine by routine, run on a RAM capture of the original and compared with a capture taken after. Equal or not done.
Deterministic screenshots from the headless emulator at known times, with scripted input, as regression checkpoints.
The long version with commands: docs/METHOD.md. The headless vAmiga setup: docs/HEADLESS.md.
The MCP server exposes the same instruments to Claude Code or any MCP client. Every tool takes paths on your machine and returns a measurement — an entropy map, a listing, a diff — never the image itself. A session reads like a lab notebook: map the disk, scan for packed blocks, unpack the one at 0x1f40 and walk it from its entry, say which routines touch hardware, recompile one and compare its writes with a capture of the original.
Install with pip install "amiga-re-kit[mcp]" and register the server:
// .mcp.json in your project
{
"mcpServers": {
"arek": { "command": "arek-mcp" }
}
}
// the 26 tools, in the order you will use them
kit_info adf_info adf_map adf_regions
adf_ls adf_file adf_extract scan_packed
unpack hunk_info hunk_load disassemble
walk hwscan xref copper
recomp recomp_profile ram_at headless_shot
headless_bpstate diff_captures render trace_records
trace_compare trace_bus| module | what it does | came from |
|---|---|---|
| arek.adf | geometry, boot block checksum, entropy map and regions, inventory record | new |
| arek.amigados | OFS/FFS file system reader: directory listing, file extraction, safe paths | Alien Breed |
| arek.packers | PowerPacker 2.0, Bytekiller B and the SWIV word-stream variant, Turrican II three-stage, Atomik (ATN!); brute-force scan with verification | SWIV, Turrican II, Superfrog |
| arek.hunk | bounded AmigaDOS HUNK reader: CODE/DATA/BSS, RELOC32, split streams; a builder for small probes | Superfrog |
| arek.copper | copper list disassembler with custom register names | SWIV |
| arek.m68k.decoder | strict 68000 decoder that raises on anything it does not model; flow-graph walker that reports frontiers | Superfrog |
| arek.m68k.hwscan | pure-RAM routines versus hardware routines, with unknown address-register bases kept explicit | Turrican II |
| arek.m68k.recomp | static 68k to C with a verification driver: RAM in, RAM and write log out; jump tables, indirect targets, external routines, overlay modules, optional clock counting | Superfrog, Alien Breed |
| arek.m68k.timing | 68000 clock count of every instruction, data-dependent ones included; matches Moira on all 42 247 decodable opcodes | new |
| arek.m68k.xref, audit | cross references from objdump listings; profile-driven inventory and reachability as JSON | Superfrog |
| arek.headless | RetroShell scripts, screenshots, breakpoint captures and continuous traces through a patched VAHeadless; the patches are included | Turrican II, Superfrog, Alien Breed |
| arek.contract | byte-level comparison of captures, register diffs, "must not touch" assertions | Superfrog |
| arek.m68k.profile | per-routine calls, clocks and memory pages from a profiled recompilation: which routines an enhancement has to touch | new |
| arek.display, parity | a frame rendered from chip RAM with vAmiga's colour pipeline, 0 pixels off; long-run parity of a rebuild against the emulator's register and input logs | Turrican II, Alien Breed, Superfrog |
| arek.seal, web | what a playable page needs: the display contract (whole device pixels, CRT, tests), code sealed to the visitor's own disk, a checker for the published bundle; the canon of a smooth picture and sound (the presenter on the GPU, the clock, the sound over shared memory, the scene composed on the GPU from one record per game frame with a CPU reference, the measurement) | Alien Breed, Superfrog, Alien Breed II |
| arek.m68k.cover, fuzz, parity suite | coverage of a translation run and random input for both sides (where a long run stalls, a bug hides); a suite of scenarios against the original: state, picture, sound per tick | Superfrog |
| arek.m68k.timing.bus | bus cycles of every instruction, not only its clocks: what a model of the Amiga bus per DMA slot needs | Alien Breed |
| arek.bus | the Amiga bus per DMA slot for recompiled games: who owns each slot, the blitter cycle by cycle, the CPU by its accesses - on which instruction an interrupt lands, when a blit ends, whether the original overran the frame; checked against the emulator's bus log by arek selftest bus | Alien Breed |
| arek, arek-mcp | the command line (32 subcommands) and the MCP server (26 tools) | new |
2482 tests: synthetic data (hand-assembled programs, random buffers, generated boot blocks and disk images) and 68000 clock counts measured on Moira.