# 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`](./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//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, : 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 ```basic 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 ```asm ; 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