The central nervous system for a household of engineering projects: a home server, a retro-industrial control interface, and a shared-memory protocol that lets a dozen independent projects report into one place.
MakerOS is the central nervous system for a household of engineering projects: a home server, a retro-industrial control interface, and a shared-memory protocol that lets a dozen independent projects (3D printing, ESP32 displays, a vinyl jukebox, smart lights, short-term rental operations, and AI agents themselves) report into one place without being reorganized to do it. It exists because the real problem of a busy workshop isn't building things. It's remembering the state of everything you've built.
Twelve active projects, each in its own repo, each with its own status, blockers, and half-finished branches. Every work session started with twenty minutes of re-orientation, and every AI coding assistant started from zero, burning tokens re-reading codebases just to answer "where was I?" Meanwhile the projects themselves were duplicating infrastructure: two separate devices independently polling the same weather and tide APIs, because nothing shared. The opportunity was to treat memory as the product. One place where humans and AI agents alike could orient in seconds, cheaply, offline.
It began as a static dashboard: a registry of projects in plain JSON, rendered in a browser. The first important decision was a refusal. Projects would be referenced, never reorganized. No mono-repo, no migrations. Each project publishes a status contract under 2 KB at its own root; MakerOS pulls snapshots and never writes back.
The second turning point was admitting the dashboard looked like every AI-startup product: indigo gradients, glassy cards, no soul. The fix was a written constitution rather than a restyle. A design spec called PHOSPHOR defines a believable retro-industrial instrument: phosphor blue for data, amber for attention, red for faults only, ten design laws, and a permanent text-only terminal mode (TTY-0) as the system's BIOS. Identity was committed to the repo before any pixels changed.
The third was discovering that one of TTY-0's constraints had quietly solved a feature on the wishlist. The constraint says every screen must be expressible as plain text. The wishlist item was physical printing. A receipt printer is a terminal, so the text pages became the print format with no rendering pipeline required.
That foundation was then stress-tested by building HostOS, a short-term-rental operations system (Airbnb/VRBO calendar polling, turnover boards, door codes, kitchen-ticket printing of new bookings), end to end in a day. That was the proof the rails were real. The current chapter is the hardware migration: everything moving onto an Arduino UNO Q as an always-on home appliance, guided by a proof-of-concept cyberdeck build based on SparkLab's UNO Q LLM Cyberdeck design (YouTube), with a local LLM, an HTTP bridge, and a GIGA display as the physical face of the system.
The architecture rests on a two-plane split. The knowledge plane is a static git repo: plain JSON registry and contracts, a zero-build HTML/CSS/JS dashboard, no server. It works offline and survives anything. The live-data plane is a set of small services destined for the UNO Q: an API bridge (promoted from an existing Sonos/Discogs/weather bridge rather than rebuilt), the HostOS poller, and a print service speaking raw ESC/POS over TCP 9100. The planes interconnect over HTTP but never merge; no server ever lives inside the knowledge repo.
Deliberate tradeoffs: plain JSON over a database, since git is the sync, diff, and backup mechanism. Zero npm dependencies in the pollers, because a vendored 60-line iCal parser beats supply-chain churn over a ten-year horizon. One repo per deployable unit, all siblings, and no more repos than that. Agent orientation follows a memory hierarchy, from L0 (a 1 KB entry point) through L1 (JSON state) and L2 (docs/decisions) down to L3 (source code, only if required), with a hard rule that any status question is answerable at L2 or above. Every significant decision is an ADR in the repo. Nine so far.
The hardest problems were design problems wearing technical clothes. How do you let a browser page "write" data when the architecture forbids a backend? Edit in memory, mark it UNSAVED in amber, and export the JSON for a git commit; the workflow honors both the user and the architecture. How do you print from a static site? You don't. You make text the universal format and let the browser print today while the appliance prints unattended tomorrow. The subtlest bug was an integrity one: sample fixture data from a test run synced onto the dashboard claiming a real rental turnover was happening. The fix went into the generator, so a sample run is now structurally incapable of publishing itself as live state. On a system that touches family income, honesty is a feature with an implementation.
Write the decision down before writing the code; a spec in the repo turns every subsequent build into cheap, delegable work. Constraints compound. The text-parity law paid for itself three times over (safe mode, printing, embedded display protocol) in ways nobody planned. And separation only works if discovery is banned: the moment an agent finds projects by scanning folders instead of reading the registry, the simplicity is gone. Starting over, the only major change would be adopting the contract protocol on day one. The projects that predate it were the hardest to integrate.
Working today: the full dashboard (THE FLOOR), TTY-0 terminal mode with read/write inventory and browser printing, contract sync across twelve projects, and HostOS verified end to end on sample data. Experimental or awaiting activation: HostOS live polling (needs real calendar URLs), smart-lock automation (hardware undecided), receipt printing (printer not yet purchased). On the roadmap: the UNO Q migration (five phases, playbook written), bridge promotion to kill the last API duplication, and deleting the legacy dashboard once its launcher is ported.
One to three years out: the UNO Q runs the house. The dashboard is served locally, contracts sync on a timer, a local LLM answers "what's the state of my world?" against the same JSON agents read today, and the GIGA-display cyberdeck sits on the bench as the physical terminal. HostOS grows guest names and revenue via email parsing (never scraping), and possibly a direct-booking channel that reuses the reservation calendar. The realistic ceiling is deliberate: a household-scale system, fully local, no cloud dependencies, cheap enough that there is never a reason to turn it off.
THE FLOOR dashboard full-screen (dark, phosphor, annunciators lit); TTY-0 terminal mode beside it, same data, two eras; a printed HOST-01 turnover board next to the receipt printer; the UNO Q + GIGA cyberdeck hardware photo; the two-plane architecture diagram; a before/after of the indigo SaaS dashboard versus PHOSPHOR; a terminal screen-capture of the sample HostOS pipeline run.
This project is also an experiment in how to work with AI. The division of labor was explicit: a frontier model (Claude Fable 5) wrote specifications, architecture decisions, and reviews; cheaper models (Claude Sonnet, Codex) executed builds against those specs, reading them from the repo rather than from conversation. The human made every call that mattered: the aesthetic direction, the product priorities (guest relations over accounting), the hardware choices, what gets published, and what gets deleted. The AI's most valuable output was written-down judgment that made the code cheap, not the code itself. Notably, the repo is designed for AI collaborators: agents are onboarded by the same documents humans read, and the case study you're reading was drafted by the AI that did the work, then reviewed by the human who owns it.
HTML/CSS/JavaScript (zero-build, zero-framework) · Node.js (zero-dep services) · PowerShell · plain-JSON contracts over git · Arduino UNO Q (Linux + Zephyr MCU) · Arduino GIGA R1 WiFi + Display Shield · ESP32-S3 (companion displays) · local LLM (qwen2.5, GGUF) · RFC 5545 iCal · ESC/POS raw-TCP printing · systemd (deploy target) · Windows Task Scheduler (interim) · Open-Meteo / NOAA CO-OPS / NDBC / Discogs / Sonos / WiZ APIs · Cloudflare Pages (portfolio) · Claude (Fable/Sonnet) + Codex as engineering collaborators · IBM Plex Mono, because the machine should look like it means it.