── WHAT IS IT ──

The Commodore 64 is the best-selling home computer ever made — where a generation learned to program, and to play. Project 64 brings it back — not just for nostalgia, but as a place an AI agent can actually build, run, and debug real 8-bit software end to end: BASIC, 6502 assembly, sprites, and three-voice SID sound.

It drives the open-source VICE emulator through a clean command line (every command speaks JSON) and an MCP server, and includes the machine knowledge — skills, memory maps, a tested cookbook — that an agent needs to get it right.

── CAPABILITIES ──

▸ SESSIONSc64 session

Boot a C64 (NTSC or PAL) headless, in warp, with a disk attached.

▸ BUILDca65 / petcat

Assemble 6502 with cc65 or tokenize BASIC; load and RUN in one step, and link a segment at a fixed address when the VIC has to see it there.

▸ DEBUGbreak / step / watch

Symbolic breakpoints and watchpoints, single-step, memory and register inspection.

▸ WAITthe sync primitive

Block until screen text appears, memory hits a value, or a checkpoint fires.

▸ DISKd64 / d71 / d81

Build a whole game disk from a manifest, copy files in and out, rename and scratch, read and write raw sectors, validate, attach and boot — via c1541.

▸ CARTRIDGEScrt / EasyFlash

Build 8K/16K/Ultimax and bank-switched EasyFlash carts, wrap a .prg, verify, boot, and debug banks live.

▸ ROM TOOLSinfo / disasm

Identify the ROM set and disassemble live memory with symbol annotations.

▸ TEST RUNNERdeclarative YAML

Boot, load, feed input, assert on screen / memory / registers. CI-ready.

▸ MCP + SKILLSagent-native

A 75-command CLI, 74 MCP tools, five skills, memory maps, and a live-tested recipe cookbook — sprites and SID included.

── QUICK START ──

Needs Python 3.11+, VICE 3.5+, and the cc65 suite.

# macOS
brew install vice cc65
python3 -m venv .venv
.venv/bin/pip install -e .

# Debian / Ubuntu (vice is in contrib / multiverse)
sudo apt install vice cc65
python3 -m venv .venv
.venv/bin/pip install -e .

A venv is not optional on Debian 12+ / Ubuntu 23.04+ — the system Python is externally managed (PEP 668). And Debian’s vice package ships without the Commodore ROM images, so x64sc will not boot until you install them from an upstream VICE release; the paths are in /usr/share/doc/vice/README.Debian.

Then drive an emulated C64:

c64 session start                 # boot a C64 (NTSC)
c64 run game.s                    # assemble + load + RUN
c64 screen                        # read the screen as text
c64 break add start               # symbolic breakpoint
c64 wait --break                  # block until it fires
c64 step 5 && c64 reg             # single-step, inspect

Every command takes --json — the interface an agent uses.

── USE WITH AN AI AGENT ──

Any agent with a shell needs zero setup — the CLI plus --json is the whole integration, and MCP-native clients can add c64-tools-mcp, which shares the same sessions. Step-by-step setup for Claude Code, OpenAI Codex, Cursor, Gemini CLI, Google Antigravity and Crush is in the guide.

AGENT SETUP GUIDE ▸

── DEMOS: TRY IT! ──

▶ Play the finished demos in your browser

Ready-to-run prompts in three sets: graded test demos that walk the toolset from a first BASIC program to a full debugger hunt, game demos — complete builds with sprites, custom charsets, and three-voice SID sound — and miscellaneous cool stuff that isn't a game.

Test demos — graded; start at 01 if you're new:

#DemoLanguageDescription
01Guess the numberBASICA number game played to a win — the write→run→verify loop
02Bouncing ball (sprite)BASICA multicolor sprite bounced off all four borders, proved from the VIC-II registers
03Sieve benchmarkBASIC + asmThe sieve written twice and timed off the jiffy clock — the asm speedup, then optimized
04Debug huntBASIC + debuggerA dashboard broken in three layers, found with breakpoints and stepping
05Bach's Invention No. 13BASICA two-part invention on voices 1 and 2, noise percussion on voice 3 — proved by audio capture, a reference score, and a piano roll

