Tools for reverse engineering Amiga floppy games, extracted from three finished projects. Entropy maps, packers, a strict 68000 decoder and recompiler, headless emulator captures — and an MCP server so an assistant can hold the same instruments.
pip install amiga-re-kit then arek adf map disk.adf does the same from the terminal.
Load a disk image to see: size and SHA-256, boot block type and checksum, regions by track, packer signatures (PP20, RNC, ATN!, IMP!, …) and Bytekiller blocks verified by their own checksum — the output of `arek adf info` and `arek scan`.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.
| module | what it does | came from |
|---|---|---|
| arek.adf | geometry, boot block checksum, entropy map and regions, inventory record | new |
| arek.packers | PowerPacker 2.0, Bytekiller B and the SWIV word-stream variant, Turrican II three-stage; brute-force scan with verification | SWIV, Turrican II |
| 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 | Superfrog |
| arek.m68k.xref, audit | cross references from objdump listings; profile-driven inventory and reachability as JSON | Superfrog |
| arek.headless | RetroShell scripts, screenshots, breakpoint captures through a patched VAHeadless; the patches are included | Turrican II, Superfrog |
| arek.contract | byte-level comparison of captures, register diffs, "must not touch" assertions | Superfrog |
| arek, arek-mcp | the command line (18 subcommands) and the MCP server (20 tools) | new |
75 tests run on synthetic data only: a hand-assembled 20-byte program, random buffers, a generated boot block.
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" }
}
}
// tools, in the order you will use them
adf_info adf_map adf_regions adf_extract
scan_packed unpack hunk_info hunk_load
disassemble walk hwscan recomp
xref copper ram_at
headless_shot headless_bpstate diff_captures