How I Use Claude Code to Develop MAME and CoCo Software

How I Use Claude Code to Develop MAME and CoCo Software

Nov 20, 2026 · tim lindner

I use Claude Code as a pair programmer for two jobs: improving MAME’s Tandy Color Computer (CoCo) and Dragon drivers, and writing and debugging CoCo software that I then run in MAME. The short version is that it works best when I treat it like a capable new hire. I write down how my tree works, I let it keep notes, and I give it ways to check its own work without me watching the screen.

In the last few weeks that setup produced 6809 interrupt-latency and undocumented-opcode fixes, a timing pass that makes Stewart Orchard’s Dragon test suite pass, a Multi-Pak that takes 1 to 16 slots, and the EMUDSK and Becker ports moved out of the drivers into proper cartridges. This post is about the habits behind that, not the code itself.

Building the same setup

The whole setup is a MAME fork, a debug build, one instructions file and a few skills. You can have it working in an afternoon.

  1. Install Claude Code. I use the Claude desktop app’s Code tab on macOS; the claude command-line tool works the same way. Open it in the root of your MAME checkout.

  2. Fork and clone MAME. Clone your own fork, add mamedev as a second remote named upstream, and make sure you can build it by hand first. MAME’s compiling documentation lists the toolchain for each platform.

  3. Write useroptions.mak. This file at the top of the tree is where MAME’s makefile picks up local options. Mine builds a debug binary (mamed) with the native macOS OSD and the tools, and limits the drivers to the ones I’m working on:

    SOURCES = src/mame/trs/coco12.cpp,src/mame/trs/coco3.cpp,src/mame/trs/dragon.cpp
    DEBUG = 1
    OSD = mac
    TOOLS = 1
    ARCHOPTS = -march=native
    ARCHOPTS_CXX = "-ferror-limit=1"
    

    The driver subset turns a full build into a few minutes. -ferror-limit=1 keeps compiler output short, which matters when Claude is the one reading it.

  4. Write CLAUDE.md. Put your build commands, your rules and your testing habits in it. Start from my general version (linked in the CLAUDE.md section below). Leave it untracked if you don’t want it in your fork, and tell Claude it is a baseline file so it never commits it.

  5. Leave memory on. Claude Code keeps per-project memory files and an index by default. You don’t seed it; you tell Claude “remember this” after a hard-won fix, and it writes the note.

  6. Add the 6809 skills. Build follow9 and coco-programming as personal skills; the next section walks through both.

  7. Collect test media. Keep ROMs, disk images, cartridges and test suites in a folder next to the MAME tree, and give Claude a separate folder outside the repo for scripts worth keeping. The session scratch space gets cleared.

  8. Keep real hardware within reach. Emulator fixes need a referee. Mine are a CoCo 3, a CoCo 1 with a 6309 and an FTDI serial cable.

Installing the skills

A skill is just a folder: a SKILL.md whose front matter says when to use it, plus any scripts and references it needs. Personal skills go in ~/.claude/skills/<name>/ and show up in every project. You don’t need a packaging tool; Claude can build the folder for you from a repository or a document.

follow9, from a GitHub repository

follow9 is my code-following 6809/6309 disassembler. It is plain JavaScript with a command-line front end, so the skill only has to wrap it.

  1. Clone the repository: git clone https://github.com/tlindner/follow9.git.

  2. Lay out the skill folder, copying follow9.js, follow9-cli.js, AGENT_USAGE.md and LICENSE.md from the clone:

    ~/.claude/skills/follow9/
      SKILL.md
      LICENSE.md
      references/AGENT_USAGE.md
      scripts/follow9.js
      scripts/follow9-cli.js
    
  3. Write SKILL.md. The description line is what Claude matches against your request, so make it name the file types and the situations:

    ---
    name: follow9
    description: Disassemble Motorola 6809 and Hitachi HD6309 machine code with a code-following disassembler that routes around data segments. Use when the user wants to disassemble, reverse engineer, or inspect a 6809/6309 binary, including CoCo raw or DECB .bin files, Dragon programs, and OS-9 modules.
    ---
    
    Run the bundled CLI with Node.js 18 or later:
    node "${CLAUDE_SKILL_DIR}/scripts/follow9-cli.js" [options] FILE
    See references/AGENT_USAGE.md for the options.
    
  4. Start a new session and ask Claude to disassemble a .bin. It should load the skill without being told to.