Game demos:

DemoLanguageDescriptionScreens
Snake▶ PLAY6502 assemblyArcade Snake on a custom hires charset — held-key steering read off the keyboard matrix, SID sound, nine speeding-up levels
Snake title screen: SNAKE in large block letters in five colours, a green snake reaching for a red apple, and PRESS ANY KEY TO PLAY Snake at level 2: a light green snake curled inside a light blue double-line border, a red apple ahead of it, SCORE 0050 and LEVEL 2 on the status line Snake game over: a panel over the playfield with GAME OVER on a red reverse-video bar, the final score, the high score, and PRESS SPACE TO PLAY AGAIN
Invaders▶ PLAY6502 assemblyThe 1978 arcade original — sprites and custom charset, the one-invader-per-tick march, three-voice SID
Invaders attract screen: INVADERS in large block letters above a score advance table Wave 1 in play: five rows of eleven invaders in cyan, green and red above four green bunkers and the laser base The red mystery saucer crossing the top of the screen while the bunkers show bomb damage
Ms. Muncher▶ PLAY6502 assemblyA maze chase — four rotating mazes, per-ghost targeting AI, six sprites, animated cut scenes
Ms. Muncher attract screen: MS MUNCHER in large block letters above the four named ghosts and a table of top scores Board 1 in play: a blue auto-tiled maze full of yellow dots with four coloured ghosts and Ms. Muncher The same board after an energizer: all four ghosts drawn as blue frightened shapes
La Galaxia▶ PLAY6502 assemblyAn old school shooter in Spanish with a deliberately off-kilter sound track — a 40-enemy formation in character RAM and raster-IRQ sprite multiplexing
Stage 4: the alien formation in cyan, red and yellow with three transformed enemies diving mid-morph, the player fighter below and the Spanish HUD down both sides La Galaxia attract screen: the game name in yellow over a starfield, framed by a bezel with the Spanish HUD down both sides The settled formation: five rows of alien blocks in cyan, red and yellow above the player fighter

Miscellaneous cool stuff:

DemoLanguageDescriptionScreens
1812▶ PLAY6502 assemblyShapes painted to Tchaikovsky's 1812 Overture — bitmap mode, a rotating polygon rasterizer, three-voice SID
The 1812 canvas at the end of the Marseillaise: large blue and red polygons over dithered blue, red and white fills A cannon shot in the 1812 canvas: the border flashed white around a bitmap of red, orange, yellow and blue dithered shapes The finished 1812 canvas: blue, yellow, brown and white shapes layered over the whole bitmap, a blue star among them
Fugue No. 2 in C Minor▶ PLAY6502 assemblyBach's BWV 847 on three SID voices while its score scrolls past — custom charset staves, pitch-class note colors, a sprite backlighting the sounding note
The grand staff before the music starts: five white lines for the treble staff and five for the bass, a treble and bass clef in the left columns, and the first bar line joining them, all on black The scrolling score with all three voices sounding: coloured note heads with flats and sharps beside them across both staves, and three sprite glows lit behind the notes at the fixed now column The closing chord held at the now column with the scroll stopped: two hollow note heads, each backlit by a sprite glow, with the last few notes trailing away to the left
Amiga Ball▶ PLAY6502 assemblyThe Amiga's 1984 Boing Ball on four multicolor sprites — a precomputed sphere texture, a custom-charset grid room, and a SID impact thump
The Boing Ball at floor contact: a red and white checkered sphere with a black rim resting on a light blue perspective floor grid, a grey elliptical shadow beneath it crossed by one of the floor's grid lines, and a purple wall grid above the horizon The ball at the top of its bounce, high in the purple wall grid, with its smallest shadow far below on the light blue floor whose lines converge on the horizon The ball flush against the right edge of the screen at a wall bounce, its shadow tracking it along the floor

Every demo outside the test tier (the game demos and the miscellaneous builds) ships its whole solution beside its prompt once it has been built — sources, plan, fidelity audit, regression test, evidence frames, and a runnable .d64 for stock VICE.