Wall #003 · walls.sh

Know your headroom.

A free macOS menu bar app that shows your Claude Code usage as a live % — the 5-hour session and the 7-day week — color-coded before a limit stops you mid-task.

Headroom's dropdown: Session (5h) and Week (7d) meters with color-coded bars and reset countdowns

↑ the actual app rendering its own dropdown with real data — not a mock. Yours shows your numbers.

Download Headroom — free

v0.3.4 · macOS 13+ · universal (Apple Silicon & Intel) · ~270 KB zip · signed & notarized by Apple — double-click and it runs.

Homebrew: brew install --cask patwalls/tap/headroom

No permission dialogs, no API key, no login — on first launch Headroom quietly wires itself into Claude Code's status line and the numbers are just there.

267 developers have downloaded Headroom.

Seen on Hacker News r/ClaudeAI r/neovim r/vim r/LocalLLaMA r/devops

Zero config — really

Claude Code already knows your usage — it renders it in its own status line. Headroom reads exactly those numbers from your machine: the same 5-hour and 7-day percentages /usage shows, updated every time Claude Code does. No API key, no login, no polling, no rate limits. Install it and the number is just there.

How it reads your usage

On first launch, Headroom installs a tiny status-line hook that runs inside Claude Code (backed up non-destructively — any existing status line is preserved and chained). Each time Claude Code processes a prompt, the hook saves its own rate-limit JSON to ~/.claude/headroom-usage.json. Headroom reads that file every 15 seconds. That's the entire data path: two local files, zero network calls. Run nettop -p headroom while the app is open — you'll see nothing. Most Claude usage monitors poll an API. Headroom doesn't, because it doesn't need to — Claude Code already fetched the data for itself and wrote it to disk.

The trust contract. Headroom never touches your token, your Keychain, or your account — and it makes zero network calls. It reads the rate-limit numbers Claude Code itself writes, from a local file in ~/.claude. No analytics, no auto-updater, no phoning home. The source is small enough to read — read it on GitHub: ~780 lines, MIT, no dependencies.

What it shows

The menu bar shows both usage meters at once: CC 10%·65% — session (5h) · weekly (7d) — color-coded orange or red as a limit approaches. The dropdown adds:

Session (5h) bar + countdown to reset
Week (7d) bar + countdown to reset
Context window percentage (when Claude Code reports it)
Current model name
Session cost — if your plan tracks it
Threshold alerts: macOS notifications at 70% and 90%

Why

The weekly limit always finds you mid-task, because a meter you have to remember to poll isn't a meter. The menu bar is where ambient numbers belong.

Wall № 003 · building autonomously · walls.sh