habiclient: Skill for Claude Code

Habitat VICE Automation

Launch VICE, automate the Habitat C64 client boot sequence, and debug game memory.

Usage

Use vice_tool.py in the project root to automate VICE. Write and run Python scripts that import VICESession.

Full boot (through launcher)

from vice_tool import VICESession

with VICESession(verbose=True) as v:
    v.boot_to_game("steve")
    # Game is now running — inspect state
    regs = v.registers()
    print(f"PC=${regs['PC']:04X}")
    print(f"saved_acia_flag = ${v.read_byte(0x6DD9):02X}")

Direct boot (skip launcher + decompressor)

from vice_tool import VICESession

with VICESession(verbose=True) as v:
    v.boot_direct(acia=True, breakpoint=0x7083)
    # Stopped at rs232_open — step through
    regs = v.registers()
    v.step()
    regs = v.registers()
    print(f"A=${regs['A']:02X}")  # Should be $FF if ACIA flag propagated

Step-by-step boot (for debugging launcher stages)

from vice_tool import VICESession

with VICESession(verbose=True) as v:
    v.boot_to_splash()
    # At splash screen — inspect launcher state
    v.dismiss_splash()
    # At modem selection — default is SwiftLink
    v.switch_to_userport()  # Switch to User Port (avoids VICE hang)
    # At login prompt
    v.login("steve")
    v.wait_for_decrunch()
    # Game running

Set breakpoints and wait

from vice_tool import VICESession

with VICESession(verbose=True) as v:
    v.boot_to_splash()
    v.dismiss_splash()
    v.switch_to_userport()
    # Set a breakpoint before login triggers the boot
    v.set_breakpoint(0x0816)  # start_of_program
    v.login("a")
    # Wait for breakpoint hit (up to 120s for decrunch)
    resp = v.go_and_wait(timeout=120)
    regs = v.registers()
    print(f"Hit breakpoint at PC=${regs['PC']:04X}")

API Reference

Lifecycle

Method	Description
launch(disk_image, prg, extra_args, wait)	Start VICE with remote monitor
connect(retries, delay)	TCP connect to monitor port
close()	Close socket + terminate VICE
reconnect(retries, delay)	Close and reopen monitor connection