Get notified before Claude Code stops you

Claude Code has two invisible meters — a 5-hour session window and a 7-day weekly rolling cap. When either fills, it stops mid-task with no warning. Headroom fires native macOS notifications before the hard stop, so you can save your work and plan around it.

Headroom makes zero network calls. The notification system reads from the same local file Claude Code's hook writes — no API key, no token, nothing leaves your machine.

How notifications work

On first launch, Headroom requests macOS notification permission (one prompt, macOS remembers your answer). After that, it watches your usage meters and fires an alert when a threshold is crossed:

Each notification fires once per threshold crossing per window, then resets when the window rolls over. You won't get the same alert twice for the same period.

Configuring thresholds

Create or edit ~/.claude/headroom-prefs.json to move the thresholds to whatever % works for you:

{
  "sessionWarnAt": 60,
  "sessionCritAt": 85,
  "weekWarnAt": 70,
  "weekCritAt": 90
}

Headroom reads this file on every refresh (every 15 seconds). No restart needed — changes take effect next tick.

sessionWarnAt% of 5-hour session window for the first alert (default: 70) sessionCritAt% of 5-hour session window for the critical alert (default: 90) weekWarnAt% of 7-day weekly cap for the first alert (default: 70) weekCritAt% of 7-day weekly cap for the critical alert (default: 90)

All values must be between 1 and 99. Values outside that range are silently clamped. Unknown keys are ignored. If the file is missing or malformed, defaults apply.

What the notifications look like

A warning notification reads:

Session at 71% — warning
Your 5-hour Claude Code window is 71% full. Resets in 1h 24m.

A critical notification reads:

Session at 92% — critical
Your 5-hour Claude Code window is 92% full. Resets in 23m.

Enabling / disabling notifications

Notifications are on by default. To disable them entirely, open System Settings → Notifications → Headroom and toggle them off. macOS controls the delivery; Headroom just requests permission and posts the content.

To disable only one tier (say, keep warnings but suppress criticals), set sessionCritAt to 99 — Headroom won't reach the threshold under normal usage.

The menu bar shows it too

While notifications fire at thresholds, the menu bar title (CC 23%·67%) is always visible. The color tracks whichever window is closest to its limit:

The dropdown adds reset countdowns ("resets in 1h 24m"), a pace forecast ("~2h at current pace"), context window fill, active model, and session cost.

Install Headroom — free, ~267 KB, macOS 13+

Download Headroom

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

Related