<p align="center"> <img src="img/logo.png" alt="Project64 logo" width="360"> </p>

Project64

Project64 is a set of tools, skills, and an MCP to enable agentic Commodore 64 coding and debugging using the VICE emulator.

The Python package is imported as c64lib, installed as c64-tools, and driven by the c64 command-line tool.

Install

Requires Python 3.11+, VICE 3.5+ (provides x64sc and petcat), and the cc65 suite (ca65/ld65, for assembling 6502 programs). Install this package into a virtual environment: Debian 12+, Ubuntu 23.04+, and Homebrew all mark their Python externally-managed (PEP 668), so a bare pip install -e . fails with error: externally-managed-environment.

macOS (Homebrew):

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

Homebrew's VICE bundles the Commodore ROM images, so that is the whole setup.

Debian / Ubuntu:

1. Debian only — enable the contrib component. Ubuntu carries vice in multiverse, on by default; skip to step 2.

sudo add-apt-repository contrib

If that command is missing, add contrib by hand: to the Components: line of /etc/apt/sources.list.d/debian.sources (fresh Debian 13 installs), or to each deb line of /etc/apt/sources.list (Debian 12 and upgraded machines).

2. Install VICE and cc65.

sudo apt update
sudo apt install vice cc65

3. Install the ROMs. The package ships without the Commodore ROM images, and x64sc will not boot until they are installed:

curl -L -o /tmp/vice.tar.gz https://sourceforge.net/projects/vice-emu/files/releases/vice-3.9.tar.gz/download
tar xf /tmp/vice.tar.gz -C /tmp
mkdir -p ~/.local/share/vice
cp -r /tmp/vice-3.9/data/C64 /tmp/vice-3.9/data/DRIVES ~/.local/share/vice/
rm -rf /tmp/vice.tar.gz /tmp/vice-3.9

C64 is the machine ROMs; DRIVES is the drive DOS ROMs that c64 disk commands and --disk boots need.

4. Install c64-tools in a venv.

sudo apt install python3-venv
python3 -m venv .venv
.venv/bin/pip install -e .

Ubuntu 22.04 ships Python 3.10, under this project's 3.11 floor — there, install python3.11 and python3.11-venv and build the venv with python3.11 -m venv .venv.

Then run the tools as .venv/bin/c64 ..., or activate the environment (source .venv/bin/activate) and use c64 directly — as the Quickstart does.

Quickstart

source .venv/bin/activate          # after the Install section above
c64 session start --model c64      # boot an emulated C64 (NTSC)
c64 run tests/programs/hello-basic/program.bas   # tokenize + load + RUN
c64 run tests/programs/hello-asm/program.s       # assemble + load + RUN (needs cc65)
c64 screen                             # read the screen as text
c64 basic type prog.bas --run          # type a program via the keyboard
c64 mem read '$0400' 64                # hex dump of screen RAM
c64 break add start                    # symbolic breakpoint (uses .lbl symbols)
c64 wait --break                       # block until it fires
c64 step 5 && c64 reg                  # single-step, inspect (PC annotated)
c64 continue                           # resume
c64 disk create work.d64 && c64 disk put work.d64 game.prg game
c64 session start --disk work.d64      # boot with the disk attached
c64 disk boot work.d64                 # or attach+run mid-session
c64 build game.s --area 'HIGH=$4000:$2000'   # link a segment at a fixed address
c64 package game.s -o game.crt         # build a bootable cartridge
c64 cart verify game.crt               # catch the silent no-boot cases
c64 run game.crt                       # reboot the session with it mapped
c64 rom info                           # identify the loaded ROM set
c64 rom disasm CHROUT 16               # annotated live disassembly
c64 session stop

c64 test run mytest.yaml               # declarative YAML test (format in docs/cli.md)
c64 test programs                      # run every example program as a test

Every command takes --json for machine-readable output — the intended interface for AI agents.

Documentation

| Reference | What's in it | |---|---| | docs/cli.md | The complete c64 command reference — one entry per command, every flag, and the *.yaml test and disk-manifest formats. | | docs/mcp.md | The CLI↔MCP map: which tool twins which command. Each MCP tool describes itself, so this page maps rather than repeats. | | docs/agent-setup.md | The two integration routes, with config for Claude Code, Codex, Cursor, Gemini CLI, Antigravity, and Crush. | | docs/graphics-and-sprites.md | What demos may use, how sprite and graphic data is authored, and what a test may assert about pixels. |

Domain knowledge — C64 memory maps, KERNAL routines, 6502 idioms, and a cookbook of working recipes — lives in skills/, written to be loaded by an agent rather than read start to finish.

Supported machines

Every session boots a Commodore 64 (--model, default c64). The two profiles differ only in video standard — pick PAL when timing against 50 Hz software:

| Model | RAM | Free at boot | BASIC | Screen | Notes | |-------|-----|--------------|-------|--------|-------| | c64 | 64 KB | 38911 bytes | 2.0 | 40×25 | The default. NTSC (60 Hz); what the demos use. | | c64pal | 64 KB | 38911 bytes | 2.0 | 40×25 | PAL (50 Hz) — different frame rate and slightly different CPU clock. |

The screen is memory-mapped at $0400 (the power-on default; the VIC-II can relocate it); "free at boot" is what BASIC reports, and is the budget a BASIC program (or a SYS-stub assembly program) actually has to fit in.

Using with AI coding agents

This toolset is built to be driven by an AI agent — every c64 command takes --json, the c64-tools-mcp MCP server exposes the same operations, and debugging state (a breakpoint halt) persists across the agent's tool calls. See docs/agent-setup.md for the two integration routes and step-by-step setup for Claude Code, OpenAI Codex, Cursor, Gemini CLI, Google Antigravity, and Crush.

Demos — try it with your AI agent

demos/ is a set of ready-to-run prompts in three tiers. Setup your agent, give it a demo's PROMPT.md, and watch it write, run, and debug real C64 software on the emulated machine.

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

| # | Demo | Language | Description | |---|------|----------|-------------| | 01 | Guess the number | BASIC | A number game played to a win — the write→run→verify loop | | 02 | Bouncing ball (sprite) | BASIC | A multicolor sprite bounced off all four borders, proved from the VIC-II registers | | 03 | Sieve benchmark | BASIC + asm | The sieve written twice and timed off the jiffy clock — the asm speedup, then optimized | | 04 | Debug hunt | BASIC + debugger | A dashboard broken in three layers, found with breakpoints and stepping | | 05 | Bach's Invention No. 13 | BASIC | A 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 — complete builds with sprites, custom charsets, and three-voice SID sound:

| Demo | Language | Description | Screens | |------|----------|-------------|---------| | Snake — ▶ Play | 6502 assembly | Arcade Snake on a custom hires charset — held-key steering read off the keyboard matrix, SID sound, nine speeding-up levels | <img src="demos/snake/evidence/title.png" width="150" alt="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"> <img src="demos/snake/evidence/levelup.png" width="150" alt="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"> <img src="demos/snake/evidence/gameover.png" width="150" alt="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 — ▶ Play | 6502 assembly | The 1978 arcade original — sprites and custom charset, the one-invader-per-tick march, 3-voice SID | <img src="demos/invaders/evidence/title.png" width="150" alt="Invaders attract screen: INVADERS in large block letters above a score advance table"> <img src="demos/invaders/evidence/formation.png" width="150" alt="Wave 1 in play: five rows of eleven invaders in cyan, green and red above four green bunkers and the laser base"> <img src="demos/invaders/evidence/ufo.png" width="150" alt="The red mystery saucer crossing the top of the screen while the bunkers show bomb damage"> | | Ms. Muncher — ▶ Play | 6502 assembly | A maze chase — four rotating mazes, per-ghost targeting AI, six sprites, animated cut scenes | <img src="demos/ms-muncher/evidence/title.png" width="150" alt="Ms. Muncher attract screen: MS MUNCHER in large block letters above the four named ghosts and a table of top scores"> <img src="demos/ms-muncher/evidence/chase.png" width="150" alt="Board 1 in play: a blue auto-tiled maze full of yellow dots with four coloured ghosts and Ms. Muncher"> <img src="demos/ms-muncher/evidence/frightened.png" width="150" alt="The same board after an energizer: all four ghosts drawn as blue frightened shapes"> | | La Galaxia — ▶ Play | 6502 assembly | An old school shooter in Spanish with a deliberately off-kilter sound track — a 40-enemy formation in character RAM and raster-IRQ sprite multiplexing | <img src="demos/la-galaxia/evidence/transform.png" width="150" alt="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"> <img src="demos/la-galaxia/evidence/title.png" width="150" alt="La Galaxia attract screen: the game name in yellow over a starfield, framed by a bezel with the Spanish HUD down both sides"> <img src="demos/la-galaxia/evidence/formation.png" width="150" alt="The settled formation: five rows of alien blocks in cyan, red and yellow above the player fighter"> |

Miscellaneous cool stuff:

| Demo | Language | Description | Screens | |------|----------|-------------|---------| | 1812 — ▶ Play | 6502 assembly | Shapes painted to Tchaikovsky's 1812 Overture — bitmap mode, a rotating polygon rasterizer, 3-voice SID | <img src="demos/1812/evidence/sec1.png" width="150" alt="The 1812 canvas at the end of the Marseillaise: large blue and red polygons over dithered blue, red and white fills"> <img src="demos/1812/evidence/cannon.png" width="150" alt="A cannon shot in the 1812 canvas: the border flashed white around a bitmap of red, orange, yellow and blue dithered shapes"> <img src="demos/1812/evidence/final.png" width="150" alt="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 — ▶ Play |