── WHAT IS IT ──

The Commodore PET was where a generation learned to program. PET Project 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.

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 ──

▸ SESSIONSpet session

Boot any PET model (2001–8296) headless, in warp, with a disk attached.

▸ BUILDca65 / petcat

Assemble 6502 with cc65 or tokenize BASIC; load and RUN in one step.

▸ 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 / d80 / d82

Create images, copy files in and out, attach and boot — via c1541.

▸ 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

~30 MCP tools plus skills, memory maps, and a tested recipe cookbook.

── QUICK START ──

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

# macOS
brew install vice cc65
pip install -e .

Then drive an emulated PET:

pet session start --model pet4032 # boot a PET 4032
pet run game.s                    # assemble + load + RUN
pet screen                        # read the screen as text
pet break add start               # symbolic breakpoint
pet wait --break                  # block until it fires
pet step 5 && pet 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. For MCP-native clients, pet-tools-mcp exposes the same operations. Pick your agent:

  1. Install the skills: mkdir -p .claude/skills && cp -R skills/* .claude/skills/
  2. Optional MCP: claude mcp add pet-tools -- pet-tools-mcp
  3. Ask for what you want — e.g. paste a prompt from demos/.

No CLAUDE.md edits needed — installed skills load on demand.

── DEMOS: TRY IT! ──

Ready-to-paste prompts, graded from a first BASIC program up to Snake in assembly. Each is validated by handing it to a real agent and confirming the result. 01–04 pass on the first attempt.

#DemoLanguageStatus
01Guess the numberBASIC[OK] passed
02Bouncing ballBASIC[OK] passed
03Sieve benchmarkBASIC + asm[OK] passed (asm 93x faster than BASIC)
04Snake6502 assembly[OK] passed
05Debug huntBASIC + debugger[ ] queued