The shortcut is to point Claude at the repository and say “make a personal skill from this”. It reads the README and usage notes, copies the files and writes the SKILL.md. Check the description it writes, because that line decides when the skill gets used.

coco-programming, from a GitHub gist

A skill doesn’t need code. coco-programming is a single Markdown document of CoCo know-how for writing, building and debugging CoCo software: 6809/6309 assembly, C with CMOC, Disk BASIC and OS-9 targets.

  1. Make the folder: mkdir -p ~/.claude/skills/coco-programming.

  2. Download the gist’s raw Markdown into it as SKILL.md: curl -L -o ~/.claude/skills/coco-programming/SKILL.md https://gist.githubusercontent.com/tlindner/96a2b43b791c75e47c116a67d12338a8/raw/SKILL.md.

  3. If the file doesn’t already start with front matter, add it:

    ---
    name: coco-programming
    description: Use when writing, building, debugging or packaging software for the TRS-80 Color Computer (6809/6309 assembly, C via CMOC, Disk BASIC or OS-9/NitrOS-9 targets).
    ---
    
  4. Read the document before you install it. A skill is instructions Claude will follow, so treat one from someone else’s gist like code you are about to run.

Mine is published as a public gist, and it already has its front matter. Before using it, edit the one marked line under “Testing in MAME” to point at your own MAME binary and ROM path.

CLAUDE.md: the build notes I used to keep in my head

A one-page CLAUDE.md at the top of my MAME checkout does more than any clever prompt. MAME’s build has sharp edges, and every one of them used to cost a wasted half hour until I wrote it down.

  • Driver subset. useroptions.mak sets SOURCES so I build only the CoCo and Dragon drivers. Claude checks it before each job and edits it directly instead of passing command-line overrides.
  • Which rebuild. Changing the driver list needs make REGENIE=1. Adding a source file means finding the right Lua build script and adding a line next to its neighbours. Changing compile options needs make clean, which takes 30 minutes on the MacBook Pro, so it must ask me first.
  • Job count by machine. It runs hostname first: -j15 on the Mac mini, -j5 on the laptop.
  • What success looks like. If nothing needs compiling, make prints only the Clang version. Without that line it kept deciding a clean build had failed.
  • Where things live. CoCo drivers are in src/mame/trs/; a lot of CoCo behaviour is in the cartridge bus, src/devices/bus/coco/.

The same file also holds the testing rules and the guardrails covered below. I keep an identical AGENTS.md beside it for other tools.

A general version is published as a public gist. Drop it at the top of your MAME checkout and change every line marked EDIT for your own machines, drivers and local patches.

Memory: lessons that survive the session

CLAUDE.md holds rules I wrote; Claude Code’s memory holds facts it learned the hard way. Each memory is a small file with a one-line index entry, and the next session reads the index before it starts. Mine has 13 entries, and most of them record a debugging session I never want to repeat.

MemoryWhat it saves me from
Full build after a subset leaves a stale drivlistRemoving SOURCES rebuilt every driver but mamed still listed 1,018 machines. Delete drivlist.cpp, then check -listfull, not the exit code.
Media names changed on the cartridge branchAfter EMUDSK became a cartridge, the IDE cartridge’s image is -hard, not -hard3, so old recipes need checking.
MAME opportunitiesA backlog of bugs found in passing, such as uninitialised SSD1306 SPI flags that blank the Arduboy screen. I ask for the list when I want a small upstream PR.

The memories also point at each other, so a test recipe links to the notes it depends on. I let Claude write and update them, and I delete any that turn out wrong.

Letting Claude run MAME itself

The biggest gain came from letting Claude test its own changes in MAME instead of asking me to look. MAME’s Lua console and debugger make the emulator scriptable, so the loop runs without me.

  1. Ask first. Before a test, Claude asks whether I want to watch. If I do, it runs ./mamed coco -console -debug -window with the native debugger. If not, it runs headless with -video none -debugger none.
  2. Start clean. It deletes the .cfg files in cfg/ at the start of a session, so input settings from an old run don’t skew the new one.
  3. Drive it from Lua. A persistent PTY session talks to the Lua console. For longer runs it uses an -autoboot_script that pokes a binary into RAM, posts keystrokes, presses joystick fields and takes snapshots on a timer.
  4. Read memory, not pictures. Checking a text screen from a screenshot wastes tokens, so the rule is to dump video RAM and read the characters. Snapshots are kept for graphics tests, where a script checks pixel colours.
  5. Compare against ground truth. That means a second MAME build or my real CoCo 3.

