VibeOS

A hobby OS vibecoded completely from scratch with Claude Code. Not everything works, some stuff is not even tested, but most things do.

What is this?

VibeOS is an operating system written from scratch for ARM64 (aarch64). It runs on QEMU and real Raspberry Pi Zero 2W. The entire OS was built in collaboration with Claude over 64 sessions, documented in the session logs.

Compile error due to missing tlse.c?

cd vendor/

git clone https://github.com/kaansenol5/tlse

No DOOM?

You need to find doom1.wad (google it) and put it in vibeos_root/games/doom1.wad

Features

Core

• Custom kernel with cooperative multitasking (preemptive backup)
• FAT32 filesystem with long filename support
• Memory allocator, process scheduler, interrupt handling
• GIC-400 (QEMU) and BCM2836/BCM2835 (Pi) interrupt controllers
• Configurable boot (splash screen, boot target)

GUI

• Desktop environment with draggable windows
• Menu bar, dock, window minimize/maximize/close
• Mouse and keyboard input
• Modern macOS-inspired aesthetic

Networking

• Full TCP/IP stack (Ethernet, ARP, IP, ICMP, UDP, TCP)
• DNS resolver
• HTTP client
• TLS 1.2 with HTTPS support

Apps

• Web browser with HTML/CSS rendering
• Terminal emulator with readline-style shell
• Text editor (vim clone) with syntax highlighting
• File manager with drag-and-drop
• Music player (MP3/WAV)
• Calculator, system monitor
• VibeCode IDE
• DOOM

Development

• TCC (Tiny C Compiler) - compile C programs directly on VibeOS
• MicroPython interpreter with full kernel API bindings
• 60+ userspace programs (coreutils, games, GUI apps)

Hardware

• Runs on Raspberry Pi Zero 2W
• USB keyboard and mouse via DWC2 driver
• SD card via EMMC driver
• 1920x1080 framebuffer

Screenshots

Quick Start

Requirements

• macOS or Linux
• aarch64-elf-gcc cross-compiler
• QEMU with qemu-system-aarch64

On macOS:

brew install aarch64-elf-gcc qemu

Build and Run

# Create disk image (first time only)
make disk

# Build and run
make run

This builds the kernel and all userspace programs, syncs them to the disk image, and launches QEMU with a GUI window.

Controls

• Mouse and keyboard work as expected
• Click dock icons to launch apps
• Ctrl+S to save in editors
• Type help in terminal for shell commands

Boot Configuration

Edit /etc/boot.cfg to customize boot behavior:

# VibeOS Boot Configuration
splash=on       # on/off - show boot splash animation
boot=desktop    # desktop/vibesh - boot target

Running on Raspberry Pi Zero 2W

Build for Pi

make TARGET=pi

Install to SD Card

# Find your SD card
diskutil list  # macOS
lsblk          # Linux

# Install (example: /dev/disk4)
make install DISK=/dev/disk4

This partitions the SD card, installs the bootloader and kernel, and copies all programs.

What Works on Pi

• Full desktop GUI at 1920x1080
• USB keyboard and mouse (including through hubs)
• SD card filesystem
• All userspace programs
• DOOM at 2x scale

What's Missing on Pi

• Networking (no driver for Pi's WiFi/Ethernet)
• Audio (no driver for Pi's audio)

Troubleshooting USB on Pi

If you boot on Pi Zero, have a USB hub with a keyboard and mouse plugged in, and your keyboard is not working, try to change the order they are plugged in to the hub. Keyboard should be plugged in before the mouse (at a lower port number) This is (i am not sure) because some mouses show up as a mouse and a few keyboards, so vibeos does not find a real keyboard.

Also, USB on Pi does not support hotplug. If you unplug or forget to plug in either one of the peripherals, you have to reboot.

If USB still does not work after verifying both of these, reboot until it does and it will probably work in 5th try tops.

Documentation

• USAGE.md - How to use VibeOS (shell commands, apps, keyboard shortcuts)
• PROGRAMMING.md - Writing programs for VibeOS (TCC, Python, cross-compile, vibe.h API)
• CLAUDE.md - Technical reference, gotchas, architecture decisions

Third-Party Code

VibeOS includes the following third-party libraries:

| Library | License | Used For | |---------|---------|----------| | doomgeneric | GPL-2.0 | DOOM port | | MicroPython | MIT | Python interpreter | | TCC | LGPL-2.1 | C compiler | | TLSe | BSD-2-Clause | TLS 1.2 implementation | | minimp3 | CC0 | MP3 decoding | | stb_truetype | MIT | TrueType font rendering | | stb_image | MIT | Image loading |

Contributing

Issues and PRs will be reviewed. No guarantees.

License

MIT. See LICENSE.

DOOM port is GPL-2.0. See user/bin/doom/LICENSE.

Session Logs

The development of VibeOS is documented across 64 sessions:

• Session Log 1 - Sessions 1-10: Bootloader, kernel, shell, VFS, FAT32, GUI foundations
• Session Log 2 - Sessions 11-20: Desktop apps, PIE relocations, terminal, interrupts
• Session Log 3 - Sessions 21-32: Power management, LFN, audio, networking, browser
• Session Log 4 - Sessions 33-49: TLS/HTTPS, Pi port, USB driver, optimizations
• Session Log 5 - Sessions 50-55: USB fixes, DMA, performance tuning
• Session Log 6 - Sessions 56-64: MicroPython, TCC, DOOM, VibeCode, polish