Rice Docs — macOS Developer Environment

Documentation as a First-Class Artifact

The Hyprland rice on Arch Linux was the first time I assembled an entire desktop environment from individual components and wired them together with explicit configuration. When I moved back to macOS for the Prachyam Sangam work, I brought the same instinct: don't accept the default environment, build the one that gets out of your way.

The macOS version — AeroSpace tiling with a custom OmniWM layer, X-Type on Karabiner-Elements, SketchyBar scripted status bar, Ghostty terminal, tmux session management, Atuin shell history, Neovim — is more sophisticated than the Hyprland setup in every dimension. More layers, more integration, more edge cases. The documentation is 5,000 lines of Markdown written to be LLM-editable: sections include explicit instructions like "tell Claude to apply this change to the Karabiner JSON." The documentation is the system. If the documentation is right, the environment can be fully reconstructed or modified without having to figure out the architecture from scratch.

The Karabiner 4-Layer Architecture

The X-Type layout on macOS lives in Karabiner-Elements across three JSON files — xtype-left-symbols.json (1 rule, 17 manipulators), xtype-right-symbols.json (2 rules, 19 manipulators), and xtype-wm-layer.json (1 rule, 43 manipulators) — implementing tap-hold dual-purpose symbol and window-manager layers with a 300ms disambiguation window. That's 79 manipulators in total; the 6 active rules in karabiner.json are what's actually loaded into the profile (a fourth file, mouse-buttons.json, handles mouse remapping). The often-quoted "43 manipulators" figure is just the WM layer — the densest single file, not the whole picture.

The 4-layer architecture: base layer (X-Type letter positions), left-symbol layer (programming symbols on the left hand, triggered by a right-hand hold), right-symbol layer (the inverse), and a WM layer for AeroSpace/OmniWM window-management commands. Every programming symbol is reachable from home row. Every window action — move focus, move window, switch workspace, resize split — is a keybind on the WM layer driving AeroSpace, with OmniWM filling the gaps AeroSpace leaves. The mouse is optional for everything except the browser.

Karabiner intercepts at the IOKit layer, so the remapping happens before any application sees the key event. This means X-Type and the symbol layers work correctly in every application, including games and full-screen environments that override normal keyboard handling.

SketchyBar and the Event Bus

SketchyBar subscribes to AeroSpace workspace events and OmniWM IPC events, Neovim mode changes via a Lua autocmd that writes to a named pipe, and a CoreAudio CATapDescription HAL tap for an FFT visualiser item. A Swift helper implements the CoreAudio tap because Bash cannot talk to the HAL directly.

The effect: the status bar is live. Workspace switches appear immediately because the WM emits events directly to SketchyBar rather than SketchyBar polling. The Neovim mode indicator (Normal / Insert / Visual) switches without latency because the autocmd fires on every mode change and writes to the pipe within the same event loop cycle. The FFT visualiser responds to audio output in real time.

The environment runs 213 WPM. It has been the daily driver since March 2026.