macOS app
Headroom
A tiny macOS notch app that shows how much of your Claude, Codex and OpenCode quota is left, and when each window resets.
- Type
- macOS app
- Platform
- macOS 14+
- Status
- Daily driver
- Built with
- Swift 6 / SwiftUI / AppKit
- Lives in the MacBook notch, invisible until hovered
- Pace ticks show whether you're ahead of your quota
- Reuses existing CLI sign-ins and never stores tokens
The problem
I use several AI coding assistants, and each has its own rolling limits: a 5-hour window, a weekly window, sometimes a per-model cap. The only way to check them was to open a settings page or run a slash command in the middle of my work. I wanted to know how much headroom I had left without leaving what I was doing.
Hiding in the notch
Collapsed, Headroom is pure black and exactly the size of the MacBook's notch cutout, so it disappears into the hardware and doesn't cover any menu bar items.
Hover over the notch and it springs open. Each provider gets one bar per quota window, along with a countdown to that window's reset.
The detail I like most is the pace tick. It marks where you'd be if you spread your usage evenly across the window. If the bar is past the tick, you're burning through it fast; if it's behind, you have room to spare. Banked resets (free reset grants, rate-limit credits) show up as small tickets with their expiry, tinted warmer as the deadline gets closer.
Respecting sign-ins
Headroom doesn't ask you to log in. It reads the sign-ins the official CLIs already have: Claude Code's keychain item, Codex's auth.json, and OpenCode's local database. Tokens are read, never refreshed or stored, so the CLIs stay in charge of their own sessions. If a token has expired, the island says so and keeps the last numbers it had. Everything runs on the Mac, and it only talks to the three providers.
Built small
It's about two thousand lines of Swift, split into a UI-free core (models, provider clients, parsing, a polling store) and a thin app layer for the notch panel and hover tracking. Adding a provider means conforming to one protocol. A --demo mode and a make render target produce every state of the island as a PNG, which made it possible to tune spring animations and pixel-match the notch without real accounts. The screenshots here use that demo data.