Help with Headroom.

No rings, no sessions: grant the two folders

Headroom can only read folders you allow. Click its pill in the menu bar, then Give access, or open Settings from the gear menu and click Grant access next to each folder. The folder picker opens in the right place, so you only confirm.

• ~/.claude for Claude Code sessions and context.
• ~/Library/Application Support/Claude for the plan limits the Claude desktop app records.

Headroom only asks for folders that exist. If Settings says Claude Code or the Claude desktop app isn’t found, that folder isn’t needed yet.

The rings say “as of”

“As of 42m ago” means the newest usage reading is more than 30 minutes old, so the rings are drawn faded. The limits come from the Claude desktop app, which records them about every 15 minutes while it’s open, or from connected terminal sessions as they run. Open the Claude app, or keep working in a connected terminal session, and the rings catch up.

A tilde before a reset time, as in resets ~Sun 7 PM, means Headroom worked it out from your usage history instead of reading an exact time.

Terminal sessions or limits are missing: connect the terminal

Click the pill, then the gear, then Connect terminal, and confirm. Headroom backs up ~/.claude/settings.json first, adds a status line and hooks, and keeps your own status line working. Sessions you start after connecting show up with their limits and status. Restart sessions that were already running.

Disconnect the terminal

Gear menu, then Disconnect terminal. It removes exactly what Connect terminal added to ~/.claude/settings.json, restores your original status line, and deletes ~/.claude/headroom.

Sessions you don’t recognize: sample data

When Headroom finds no Claude data at all, the empty panel offers Preview with sample data, with made-up sessions and limits. The same switch is in Settings, as Show sample data. While it’s on, the panel footer reads Sample data · Turn off. Click Turn off to go back to your own data.

Turn off moments

Don’t want the pill to widen when a session finishes or needs you? Open Settings from the gear menu and turn off Show moments.

Quit or uninstall

To quit, click the pill, then the gear, then Quit Headroom. To stop it from opening when you log in, turn off Launch at login in Settings.

To uninstall:

1. If you connected the terminal, choose Disconnect terminal first. That removes the status line and hooks (the bridge) from ~/.claude/settings.json and deletes ~/.claude/headroom.
2. Quit Headroom.
3. Move Headroom from your Applications folder to the Trash.
4. To remove its settings too, delete ~/Library/Containers/com.niomartinez.headroom if it’s still there. In the Finder, choose Go › Go to Folder and paste that path.

Already deleted it without disconnecting? The status line and hooks stay in ~/.claude/settings.json, and the bridge keeps writing its status files until both the app and the folder in step 4 are gone. After that it writes nothing and only runs the status line you had before, if any. To remove the entries, install Headroom again and choose Disconnect terminal.