CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Running VMs

```
./launch.sh
```
- Interactive menu-driven launcher for VMs and ISOs
```
./run-mac.sh --config <vm_config_file>
```
- Launch a specific VM configuration

./run-mac.sh --config <vm_config_file> --iso <iso_file>

- Launch VM with attached ISO

./run-mac.sh --config <vm_config_file> --iso <iso_file> --boot-from-cd

- Boot from CD/ISO

```
./run-mac.sh --create-config <vm_name>
```
- Create new VM configuration interactively with optional default installer selection

Software Management

```
./iso-downloader.sh
```
- Interactive downloader for operating systems and software from the database
Supports
```
"delivery": "shared"
```
for direct downloads to the shared disk system
Custom software can be added to
```
iso/custom-software.json
```
to extend the available downloads

File Transfer System

```
./mount-shared.sh
```
- Mount shared disk on host for file transfer
```
./mount-shared.sh -u
```
- Unmount shared disk
Shared disk appears as additional drive in all VMs (auto-created on first run)

Dependencies

Required tools:

qemu-system-m68k

qemu-system-ppc

qemu-img

jq

curl

unzip

hfsprogs

(Ubuntu) or

hfsutils

(macOS)

Architecture Overview

VM Management System

The project provides a complete QEMU-based classic Macintosh emulation environment supporting two architectures:

m68k Architecture (Macintosh Quadra):

Uses
```
qemu-system-m68k
```
with q800 machine type
ROM file at
```
roms/800.ROM
```
(auto-downloaded on first run)
Uses PRAM file for boot device selection (SCSI-based)
Typical RAM: 128M, disk: 2G
SCSI device configuration with customizable IDs

PPC Architecture (PowerMac G4):

Uses
```
qemu-system-ppc
```
with mac99 machine type
No ROM file required (built into QEMU)
Uses bootindex for boot device selection
Typical RAM: 512M, disk: 10G
IDE device configuration with USB keyboard/mouse support

Key Components

```
run-mac.sh
```
: Core VM runner with architecture-specific QEMU argument building and an integrated interactive launcher.
```
iso-downloader.sh
```
: Software acquisition from JSON database
```
vms/
```
: Directory containing VM configurations and disk images
```
iso/
```
: Directory for ISO files and software database
```
roms/
```
: Directory for ROM files (auto-downloaded as needed)
```
shared/
```
: Cross-VM shared disk directory (auto-created)

Default VM Configurations

The project includes 4 pre-configured VMs ready for immediate use:

PowerPC VMs:

```
vms/power_mac_g4_os9/
```
- PowerMac G4 with Mac OS 9.2.2 (DEFAULT_INSTALLER="macos922")
```
vms/power_mac_g4_tiger/
```
- PowerMac G4 with Mac OS X Tiger (DEFAULT_INSTALLER="macos_x_tiger")
```
vms/power_mac_g4_leopard/
```
- PowerMac G4 with Mac OS X Leopard (DEFAULT_INSTALLER="macos_x_leopard")

68k VM:

```
vms/68k_quadra_800/
```
- Quadra 800 with classic Mac OS (DEFAULT_INSTALLER="apple_legacy_recovery")

All default VMs include automatic installer setup - first boot downloads and configures the OS, subsequent boots use the hard drive.

VM Configuration Format

VM configs are bash files defining variables:

```
ARCH
```
: "m68k" or "ppc"
```
MACHINE_TYPE
```
: QEMU machine type
```
RAM_SIZE
```
: Memory allocation
```
HD_SIZE
```
: Disk size for new VMs
```
HD_IMAGE
```
: Path to disk image
Architecture-specific settings (PRAM_FILE, SCSI IDs for m68k)
```
SHARED_SCSI_ID
```
: SCSI ID for shared disk (m68k only, defaults to 4)
```
DEFAULT_INSTALLER
```
: Optional installer key for first-run automatic setup

Boot Device Handling

m68k: PRAM file is patched with SCSI RefNum calculations for boot device selection
PPC: Uses QEMU's bootindex parameter for IDE devices

First-Run Installer System

