Headroom
Your AI coding quotas and ship status — in the menu bar, on your phone, and optionally on the desk.
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 macOS menu bar app (+ optional iPhone / Watch). One Python host on your Mac reads the auth and CLIs you already have and serves a single JSON feed. No Headroom cloud account — tokens stay on the machine.
| Surface | What you see |
|---|---|
| Menu bar | Thin remaining-quota tanks for the first three enabled providers + amber/red attention pip |
| Popover | Usage (rings, daily burn, spend), Attention, Activity (Recent feed + service panels) |
| Notification Center | Same widget as the iPhone: rings small, combined burndown medium |
| iPhone / iPad | Same three tabs — Usage, Attention, Activity — plus Settings, notifications, widgets |
| Apple Watch | Two complications: rings, or the week's burndown |
| ESP32 desk board (optional) | Same three rings + burndown on a Waveshare AMOLED — docs/esp32.md |
|
|
|
|
~/.claude / ~/.codex / Cursor / … Mac (Python, stdlib) Clients
Vercel · git · gh · SB · … ──▶│ headroom_server.py :8737 │◀── menu bar
~/.headroom/{config,sources} │ + usb_bridge │◀── iPhone
└──────────────────────────┘◀── ESP32 (opt.)
Why it exists
- Quota anxiety — session / weekly windows, pace, and spend on one ring (and a menu-bar tick per provider in focus).
- Ship status ambient — failed Actions, deploys, and monitors as an Attention pip and queue, not another tab.
- Agents away from the desk — approve, deny, or reply to Claude / Codex requests from Attention on iPhone (Headroom answers; it does not start work).
- Local-first — credentials and CLIs you already have; optional board can fall back to USB when hotel Wi‑Fi blocks mDNS.
Requirements
| Need | Notes |
|---|---|
| macOS 14+ | Menu bar app |
| Python 3.9+ | Bundled host is stdlib only (system /usr/bin/python3) |
| At least one AI coding tool | Already signed in locally |
| Optional: iPhone / iPad (iOS 17+) | Same LAN or Tailscale as the Mac |
| Optional: PlatformIO | Only to flash the desk board |
No Headroom cloud account.
Quick start
1. Mac app (Release)
- Download Headroom-macOS.zip from Releases.
- Open
Headroom.app→ menu bar meters → Welcome. - On a Release build the host starts automatically and stays up at login.
- Confirm detected providers → Continue.
Build from source, Xcode, and signing: macos/README.md.
2. iPhone (optional)
TestFlight when published, or build from source — docs/ios-companion.md. Use the mobile token from Mac Settings → iPhone pairing (not the host token).
3. Desk board (optional)
Waveshare ESP32-S3-Touch-AMOLED-1.8 only. Flash, config, brightness: docs/esp32.md.
After install
| Topic | Doc |
|---|---|
| Providers, accounts, Integrations, colours, focus, tokens | docs/setup.md |
~/.headroom keys + HTTP endpoints | docs/host.md |
| Something’s broken | docs/troubleshooting.md |
curl -s localhost:8737/health | python3 -m json.tool
Docs
| Doc | For |
|---|---|
| macos/README.md | Menu bar — build, Xcode, signing |
| docs/setup.md | First run, Providers, Integrations, tokens |
| docs/host.md | Config files + API surface |
| docs/ios-companion.md | iPhone pairing + widgets |
| docs/watch.md | Apple Watch complications |
| docs/esp32.md | Optional Waveshare desk display |
| docs/troubleshooting.md | Symptom → fix |
| docs/glossary.md | Shared chrome names |
| docs/rings.md | Ring / pace semantics |
| docs/contract.md | Changing /usage safely |
| docs/trust.md | Who may call which routes |
| docs/product.md | Standing product decisions |
| docs/metering.md | Meter kinds |
| docs/attention.md | Attention rollup policy |
| docs/agent-attention.md | Coding-agent gateway |
| docs/multi-mac.md | CloudKit settings sync |
| docs/telemetry.md | Anonymous product diagnostics |
| docs/updater.md | In-app update feed |
| docs/releasing.md | Notarize, TestFlight, cut-release |
| docs/appstore.md | App Store listing + screenshots |
| docs/privacy.md | Privacy policy |
| docs/install-links.md | Release + TestFlight URLs |
| docs/backlog.md | What’s queued |
| CHANGELOG.md | Per-version notes |
| CONTRIBUTING.md | Build, test, PR expectations |
| SECURITY.md | Threat model + reporting |
Contributing
Build and test commands: CONTRIBUTING.md. The host is
stdlib-only Python; every surface has to keep agreeing about /usage.
Security reports go through SECURITY.md.
License
MIT — see LICENSE.
Headroom reads local state that other tools leave on your Mac. It is not affiliated with, endorsed by, or supported by Anthropic, OpenAI, Anysphere, GitHub, Google, JetBrains, Zed, Codeium, Vercel, Supabase, Plausible, PostHog, Sentry, Datadog, or Axiom. Those names appear here to say what is being measured.