Credentials. Headroom reads the auth and CLIs you already have on the Mac, so only install it on machines where you trust local access to those tool sessions.
Who it is forA developer working in Claude, Codex, or Cursor on a Mac who keeps running into surprise usage limits and forgets to check whether CI or prod is healthy.
The problemQuota limits, failed Actions runs, and deploy problems are spread across billing pages, gh, and Vercel, so you break focus to check each one.
The outcomeThin quota tanks and an attention pip sit in the menu bar, and the popover shows Usage, Attention, and Activity from local data only.
What you need first
- macOS 14 or later for the menu bar app
- Python 3.9 or later (the bundled host is stdlib only, using /usr/bin/python3)
- At least one AI coding tool already signed in locally
- Optional: iPhone or iPad on iOS 17 or later, on the same LAN or Tailscale as the Mac
- Optional: PlatformIO and a Waveshare ESP32-S3-Touch-AMOLED-1.8 for the desk board
Steps
- Download Headroom-macOS.zip from the Releases page on the Headroom GitHub repo and open Headroom.app.
- Open the menu bar meters and follow the Welcome screen.
- Confirm the detected providers, then select Continue. On a Release build the host starts automatically and stays up at login.
- Run
curl -s localhost:8737/health | python3 -m json.toolin Terminal to confirm the host is responding. - Open the popover and check the Attention tab for failed Actions runs, deploys, or monitors.
Prompt for your agent
Using the michellzappa/headroom repo, help me set up the Headroom macOS menu bar app for my <tool name> account. Expected output: the menu bar shows quota tanks for the enabled providers, and the local health check returns JSON. Verify by running `curl -s localhost:8737/health | python3 -m json.tool` and confirming it responds.
Caveat. The README says Headroom reads local state that other tools leave on your Mac and only works for providers already signed in on that machine.
Use this in your AI agent
Ask your agent
Using the Deduped MCP, get the setup steps for michellzappa/headroom and "Check AI coding quota and ship status from the menu bar"
Add Deduped to Claude Code once
claude mcp add --transport http deduped https://dedupedai.com/mcp
Every Monday: the 5 hottest repos and exactly how to use them. Free, one email a week, unsubscribe anytime.
Get them freeShare: X LinkedIn Hacker News Email Copy link
Third-party repos we don't own. AI-written use cases can be wrong. Disclaimer