Headroom App

Headroom is an open-source, local-first macOS menu bar app built by Michell Zappa that surfaces AI coding quota usage and CI/deployment ship status without requiring a cloud account. It reads credentials and CLIs already present on your Mac, serves a single JSON feed over localhost, and pushes that data to optional companion surfaces including iPhone, Apple Watch, and an ESP32 desk display. The project is MIT-licensed and available on GitHub, with 212 stars as of its latest release.

What It Is

Headroom sits in the category of developer ambient-monitoring tools — specifically targeting the problem of "quota anxiety" when working heavily with AI coding assistants like Claude Code, OpenAI Codex, and Cursor. Instead of navigating billing dashboards mid-flow, developers get a persistent, glanceable view of remaining session/weekly quotas, daily burn rate, spend, and CI/deployment health across all their active tools. The architecture is intentionally local-first: a stdlib-only Python host (headroom_server.py) runs on port 8737, reads local auth state left by other tools, and clients connect to it directly — no Headroom cloud account, no token upload.

Surfaces and What Each Shows

Headroom spans multiple display surfaces, each scoped to what makes sense at that glance distance:

• Menu bar — thin remaining-quota "tanks" for up to three enabled providers plus an amber/red attention pip for failures
• Popover — overview rings, daily burn, spend, and an Activity/Services panel
• Notification Center widget — rings and combined burndown, matching the iPhone widget layout
• iPhone / iPad (iOS 17+) — full quotas, burndown chart, activity feed, services status, controls, notifications, and home-screen widgets
• Apple Watch — two complications: quota rings or the week's burndown
• ESP32 desk board (optional) — Waveshare ESP32-S3-Touch-AMOLED-1.8 showing the same three rings and burndown; can fall back to USB when mDNS is blocked

Architecture and Local-First Design

The Python host is stdlib-only, meaning it runs on the system /usr/bin/python3 with no pip dependencies. It reads ~/.claude, ~/.codex, Cursor config, and other local auth files, then exposes HTTP endpoints under localhost:8737. Clients — the macOS SwiftUI app, iPhone companion, and ESP32 firmware — all consume the same /usage JSON contract. CloudKit is used for settings sync across multiple Macs. The trust model is documented in docs/trust.md, and the security threat model is in SECURITY.md. Credentials never leave the machine unless the user explicitly enables Tailscale-based remote access for the iPhone companion.

Supported Providers and Integrations

Headroom measures quota and status across AI coding tools and deployment/observability services it finds already configured on the Mac:

• AI coding tools: Claude (Anthropic), OpenAI Codex, Cursor, and others detectable via local auth
• Ship status sources: GitHub Actions, Vercel, Supabase, Plausible, PostHog, local dev servers
• The README explicitly notes Headroom is not affiliated with or endorsed by any of these vendors — their names appear only to describe what is being measured

Update: v1.7.0

The latest release is v1.7.0, published on 2026-08-03, with the repository last pushed the same day. The project was created on 2026-07-24, making it a very recently launched tool with active development momentum. The backlog (docs/backlog.md) and changelog (CHANGELOG.md) are maintained in-repo. The App Store listing and TestFlight distribution paths are documented, indicating a planned public iOS release beyond the current source-build path.