C64-dev/CLAUDE.md

CLAUDE.md — Commodore 64 Development Agent Configuration

This file configures AI agents (Claude and others) to assist with Commodore 64 application development. Start here. Then follow pointers to AGENTS.md and the skill files.

---

Purpose

This repository is a structured knowledge base for developing software on the Commodore 64, compiled from 11 canonical C64 reference books by a collective of 150 expert C64 developers. It also includes supplemental VICE 3.10 emulator workflow guidance for modern testing and debugging.

Primary Reference

→ Read AGENTS.md first. It contains:

• Complete system overview and memory map
• Skill directory index
• Kernal jump table quick reference
• Zero-page location table
• Common development patterns
• Source book citations

Repository Structure

c64-dev-knowledge/
├── CLAUDE.md                    ← You are here
├── AGENTS.md                    ← Primary AI reference (read this first)
├── skills/
│   ├── 6510-assembly/SKILL.md   ← 6510 CPU, opcodes, addressing
│   ├── memory-map/SKILL.md      ← Memory layout, banking, zero page
│   ├── graphics-vic2/SKILL.md   ← VIC-II chip, sprites, modes
│   ├── sound-sid/SKILL.md       ← SID 6581 sound chip
│   ├── disk-io-1541/SKILL.md    ← 1541 disk drive programming
│   ├── kernal-routines/SKILL.md ← OS routines and vectors
│   ├── basic-programming/SKILL.md ← BASIC 2.0 and extensions
│   ├── interrupts/SKILL.md      ← IRQ, NMI, CIA timers
│   ├── compiler-design/SKILL.md ← Assemblers, compilers for C64
│   └── vice-emulator/SKILL.md   ← VICE launch, autostart, monitor, automation
├── reference/
│   ├── memory-map-complete.md   ← Full address space reference
│   ├── 6510-opcodes.md          ← Complete opcode table
│   ├── kernal-jumplist.md       ← Kernal routine details
│   ├── vic-registers.md         ← VIC-II register map
│   ├── sid-registers.md         ← SID register map
│   ├── cia-registers.md         ← CIA 6526 register map
│   ├── disk-dos-commands.md     ← 1541 DOS commands
│   └── vice-usage.md            ← VICE 3.10 quick reference
└── examples/
    ├── hello-world.asm          ← Assembly hello world
    ├── sprite-demo.bas          ← Sprite programming in BASIC
    ├── sound-demo.bas           ← SID sound in BASIC
    ├── disk-access.bas          ← File I/O examples
    ├── irq-handler.asm          ← Custom IRQ handler
    ├── kernal-io.asm            ← Kernal I/O routines
    ├── vice-autostart-c64os.bat ← Launch c64os.prg in x64sc
    ├── vice-debug-c64os.bat     ← Launch c64os.prg with native monitor
    ├── vice-monitor-c64os.txt   ← VICE monitor playback commands
    └── vice-monitor-c64os-debug.txt ← Repeatable VICE debug session

Agent Instructions

When a user asks a C64 development question:

1. Consult AGENTS.md for the system overview and to identify which skill applies
2. Load the relevant SKILL.md from skills/<topic>/SKILL.md
3. Reference specific values from files in reference/
4. Use examples from examples/ as starting points for code
5. If the task involves emulator execution or debugging, load skills/vice-emulator/SKILL.md

When the task is specifically about debugging a program in VICE, prefer:

• x64sc over the older x64
• -nativemonitor -keepmonopen -refreshonbreak
• sidefx off before inspecting hardware-mapped locations
• watchpoints on $0001, $0314/$0315, and other critical machine state
• repeatable playback files from examples/vice-monitor-c64os-debug.txt

Topic Routing

User asks about...	→ Load skill
6502/6510 assembly, opcodes, registers, addressing	skills/6510-assembly/SKILL.md
Memory layout, PEEK/POKE locations, banking	skills/memory-map/SKILL.md
Sprites, text modes, bitmap, colors, VIC chip	skills/graphics-vic2/SKILL.md
Music, sound effects, SID chip	skills/sound-sid/SKILL.md
Disk operations, loading, saving, file types	skills/disk-io-1541/SKILL.md
OS calls, LOAD/SAVE from ML, I/O from assembly	skills/kernal-routines/SKILL.md
BASIC programming, PEEK/POKE tricks, adding commands	skills/basic-programming/SKILL.md
IRQ handlers, NMI, CIA timers, raster bars	skills/interrupts/SKILL.md
Writing assemblers, compilers, parsers	skills/compiler-design/SKILL.md
Running, testing, or automating code in VICE	skills/vice-emulator/SKILL.md

Expert Conventions (apply to all answers)

• Always use hex addresses with $ prefix (e.g., $D000, $FFD2)
• Always note decimal equivalents for BASIC PEEK/POKE (e.g., 53248)
• Always check memory banking before giving addresses in the $A000–$FFFF range
• Prefer Kernal routines over custom code for standard I/O operations
• Use zero page for frequently-accessed variables (faster indexed addressing)
• Protect ML code from BASIC with POKE 56,<high-byte> : CLR
• Note NTSC/PAL differences for timing-sensitive code (raster, sound frequencies)

Hardware Constraints

Always keep these limits in mind when generating code or advice:

• RAM available to BASIC: ~38KB ($0801–$9FFF = 38911 bytes)
• Free RAM under I/O: $C000–$CFFF (4KB, always RAM)
• 6510 stack: $0100–$01FF (256 bytes, hardware fixed)
• Screen RAM: $0400–$07E7 (default, 1000 bytes)
• Color RAM: $D800–$DBE7 (always at this address, 1000 nybbles)
• VIC-II sees: One 16KB bank at a time (bank selected via CIA #2 $DD00 bits 0-1)
• SID registers: Write-only except $D419–$D41C (paddles/misc)
• Character ROM: Mapped at $D000 when I/O is banked out (not normally accessible via CPU)
• Max sprite data blocks: 256 blocks × 64 bytes = 16KB within VIC bank

Quick-Start Code Templates

BASIC Program with ML Routine

1 REM C64 ML TEMPLATE
10 ML=49152 : REM $C000 - safe ML area
20 POKE 56,192 : CLR : REM PROTECT ML AREA
30 FOR I=ML TO ML+N-1 : READ D : POKE I,D : NEXT
40 SYS ML : REM RUN THE ROUTINE
50 REM ... your BASIC code ...
60000 DATA 96 : REM RTS (minimal routine placeholder)

Assembly Program Skeleton

        ; C64 Assembly Program Template
        ; Assemble to $C000 (49152)
        *=$C000
        
START   JSR $FF81   ; CINT - init screen
        ; ... your code ...
        RTS         ; return to BASIC (if SYS'd)
        ; or JMP $FCE2 to warm-start BASIC

Emulator/Development Tool Notes

Modern C64 development typically uses:

• VICE (emulator) — accurate cycle-level emulation
• KickAssembler, ACME, CA65, 64tass — modern assemblers
• CBM .prg Studio — Windows IDE
• C64 debugger — visual debugger with VICE integration
• Exomizer, Pucrunch — executable crunchers

For period-accurate development (on hardware or accurate emulation):

• SUPERMON — machine language monitor (from ROM books)
• Mikro Assembler, PAL — period assemblers
• Simon's BASIC — extended BASIC with ML-callable routines