7.2KB

Raw Blame History

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:

Consult AGENTS.md for the system overview and to identify which skill applies
Load the relevant SKILL.md from skills/<topic>/SKILL.md
Reference specific values from files in reference/
Use examples from examples/ as starting points for code
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

7.2KB Raw Blame History