HomeOS

The open-source macOS — built entirely in Home, one language from kernel to desktop.

Honest Baseline

HomeOS is in early bring-up. Read this before anything else in the repository.

A Home-compiled kernel boots in QEMU and prints on the serial console. That is the entirety of what executes today. The tree also holds a large body of Home source — a TCP stack, a compositor, a CFS scheduler, 80+ coreutils — all of which has been written and parses, and none of which has ever run.

Gate	What it proves	Status
`parse-rate`	every kernel `.home` file parses	410/410 (100%)
`stub-register`	the stub register matches the source	green
`boot-qemu-x86_64`	Home-compiled code boots and prints on serial	green
`mvk-compiles`	how much of the kernel reaches codegen	35/35 ✅
`typecheck`	how much of the kernel has zero type errors	35/35 ✅
`boot-to-shell`	an interactive shell over serial	not started
everything after	see the phase map	not started

Try it yourself:

./scripts/build.sh mvk    # compile a .home kernel, link it, emit the image
./scripts/boot-test.sh    # boot it in QEMU, assert the string on serial

IMPLEMENTATION_STATUS.md is the full picture, and it is generated by measurement rather than written by hand — it re-runs the parser, rebuilds the kernel, and boots it, so it cannot drift.

Strategy: kernel-first purist (MASTER_PLAN) — no Linux-hosted stopgap; QEMU → x86-64 → Raspberry Pi 5 hardware waves. The honest cost of that choice is that desktop parity arrives at Phase 5, not next quarter.

Project Structure

home-os/
├── kernel/
│   ├── src/
│   │   ├── mvk_poc.home      # the kernel that currently boots
│   │   ├── main.home         # x86-64 kernel entry (lean unified entry)
│   │   ├── boot.s            # multiboot headers + long-mode transition
│   │   └── *.home            # Kernel modules
│   ├── linker.ld             # x86-64 linker script
│   └── linker-rpi5.ld        # ARM64 linker script
├── apps/                     # Userspace: shell, coreutils, init
├── libs/libc/                # libc (12 modules)
├── installer/                # OS installer
├── scripts/
│   ├── build.sh              # Canonical build dispatcher (--help)
│   ├── boot-test.sh          # boot-qemu-x86_64 gate
│   ├── parse-rate.sh         # parse-rate gate
│   └── stub-check.sh         # stub-register gate
├── static-checks/            # Static/grep checks (not executed tests)
└── docs/
    └── MASTER_PLAN.md        # Canonical roadmap

Building from Source

Prerequisites

Home Compiler (required)

git clone https://github.com/home-lang/home   # or your checkout
cd home && zig build

QEMU, for the boot gate. This repo declares it in pantry.jsonc:
```
pantry install
```
For Raspberry Pi 5: blocked on the Home arm64 backend (milestone A6).

Build Commands

./scripts/build.sh mvk             # the Minimum Viable Kernel (also the default)
./scripts/boot-test.sh             # boot it in QEMU, assert proof-of-life
./scripts/parse-rate.sh --strict   # the parse-rate gate
./scripts/stub-check.sh            # the stub-register gate
./scripts/build.sh --help          # every subcommand

Build failures are loud by design. A missing compiler, a missing source file, or a failed compile exits nonzero — there are no stub fallbacks that let a build report success without producing a kernel.

Roadmap

The canonical plan is docs/MASTER_PLAN.md. Phases:

Phase 0 (now) — Truth & Toolchain: parse 100%, honest builds/docs, MVK boots in QEMU under CI
Phase 1 — Kernel bring-up to interactive serial shell
Phase 2 — Storage + networking + console subsystems
Phase 3 — Userspace & POSIX solidity
Phase 4 — Craft GUI foundation
Phase 5 — Desktop experience parity (v1.0)
Phase 6+ — Beyond Omarchy; hardware waves

License

MIT

Contributing

See CONTRIBUTING.md.