Claude Code Status Line

The status bar at the bottom of Claude Code shows live usage data — and that data is available to external tools.

What the status line shows

When Claude Code is active, the bottom of the terminal shows a status line with multiple fields, updated after each response:

⠿ claude-sonnet-4-6  23% session · 67% weekly · 41% context · $0.34

Field	What it means
Model	Active Claude model (claude-sonnet-4-6, claude-opus-4-8, claude-fable-5, etc.)
Session %	How much of the 5-hour rolling token window you've used
Weekly %	How much of the 7-day rolling token cap you've used
Context %	How full the current conversation context window is (resets on /clear or /compact)
Cost	Cumulative token cost for this session

How Headroom reads the status line

Claude Code has a statusLineHook feature: if configured, it invokes a shell script each time the status line updates, passing the raw data as JSON to stdin. Headroom installs itself as this hook — it receives the JSON, writes it to ~/.claude/headroom-usage.json, and the macOS app reads from that file.

The hook entry in ~/.claude/settings.json looks like this:

{
  "statusLineHook": "node ~/.claude/headroom-hook.js"
}

The JSON Headroom writes:

{
  "sessionUsagePct": 23.1,
  "weeklyUsagePct": 67.4,
  "contextUsagePct": 41.0,
  "modelName": "claude-sonnet-4-6",
  "sessionCost": 0.34,
  "sessionResetSec": 14400,
  "weeklyResetSec": 201600
}

Reading the status line data yourself

Once Headroom is installed, the data file is updated automatically. Any tool can read it:

# All fields
cat ~/.claude/headroom-usage.json | python3 -m json.tool

# Just the usage percentages
jq '{sessionUsagePct, weeklyUsagePct, contextUsagePct}' ~/.claude/headroom-usage.json

# Quick one-liner for shell prompt
jq -r '"CC " + (.sessionUsagePct|floor|tostring) + "%·" + (.weeklyUsagePct|floor|tostring) + "%"' ~/.claude/headroom-usage.json

Write your own status line hook

You don't need Headroom to read the status line data — you can install your own hook in ~/.claude/settings.json:

{
  "statusLineHook": "cat >> /tmp/claude-usage.log"
}

Or a Node script that does whatever you want:

// ~/.claude/my-hook.js
const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
// data.sessionUsagePct, data.weeklyUsagePct, data.contextUsagePct, etc.
require('fs').writeFileSync('/tmp/claude-usage.json', JSON.stringify(data));

Then in settings.json: "statusLineHook": "node ~/.claude/my-hook.js"

The statusLineHook vs the /usage command

/usage is a command you run inside Claude Code — it shows current usage on demand. The statusLineHook runs automatically after every response, so external tools always have fresh data without polling Claude Code or the API.

→ Full hook documentation
→ Show usage in your shell prompt
→ Show usage in tmux status bar
→ Show usage in Starship

The menu bar view

Headroom takes the status line data and shows it as a persistent menu bar item — always visible, color-coded, with countdown timers in the dropdown.

brew install --cask patwalls/tap/headroom