by michellzappa
Local-first AI coding quotas and ship status, on your menu bar, iPhone, Watch and an ESP32 desk display.
# Add to your Claude Code skills
git clone https://github.com/michellzappa/headroomLast scanned: 7/31/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-07-31T06:43:39.375Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}headroom is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by michellzappa. Local-first AI coding quotas and ship status, on your menu bar, iPhone, Watch and an ESP32 desk display. It has 262 GitHub stars.
Yes. headroom passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/michellzappa/headroom" and add it to your Claude Code skills directory (see the Installation section above).
headroom is primarily written in Python. It is open-source under michellzappa on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh headroom against similar tools.
No comments yet. Be the first to share your thoughts!
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.)
| 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.
Headroom.app → menu bar meters → Welcome.Build from source, Xcode, and signing: macos/README.md.
TestFlight when published, or build from source — docs/ios-companion.md. Use the mobile token from Mac Settings → iPhone pairing (not the host token).
Waveshare ESP32-S3-Touch-AMOLED-1.8 only. Flash, config, brightness: docs/esp32.md.
| 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
| 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 |
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.
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.