# Headroom App

> Local-first macOS menu bar app that shows AI coding quotas and ship status across Claude, Codex, Cursor, and more — with optional iPhone, Apple Watch, and ESP32 desk display support.

Headroom is an open-source, local-first macOS menu bar app built by Michell Zappa that surfaces AI coding quota usage and CI/deployment ship status without requiring a cloud account. It reads credentials and CLIs already present on your Mac, serves a single JSON feed over localhost, and pushes that data to optional companion surfaces including iPhone, Apple Watch, and an ESP32 desk display. The project is MIT-licensed and available on GitHub, with 212 stars as of its latest release.

## What It Is

Headroom sits in the category of developer ambient-monitoring tools — specifically targeting the problem of "quota anxiety" when working heavily with AI coding assistants like Claude Code, OpenAI Codex, and Cursor. Instead of navigating billing dashboards mid-flow, developers get a persistent, glanceable view of remaining session/weekly quotas, daily burn rate, spend, and CI/deployment health across all their active tools. The architecture is intentionally local-first: a stdlib-only Python host (`headroom_server.py`) runs on port 8737, reads local auth state left by other tools, and clients connect to it directly — no Headroom cloud account, no token upload.

## Surfaces and What Each Shows

Headroom spans multiple display surfaces, each scoped to what makes sense at that glance distance:

- **Menu bar** — thin remaining-quota "tanks" for up to three enabled providers plus an amber/red attention pip for failures
- **Popover** — overview rings, daily burn, spend, and an Activity/Services panel
- **Notification Center widget** — rings and combined burndown, matching the iPhone widget layout
- **iPhone / iPad (iOS 17+)** — full quotas, burndown chart, activity feed, services status, controls, notifications, and home-screen widgets
- **Apple Watch** — two complications: quota rings or the week's burndown
- **ESP32 desk board (optional)** — Waveshare ESP32-S3-Touch-AMOLED-1.8 showing the same three rings and burndown; can fall back to USB when mDNS is blocked

## Architecture and Local-First Design

The Python host is stdlib-only, meaning it runs on the system `/usr/bin/python3` with no pip dependencies. It reads `~/.claude`, `~/.codex`, Cursor config, and other local auth files, then exposes HTTP endpoints under `localhost:8737`. Clients — the macOS SwiftUI app, iPhone companion, and ESP32 firmware — all consume the same `/usage` JSON contract. CloudKit is used for settings sync across multiple Macs. The trust model is documented in `docs/trust.md`, and the security threat model is in `SECURITY.md`. Credentials never leave the machine unless the user explicitly enables Tailscale-based remote access for the iPhone companion.

## Supported Providers and Integrations

Headroom measures quota and status across AI coding tools and deployment/observability services it finds already configured on the Mac:

- **AI coding tools**: Claude (Anthropic), OpenAI Codex, Cursor, and others detectable via local auth
- **Ship status sources**: GitHub Actions, Vercel, Supabase, Plausible, PostHog, local dev servers
- The README explicitly notes Headroom is not affiliated with or endorsed by any of these vendors — their names appear only to describe what is being measured

## Update: v1.7.0

The latest release is **v1.7.0**, published on 2026-08-03, with the repository last pushed the same day. The project was created on 2026-07-24, making it a very recently launched tool with active development momentum. The backlog (`docs/backlog.md`) and changelog (`CHANGELOG.md`) are maintained in-repo. The App Store listing and TestFlight distribution paths are documented, indicating a planned public iOS release beyond the current source-build path.

## Features
- macOS menu bar quota tanks for up to three AI providers
- Amber/red attention pip for CI failures and deployment issues
- Popover with overview rings, daily burn, and spend
- iPhone and iPad companion app with widgets
- Apple Watch complications (rings or weekly burndown)
- Optional ESP32 Waveshare AMOLED desk display
- Local-first: no cloud account, tokens stay on device
- stdlib-only Python host with no pip dependencies
- CloudKit settings sync across multiple Macs
- USB fallback for ESP32 when mDNS is blocked
- Supports Claude, Codex, Cursor, and other local AI tools
- GitHub Actions, Vercel, Supabase, Plausible, PostHog ship status
- Notification Center widget
- Tailscale support for remote iPhone access

## Integrations
Claude (Anthropic), OpenAI Codex, Cursor, GitHub Actions, Vercel, Supabase, Plausible, PostHog, Tailscale, CloudKit, Apple Watch, TestFlight

## Platforms
WINDOWS, MACOS, IOS, API, JETBRAINS_PLUGIN

## Pricing
Open Source

## Version
v1.7.0

## Links
- Website: https://github.com/michellzappa/headroom
- Documentation: https://github.com/michellzappa/headroom/blob/main/docs/setup.md
- Repository: https://github.com/michellzappa/headroom
- EveryDev.ai: https://www.everydev.ai/tools/headroom-app