VibeOS CLAUDE.md

VibeOS - Claude Context

IMPORTANT DISK RULES:

• Never look at the disk
• The disk always works
• make run is the only way to compile and run the code - the user will run it
• Trust make run - the user will tell you if it is broken
• Do NOT use hdiutil for anything

Project Overview

VibeOS is a hobby operating system built from scratch for aarch64 (ARM64), targeting QEMU's virt machine. This is a science experiment to see what an LLM can build.

The Vibe

• Aesthetic: Modern macOS-inspired (draggable windows, dock, menu bar)
• Philosophy: Simple, educational, nostalgic
• NOT trying to be: Linux, production-ready, or modern

Current State (Last Updated: Session 40)

• Bootloader (boot/boot.S) - Sets up stack, clears BSS, jumps to kernel
• Minimal kernel (kernel/kernel.c) - UART output working
• Linker script (linker.ld) - Memory layout for QEMU virt
• Makefile - Builds and runs in QEMU
• Boots successfully! Prints to serial console.
• Memory management (kernel/memory.c) - malloc/free working, dynamic heap sizing
• DTB parsing (kernel/dtb.c) - Detects RAM size at runtime from Device Tree
• String functions (kernel/string.c) - memcpy, strlen, strcmp, strtok_r, etc.
• Printf (kernel/printf.c) - %d, %s, %x, %p working
• Framebuffer (kernel/fb.c) - ramfb device, 800x600
• Bitmap font (kernel/font.c) - 8x16 VGA-style font
• Console (kernel/console.c) - Text console with colors on screen
• Virtio keyboard (kernel/keyboard.c) - Full keyboard with shift support
• Shell (kernel/shell.c) - In-kernel shell with commands
• VFS (kernel/vfs.c) - Now backed by FAT32, falls back to in-memory
• Coreutils - ls, cd, pwd, mkdir, touch, rm, cat, echo (with > redirect)
• ELF loader (kernel/elf.c) - Loads PIE binaries with full relocation support
• Process management (kernel/process.c) - Process table, context switching, scheduler
• Cooperative multitasking - yield(), spawn() in kapi, round-robin scheduler
• Kernel API (kernel/kapi.c) - Function pointers for programs to call kernel
• Text editor (kernel/vi.c) - Modal vi clone with normal/insert/command modes
• Virtio block device (kernel/virtio_blk.c) - Read/write disk sectors
• FAT32 filesystem (kernel/fat32.c) - Read/write, full LFN (long filename) support
• Persistent storage - 64MB FAT32 disk image, mountable on macOS
• Interrupts - GIC-400 working! Keyboard via IRQ, boots at EL3 (Secure)
• Timer - 10ms tick (100Hz), used for uptime tracking
• System Monitor - GUI app showing uptime and memory usage
• TextEdit - GUI text editor with Save As modal
• RTC - PL031 real-time clock at 0x09010000, shows actual date/time
• Date command - /bin/date shows current UTC date/time
• Menu bar - Apple menu with About/Quit, File menu, Edit menu
• About dialog - Shows VibeOS version, memory, uptime
• Power management - WFI-based idle, mouse interrupt-driven, 100Hz UI refresh
• Virtio Sound - Audio playback via virtio-sound device, WAV and MP3 support
• Music Player - GUI music player with album/track browser, pause/resume, progress bar
• Floating point - FPU enabled, context switch saves/restores FP regs, calc uses doubles
• Networking - virtio-net driver, Ethernet, ARP, IP, ICMP working!
• Ping command - /bin/ping can ping internet hosts (1.1.1.1, etc.)
• UDP + DNS - hostname resolution via QEMU's DNS server (10.0.2.3)
• TCP - full TCP state machine with 3-way handshake, send/recv, close
• HTTP client - /bin/fetch can make HTTP requests to real websites!
• Web Browser - /bin/browser GUI browser with HTML rendering, works on HTTP sites
• TLS 1.2 - Full HTTPS support via TLSe library, ECC key exchange working!
• HTTPS client - /bin/fetch can make HTTPS requests to google.com, etc!
• Raspberry Pi Zero 2W support - boots on real hardware!
• Pi SD card (EMMC) driver - FAT32 filesystem works, userspace runs!
• Pi USB host (DWC2) - Device enumeration working, HID keyboard via hub works!