Headroom

Your AI coding quotas and ship status — on the desk, in the menu bar, and on your phone.

When you're deep in Claude, Codex, or Cursor, you shouldn't have to dig through billing pages, gh, and Vercel to answer: Am I about to hit a limit? Did CI go red? Is prod healthy?

Headroom is a local-first desk gadget + macOS menu bar (+ optional iPhone) that consolidates that into one glance:

One Python host on your Mac reads local auth + CLIs and serves a single JSON feed. No cloud account for Headroom itself — your tokens stay on the machine.

  ~/.claude JSONL + OAuth          Mac (Python, stdlib)              Clients
  ~/.codex + Cursor state.vscdb    ┌──────────────────┐             ┌──────────────┐
  ~/.gemini + Windsurf profile    ─▶│ headroom_        │◀── HTTP ────│ Menu bar app │
  Copilot / JetBrains / Zed       │ server.py :8737  │◀── HTTP ────│ iPhone app   │
  Vercel / git / gh / SB / Plaus. │ + usb_bridge     │◀── HTTP/USB─│ ESP32 /usage │
  ~/.headroom/{config,sources}    └──────────────────┘             └──────────────┘

Hardware is optional. The menu bar alone is useful. The Waveshare ESP32-S3-Touch-AMOLED-1.8 (368×448) is the always-on desk glance — same feed, tap a slot for detail, tap the header to switch Burndown / Activity, and long-press to force-refresh. Its three rings are the same three the menu bar draws — the host picks them and the board draws what it is sent, so a newer provider, an extra account, your pinned order and your color overrides all reach the desk. The default lower half combines those providers into the same seven-day burndown the Mac, phone and medium widget show.

Why it exists

• Quota anxiety is real. Session / weekly windows, pace, and spend are scattered across products. Headroom puts hottest pool % + pace on one ring (and a menu-bar tick per provider in focus).
• Ship status is ambient. Failed Actions, Vercel builds, Supabase alerts and RLS holes, and listening local servers surface as an attention pip — not another tab.
• Local-first. The host talks to credentials and CLIs you already have. The board can fall back to USB CDC when hotel Wi‑Fi blocks mDNS.

Requirements

No Headroom cloud account. Tokens stay on your Mac.

Quick start

Option A — macOS from a GitHub Release

1. Download Headroom-macOS.zip from Releases. If no release exists yet, use Option B.
2. Unzip and open Headroom.app (notarized builds open normally; ad-hoc builds need right-click → Open once).
3. Click the menu bar meters → the Welcome sheet appears.
4. On a Release .app, the host starts automatically and installs a LaunchAgent so it stays up at login (and after you quit the menu bar). Use Start host & keep at login only if that didn’t happen.
5. Confirm which providers were detected → Continue.

Updating. scripts/update-app.sh replaces an installed Headroom.app with the current Release. It refuses anything that is not notarized and signed by the project's team, and it brackets the swap with launchctl bootout / bootstrap — the host runs from inside the bundle under a KeepAlive agent, so replacing the app under a live agent leaves launchd holding the old code.

./scripts/update-app.sh --check

./scripts/update-app.sh

Option B — macOS from source

git clone https://github.com/michellzappa/headroom.git
cd headroom
./scripts/build-app.sh          # embeds host → dist/Headroom.app
open dist/Headroom.app

Or the two-piece flow (host from clone, debug app):

./scripts/install-host.sh
./scripts/gen-project.sh          # embeds host + writes Headroom.xcodeproj
cd macos
xcodebuild -project Headroom.xcodeproj -scheme Headroom \
  -configuration Debug -derivedDataPath .build build
open .build/Build/Products/Debug/Headroom.app

Foreground try (no login item): ./scripts/install-host.sh --foreground
Uninstall LaunchAgent: ./scripts/uninstall-host.sh (--purge wipes ~/.headroom)

Opening the project in Xcode

A fresh clone contains no .xcodeproj, and that is expected: macos/project.yml is the source of truth and XcodeGen writes the project from it, so the generated macos/Headroom.xcodeproj is gitignored. On a new Mac, write it first:

brew install xcodegen

./scripts/gen-project.sh

open macos/Headroom.xcodeproj

Go through the script rather than calling xcodegen generate yourself. project.yml lists macos/host as a source directory, and that folder is a gitignored copy of the host made by sync-embedded-host.sh — on a fresh clone bare xcodegen stops at a missing source directory, which does not point at the real cause. The script syncs first.

Anything touching the watch app needs the beta toolchain, and that includes the iPhone app, which embeds it. Stable Xcode reports a watchOS SDK and still resolves every watch destination to "watchOS 26.5 is not installed":

open -a /Applications/Xcode-beta.app macos/Headroom.xcodeproj

Regenerate after any pull that adds files. A new file under Shared/ will not be in the project you generated last week, and the failure reads as a missing type rather than a stale project. Quit Xcode before regenerating — replacing the project underneath a running Xcode is what produces "The project “Headroom” is not a valid property list" on a file that is perfectly valid.

Option C — iPhone

1. Install via the TestFlight link when published, or build from source (docs/ios-companion.md).
2. Keep the Mac host running (Option A/B).
3. On the phone: allow Local Network, pick your Mac under Nearby Macs.
4. On the Mac: Settings → iPhone pairing → Copy mobile token, paste once on the phone → Connect.

The phone uses the mobile token. The ESP32 uses the separate host token. See Tokens below.

First run (Mac)

• ~/.headroom/sources.json is seeded from local detection — only providers that look signed-in are enabled. If none are found, every quota source stays on so the UI can show sign-in errors.
• The Welcome sheet lets you confirm toggles before the overview appears.
• Edit ~/.headroom/config.json later for git authors / GitHub org / timezone.

curl -s localhost:8737/health | python3 -m json.tool
curl -s localhost:8737/setup  | python3 -m json.tool

Two kinds of source

Onboarding and Settings keep them apart, because they answer different questions and take different setup:

• AI coding tools — Claude, Codex, Cursor, Copilot, Gemini, Windsurf, JetBrains AI, Zed. How much plan is left. Read from the sign-in already on the Mac, so there is nothing to paste.
• Dev tools — Vercel, Git, GitHub Actions, Supabase, Plausible, local servers. What your projects are doing. Some want a key, pasted once in Mac Settings (Keychain — never sent to the phone or written into /usage).

Which repos Actions watches is editable in Settings → GitHub Actions: owner filters, an always-watch list, and the discovery cap. Settings also shows the repos those settings resolve to on this machine.

Both lists toggle under Settings, each in its own section — the same flags drive the menu bar, overview rings, iPhone, and the board.

More than one account per tool. Personal Claude and work Claude, two ChatGPT logins, a second Cursor profile — each is a separate plan with its own quota, and Headroom used to show only whichever one the CLI wrote last. Add the others in Settings → Extra accounts: pick the provider, name it, and point it at the credential location that login already uses.