Headroom

Show your Claude limits in the Claude Code status line

Claude Code passes five_hour and seven_day usage to your status line script. Here are the exact fields, who gets them, when they appear, and what is missing.

ยท 6 min read

Claude Code sends your status line script a JSON object that can include a rate_limits field with two windows: five_hour and seven_day. Read used_percentage and resets_at from each, print them, and your limits sit under the prompt at all times. The field names below come from the status line documentation, and Anthropic's own error reference suggests exactly this as a way to watch your allowance.

The fields

Field Meaning
rate_limits.five_hour.used_percentage How much of the five-hour session limit is used, 0 to 100
rate_limits.five_hour.resets_at When that window resets, as Unix epoch seconds
rate_limits.seven_day.used_percentage How much of the weekly limit is used, 0 to 100
rate_limits.seven_day.resets_at When the weekly limit resets, as Unix epoch seconds

These are values for how much you have used, not how much is left, and they can have decimals (the docs' sample shows 23.5). For the meaning of the two windows, see session vs weekly limit.

Who gets them, and when

Three conditions from the docs decide whether your script sees anything:

  • rate_limits appears only for claude.ai Pro, Max and Ultra subscribers, or behind a Claude apps gateway that sets a spend limit for you (that case uses a separate spend_limit window). The docs do not list API-key sessions, and they do not list Team or Enterprise seats either.
  • It appears only after the first API response in a session. A brand-new session has no rate_limits until Claude has answered once.
  • Each window may be absent on its own, and Claude Code drops a window once its resets_at time passes. A verified Ultra account has no five-hour limit, according to the Ultra plan article, so the docs do not say what that account receives, but a missing five_hour window is the likely result.

Write the script so that a missing field prints nothing instead of failing.

Set it up

The status line is a command you configure under the statusLine key in your settings. Claude Code runs it, passes the JSON on standard input and shows whatever it prints. The fastest route is the built-in /statusline command, which takes a plain description (for example "show my five-hour and weekly usage") and writes a script and the setting for you.

To do it by hand, save this as ~/.claude/statusline.sh. It uses jq, a command-line JSON tool that recent macOS versions include; if jq --version reports nothing, install it first.

#!/bin/bash
input=$(cat)
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty | floor')
five_at=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty | floor')
out=""
if [ -n "$five" ]; then
  out="session ${five}%"
  [ -n "$five_at" ] && out="$out (resets $(date -r "$five_at" '+%H:%M'))"
fi
[ -n "$week" ] && out="${out:+$out, }week ${week}%"
echo "$out"

With both windows present it prints a line such as session 23% (resets 15:30), week 41%. The // empty part is what handles missing windows: if five_hour is absent you get only the weekly part, and if rate_limits is absent the line is blank. date -r with a number of seconds is the macOS form; on Linux use date -d @"$five_at" '+%H:%M' instead.

Make it executable:

chmod +x ~/.claude/statusline.sh

Then add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

If you keep a second account in its own folder with CLAUDE_CONFIG_DIR, that folder has its own settings, so add the same entry to the settings.json inside it.

When it updates

Per the docs, the script runs when a session starts and again when a new assistant message arrives, when /compact finishes, when a rate-limit window reaches its resets_at time, and on a few other events. The optional refreshInterval field re-runs it every N seconds as well, which helps if you show a clock or countdown. The status line runs locally and does not consume API tokens.

Making the numbers easier to act on

A bare percentage is easy to ignore. A few small choices help:

  • Print the reset time next to the percentage, as the script does, so you know whether to wait or to switch work.
  • Colour the number once it passes a threshold you choose. The docs say ANSI colour codes work. Nothing in the Claude Code docs makes any particular percentage special.
  • Keep the line short, so it stays readable in a narrow terminal.

When both windows are present, remember they count at the same time. Anthropic's error reference notes that a single burst of heavy activity can exhaust the weekly allowance before the session window resets, so a low session number does not mean the week is safe.

What is not available

The docs describe no per-model field. Some plans have a separate weekly limit for one model, which as of November 2026 is Fable on Max, Ultra and premium seats (see the Fable weekly limit). Your status line cannot show that limit today. Users have asked for it on GitHub (issue 102989); that is a request, not a promise.

Also not in the field list: any statement of what 100% equals in tokens or messages. Anthropic does not publish that.

Status line or /usage?

The status line shows two numbers all the time without a keystroke. /usage shows more: the breakdown, recommendations and the usage-credits row, as covered in how to check your usage with /usage. Use the status line for glanceable numbers and /usage when you want to know why.

Limits of the status line approach

  • It only exists while a Claude Code session is open. When no session is running, there is nothing to look at.
  • It reflects the account that session is signed in to. With several accounts, each terminal shows its own.
  • It does nothing for accounts you are not currently using.

Seeing every account without a session

If you keep more than one Claude Code account on a Mac, Headroom is a free menu bar app that shows the session and weekly percentages for each signed-in account, plus a per-model weekly limit when an account has one. It reads the sign-in Claude Code already saved on your Mac and never sends a prompt, so looking does not use your limits. It is independent and not made or endorsed by Anthropic. Because Anthropic does not publish these usage figures as an official interface, a change on their side can break it until it is updated; the panel then says it could not read the numbers. Download Headroom.

Troubleshooting

The line is blank. Check that you signed in with a claude.ai Pro, Max or Ultra subscription and not an API key, and that Claude has responded at least once in the session. Pipe sample JSON into the script by hand to rule out a script error.

Only one window shows. That is expected where a window is absent, for example the five-hour window on a verified Ultra account, or a window whose reset time has just passed.

The values differ from /usage. The status line gets new figures with Claude Code's own responses, so usage from claude.ai or another terminal shows up only after the next response in this session. Treat /usage as the reference if they disagree.