A few things only came from experience. With -video none, frame notifiers never fire, so timed scripts use emu.register_periodic. Two MAME snapshots of the same screen always differ by md5 because of the version string, so A/B checks compare decoded pixels. Each soft reset re-runs the autoboot script, so command pollers need marker files. All of that lives in a reusable harness folder outside the repo, which Claude extends instead of rewriting.

For visible debugging I carry a patch from MAME issue 15272 in the debugger code. CLAUDE.md says to check for it before a visible test and to apply it in a fresh worktree, and never to commit it.

Skills for 6809 work

Skills are packaged instructions that Claude loads when a task calls for them. Two of mine cover the CoCo side.

  • follow9 disassembles 6809 and 6309 code with a code-following disassembler that steps around data. It reads raw and DECB .bin files, Dragon programs and OS-9 modules.
  • coco-programming covers writing and building CoCo software: assembly, C with CMOC, Disk BASIC and OS-9 targets.

The split matters. Reading code is cheap, and MAME is for anything with timing or hardware in it. Having both named means Claude picks the cheapest tool that answers the question.

Four examples

Dragon and CoCo video timing. Stewart Orchard’s timing suite draws a checkerboard and a highlighted square that must land exactly on it. Claude wrote a Lua harness that loads each test, presses the menu keys, snapshots and checks the highlight’s pixels, covering seven machines in about a minute. The fixes included a keyboard-matrix refresh regression, 6809 IRQ/FIRQ latching and SYNC wake timing, and a CoCo master clock of 14,318,176 Hz so the CPU and VDG stop drifting apart. Claude also ported the suite to the NTSC CoCo, and my real CoCo matched MAME on every test.

Undocumented 6809 behaviour. Claude compared MAME against published research on undocumented opcodes and found six gaps. A small test program run on a real CoCo 3 passed all 14 checks where MAME failed 13. That made the fix an easy decision.

Cartridges and the Multi-Pak. The Multi-Pak is now a template for 1 to 16 slots, and the EMUDSK virtual disk and Becker port are cartridges instead of driver options. Claude tested the Becker cart end to end: a DriveWire server on port 6809, HDB-DOS in a Multi-Pak beside a floppy controller, a Lua write to $FF7F to route the slot selects, then DIR listing the served disk.

Regressions I wouldn’t have caught. On one branch, OS-9 stored a 257th byte off the end of a sector buffer. The cause was the cartridge NMI and HALT delays being 12 and 6 cycles. Before changing them, Claude ran a regression pass under both settings: floppy and IDE boots, Disk BASIC writes compared byte for byte, and OS-9 Level 2. For a CPU change that touched arcade games too, it built master and the branch, ran attract modes headless, and gave me stereo MP3s with master on the left and the branch on the right to listen to.

Guardrails

MAME is a shared upstream project, so the rules are mostly about keeping my mess out of it.

  • Origin, never upstream. Claude may commit or push to my fork when I tell it to, and never to mamedev.
  • Match the code around you. No reformatting lines it isn’t changing; follow the surrounding style. MAME reviewers notice.
  • Baseline edits stay put. The debugger patch and the untracked CLAUDE.md and AGENTS.md are always in my working tree. Claude carries them across branch switches, never commits them, and doesn’t report them as surprises.
  • Hands off the built-in tests. scripts/src/tests.lua is off limits; external harnesses are fine.
  • Clean commits. No Claude co-author line and no LLM prefix on branch names.
  • Ask before the slow or risky step. make clean, and whether I want to watch the screen, are my call.

What works and what doesn’t

It works when Claude can check its own answer. A timing fix verified by a pixel check across seven machines is worth more than any explanation of why it should work. The memory file is the second big win: a pitfall found once stays found.

It still needs me for:

  • Real hardware. The emulator can only be checked against something, and in the end that is my CoCo 3, my CoCo 1 with a 6309, and an FTDI cable. Several memories exist only because the real machine disagreed with everyone’s assumptions.
  • Judgement calls. Whether the Becker cart gets a pass-through slot, or whether a fix belongs in the CPU or the cartridge, are design choices. Claude lays out the options and I pick.
  • Some input. Driving a CoCo menu from Lua is still fiddly. Posting a down-arrow keystroke didn’t move one menu’s cursor, so the script holds the key’s input field for a dozen frames instead.

If you want to try this on your own MAME tree, start small: a CLAUDE.md with your build commands and your rules, one headless test you trust, and permission for Claude to write down what it learns.