Automatic Setup: VMs with
```
DEFAULT_INSTALLER
```
automatically download and configure installer on first boot
ROM Auto-Download: m68k VMs automatically download required ROM file if missing
Architecture Filtering: Only compatible installers are offered during VM creation
Seamless Experience: First boot automatically boots from installer, subsequent boots use hard drive
Optional Feature: Can be skipped during VM creation for manual setup

Shared Disk System

Single shared disk: 512MB HFS-formatted disk accessible by all VMs
Cross-architecture support: Works with both m68k (SCSI) and PPC (IDE) VMs
Automatic creation: Created on first VM run, format as HFS from within Mac OS
Host mounting: Simple loop mount via
```
mount-shared.sh
```
script at
```
/tmp/qemu-shared
```
File transfer: Easy way to move files between host and all Mac VMs
Direct software delivery: Software with
```
"delivery": "shared"
```
downloads directly to shared disk

Display and Input

Automatically detects host OS (macOS uses Cocoa, Linux uses SDL)
Host-specific keyboard shortcuts and mouse handling
Color-coded terminal output for user guidance

Performance Optimizations

Built-in Performance Features

QemuMac automatically applies performance optimizations without requiring configuration:

Storage I/O Optimization:

```
cache=writeback
```
for 50-80% faster disk operations
```
aio=threads
```
backend for universal compatibility
```
detect-zeroes=on
```
for space-efficient storage

CPU Model Accuracy:

m68k: Uses
```
m68040
```
CPU model (authentic Quadra 800 processor)
PPC: Uses
```
7400_v2.9
```
CPU model (authentic PowerMac G4 processor)
Provides proper instruction timing and enhanced compatibility

Implementation Details:

```
detect_aio_backend()
```
function automatically selects compatible AIO backend
Performance status messages inform users of active optimizations
All optimizations tested for stability and compatibility across QEMU versions

Performance Impact

Boot times: Significantly reduced
File operations: 50-80% faster with writeback caching
Overall responsiveness: Noticeably improved
Compatibility: Enhanced with authentic CPU models

Technical Notes

Multi-threaded TCG avoided due to m68k/PPC compatibility issues
Storage optimization prioritized as highest-impact improvement
All changes maintain backward compatibility with existing VM configurations

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Running VMs

```
./launch.sh
```
- Interactive menu-driven launcher for VMs and ISOs
```
./run-mac.sh --config <vm_config_file>
```
- Launch a specific VM configuration

./run-mac.sh --config <vm_config_file> --iso <iso_file>

- Launch VM with attached ISO

./run-mac.sh --config <vm_config_file> --iso <iso_file> --boot-from-cd

- Boot from CD/ISO

```
./run-mac.sh --create-config <vm_name>
```
- Create new VM configuration interactively with optional default installer selection

Software Management

```
./iso-downloader.sh
```
- Interactive downloader for operating systems and software from the database
Supports
```
"delivery": "shared"
```
for direct downloads to the shared disk system
Custom software can be added to
```
iso/custom-software.json
```
to extend the available downloads

File Transfer System

```
./mount-shared.sh
```
- Mount shared disk on host for file transfer
```
./mount-shared.sh -u
```
- Unmount shared disk
Shared disk appears as additional drive in all VMs (auto-created on first run)

Dependencies

Required tools:

qemu-system-m68k

qemu-system-ppc

qemu-img

jq

curl

unzip

hfsprogs

(Ubuntu) or

hfsutils

(macOS)

Architecture Overview

VM Management System

The project provides a complete QEMU-based classic Macintosh emulation environment supporting two architectures:

m68k Architecture (Macintosh Quadra):

Uses
```
qemu-system-m68k
```
with q800 machine type
ROM file at
```
roms/800.ROM
```
(auto-downloaded on first run)
Uses PRAM file for boot device selection (SCSI-based)
Typical RAM: 128M, disk: 2G
SCSI device configuration with customizable IDs

PPC Architecture (PowerMac G4):

Uses
```
qemu-system-ppc
```
with mac99 machine type
No ROM file required (built into QEMU)
Uses bootindex for boot device selection
Typical RAM: 512M, disk: 10G
IDE device configuration with USB keyboard/mouse support

Key Components

