Headroom puts Claude Code usage limits in the macOS menu bar

Headroom, released by patwalls as `v0.3.4`, is a free macOS menu bar app that surfaces Claude Code's built-in usage data — the 5-hour session limit and the 7-day weekly limit — as live color-coded percentages directly in the menu bar. The motivation, as the post describes it, is that a usage meter you have to remember to check isn't really a meter; the weekly limit reliably catches users mid-task. The menu bar displays both meters simultaneously in the format `CC 10%·65%`, turning orange or red as a limit approaches.

On first launch, Headroom installs a status-line hook that runs inside Claude Code, backing up any existing status line non-destructively and chaining to it.

On first launch, Headroom installs a status-line hook that runs inside Claude Code, backing up any existing status line non-destructively and chaining to it. Each time Claude Code processes a prompt, the hook writes rate-limit JSON to `~/.claude/headroom-usage.json`. Headroom polls that local file every 15 seconds — the entire data path is two local files with zero network calls. The post notes that most Claude usage monitors poll an external API, but Headroom does not because Claude Code already fetches and writes the data itself.

The dropdown panel adds session and weekly progress bars with countdown timers to reset, context window percentage (when Claude Code reports it), the current model name, session cost if the user's plan tracks it, and macOS notifications at 70% and 90% usage thresholds. The app is ~270 KB, universal (Apple Silicon and Intel), requires macOS 13+, is signed and notarized by Apple, and is available via Homebrew (`brew install --cask patwalls/tap/headroom`). The source is MIT-licensed, approximately 780 lines, and has no dependencies.

Key facts

1. 01Free macOS menu bar app (v0.3.4) that shows Claude Code's 5-hour session and 7-day weekly usage as live color-coded percentages
2. 02On first launch, installs a status-line hook inside Claude Code that writes rate-limit JSON to `~/.claude/headroom-usage.json`
3. 03Headroom reads that local file every 15 seconds — zero network calls, no API key, no login required
4. 04Dropdown shows session/weekly bars with reset countdowns, context window %, current model name, and session cost
5. 05Sends macOS notifications at 70% and 90% usage thresholds
6. 06~270 KB universal binary (Apple Silicon & Intel), requires macOS 13+, signed and notarized by Apple
7. 07MIT-licensed, ~780 lines of source code, no dependencies; also available via Homebrew

Topics