Install Headroom via Homebrew

One command. No API key, no permissions dialog, no configuration.

brew install --cask patwalls/tap/headroom

That's it. Headroom appears in your menu bar immediately.

What this command does

Homebrew casks install macOS GUI applications. The command above:

Adds the patwalls/tap third-party tap (only on first install — Homebrew caches it)
Downloads the signed + notarized Headroom.zip (~267 KB)
Moves Headroom.app to /Applications
Launches the app

The app hooks itself into Claude Code's status line (via ~/.claude/settings.json) during first launch, then shows the usage % in your macOS menu bar.

Prerequisites

Homebrew — install at brew.sh if you don't have it
macOS 13 Ventura or later
Claude Code installed and running — Headroom reads the data Claude Code writes; it shows CC —% placeholders until the first Claude Code status line fires

Verify the installation

# Check the app is installed
brew list --cask | grep headroom

# Check the version
brew info --cask patwalls/tap/headroom

# Check the hook was installed (should show statusLineHook)
cat ~/.claude/settings.json | grep statusLineHook

# Check the data file is being written
cat ~/.claude/headroom-usage.json

The tap: patwalls/tap

Headroom is distributed through a third-party Homebrew tap at github.com/patwalls/homebrew-tap. Homebrew taps are just GitHub repositories with cask formulas. The tap is added automatically when you run the install command.

To add the tap manually (without installing):

brew tap patwalls/tap

Update Headroom

brew upgrade --cask headroom

Or upgrade all your casks at once:

brew upgrade --cask

Headroom doesn't auto-update — Homebrew is the update mechanism.

Uninstall

# Remove the app
brew uninstall --cask headroom

# Optionally remove the hook from settings.json
# Open ~/.claude/settings.json and remove the statusLineHook key

# Optionally remove the data file
rm ~/.claude/headroom-usage.json

Troubleshooting

"cannot be opened because Apple cannot check it for malicious software" — This should not happen with the notarized build, but if it does: go to System Preferences → Privacy & Security → open anyway. Or: xattr -dr com.apple.quarantine /Applications/Headroom.app.

Menu bar shows CC —% — Headroom is running but hasn't seen a Claude Code status line update yet. Open Claude Code and run any command; the % should appear within a few seconds. Or check that the hook is installed: cat ~/.claude/settings.json | grep statusLineHook.

Formula not found / tap error — Run brew update first to refresh tap indexes, then retry the install.

Already installed a previous version from a .zip — Move the old Headroom.app to Trash, then run the Homebrew command. Homebrew will install cleanly.

Manual download (alternative)

If you prefer not to use Homebrew: download Headroom.zip directly. Unzip it and drag Headroom.app to your Applications folder.

→ Getting started guide
→ How the statusLineHook works
→ FAQ