```
run-mac.sh
```
: Core VM runner with architecture-specific QEMU argument building and an integrated interactive launcher.
```
iso-downloader.sh
```
: Software acquisition from JSON database
```
vms/
```
: Directory containing VM configurations and disk images
```
iso/
```
: Directory for ISO files and software database
```
roms/
```
: Directory for ROM files (auto-downloaded as needed)
```
shared/
```
: Cross-VM shared disk directory (auto-created)

Default VM Configurations

The project includes 4 pre-configured VMs ready for immediate use:

PowerPC VMs:

```
vms/power_mac_g4_os9/
```
- PowerMac G4 with Mac OS 9.2.2 (DEFAULT_INSTALLER="macos922")
```
vms/power_mac_g4_tiger/
```
- PowerMac G4 with Mac OS X Tiger (DEFAULT_INSTALLER="macos_x_tiger")
```
vms/power_mac_g4_leopard/
```
- PowerMac G4 with Mac OS X Leopard (DEFAULT_INSTALLER="macos_x_leopard")

68k VM:

```
vms/68k_quadra_800/
```
- Quadra 800 with classic Mac OS (DEFAULT_INSTALLER="apple_legacy_recovery")

All default VMs include automatic installer setup - first boot downloads and configures the OS, subsequent boots use the hard drive.

VM Configuration Format

VM configs are bash files defining variables:

```
ARCH
```
: "m68k" or "ppc"
```
MACHINE_TYPE
```
: QEMU machine type
```
RAM_SIZE
```
: Memory allocation
```
HD_SIZE
```
: Disk size for new VMs
```
HD_IMAGE
```
: Path to disk image
Architecture-specific settings (PRAM_FILE, SCSI IDs for m68k)
```
SHARED_SCSI_ID
```
: SCSI ID for shared disk (m68k only, defaults to 4)
```
DEFAULT_INSTALLER
```
: Optional installer key for first-run automatic setup

Boot Device Handling

m68k: PRAM file is patched with SCSI RefNum calculations for boot device selection
PPC: Uses QEMU's bootindex parameter for IDE devices

First-Run Installer System

Automatic Setup: VMs with
```
DEFAULT_INSTALLER
```
automatically download and configure installer on first boot
ROM Auto-Download: m68k VMs automatically download required ROM file if missing
Architecture Filtering: Only compatible installers are offered during VM creation
Seamless Experience: First boot automatically boots from installer, subsequent boots use hard drive
Optional Feature: Can be skipped during VM creation for manual setup

Shared Disk System

Single shared disk: 512MB HFS-formatted disk accessible by all VMs
Cross-architecture support: Works with both m68k (SCSI) and PPC (IDE) VMs
Automatic creation: Created on first VM run, format as HFS from within Mac OS
Host mounting: Simple loop mount via
```
mount-shared.sh
```
script at
```
/tmp/qemu-shared
```
File transfer: Easy way to move files between host and all Mac VMs
Direct software delivery: Software with
```
"delivery": "shared"
```
downloads directly to shared disk

Display and Input

Automatically detects host OS (macOS uses Cocoa, Linux uses SDL)
Host-specific keyboard shortcuts and mouse handling
Color-coded terminal output for user guidance

Performance Optimizations

Built-in Performance Features

QemuMac automatically applies performance optimizations without requiring configuration:

Storage I/O Optimization:

```
cache=writeback
```
for 50-80% faster disk operations
```
aio=threads
```
backend for universal compatibility
```
detect-zeroes=on
```
for space-efficient storage

CPU Model Accuracy:

m68k: Uses
```
m68040
```
CPU model (authentic Quadra 800 processor)
PPC: Uses
```
7400_v2.9
```
CPU model (authentic PowerMac G4 processor)
Provides proper instruction timing and enhanced compatibility

Implementation Details:

```
detect_aio_backend()
```
function automatically selects compatible AIO backend
Performance status messages inform users of active optimizations
All optimizations tested for stability and compatibility across QEMU versions

Performance Impact

Boot times: Significantly reduced
File operations: 50-80% faster with writeback caching
Overall responsiveness: Noticeably improved
Compatibility: Enhanced with authentic CPU models

Technical Notes

Multi-threaded TCG avoided due to m68k/PPC compatibility issues
Storage optimization prioritized as highest-impact improvement
All changes maintain backward compatibility with existing VM configurations

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password