Claude Code Statusline: Show Your Rate Limit Usage

Claude Code can show how much of your five-hour and weekly limits you have used, right under the prompt. On Pro and Max, it passes rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage, plus their reset times, to any status line script. Save the script below, add four lines to your settings, and you get a line like this:

[Opus 5.5] ctx 8% | 5h 23% (resets 16:00) | week 41% (resets Thu 16:00)

Each percentage turns yellow from 50% and red from 80%. The script never calls the model, so it costs nothing.

Field names checked on October 25, 2026 against the official status line docs. We ran the script with Claude Code’s sample JSON on macOS (bash 3.2, jq 1.7). Claudekit.ai is an independent community site, not affiliated with Anthropic.

The fields you get

Field	Meaning
rate_limits.five_hour.used_percentage	Share of the five-hour limit used, 0 to 100
rate_limits.five_hour.resets_at	When the five-hour window resets, Unix epoch seconds
rate_limits.seven_day.used_percentage	Share of the weekly limit used, 0 to 100
rate_limits.seven_day.resets_at	When the weekly window resets, Unix epoch seconds
context_window.used_percentage	Share of the context window in use (input tokens only)

Per the docs, rate_limits appears only for claude.ai Pro and Max subscribers (or behind a Claude apps gateway with spend limits), and only after the first API response in a session. Each window can be missing on its own, and Claude Code drops a window once its resets_at time passes. The script below handles all of that. context_window.used_percentage can be null early in a session.

These are percentages of limits Anthropic does not publish in tokens or hours. They tell you how close you are, not how much is left in absolute terms. For the rules behind them, read Claude usage limits explained.

Step 1: save the script

You need jq 1.6 or later (brew install jq, apt install jq). Save this as ~/.claude/statusline.sh:

#!/usr/bin/env bash
# Claude Code status line: model, context use and plan usage limits.
# Claude Code pipes session JSON to stdin; this prints one line. Needs jq.
input=$(cat)

# One jq call. Absent fields become empty strings, and "|" or control characters
# in the model name become spaces, so the columns never shift.
IFS='|' read -r model ctx five five_reset week week_reset <<<"$(
  printf '%s' "$input" | jq -r '
    def pct(p): if p == null then "" else (p | floor | tostring) end;
    def at(t; fmt): if t == null then "" else (t | strflocaltime(fmt)) end;
    [ (.model.display_name // "Claude" | tostring | gsub("[|[:cntrl:]]"; " ")),
      pct(.context_window.used_percentage),
      pct(.rate_limits.five_hour.used_percentage),
      at(.rate_limits.five_hour.resets_at; "%H:%M"),
      pct(.rate_limits.seven_day.used_percentage),
      at(.rate_limits.seven_day.resets_at; "%a %H:%M")
    ] | join("|")'
)"

# Green under 50%, yellow under 80%, red from 80%.
paint() {
  local color=32
  if [ "$1" -ge 80 ]; then color=31; elif [ "$1" -ge 50 ]; then color=33; fi
  printf '\033[%sm%s%%\033[0m' "$color" "$1"
}

line="[${model:-Claude}]"
[ -n "$ctx" ] && line+=" ctx $(paint "$ctx")"
[ -n "$five" ] && line+=" | 5h $(paint "$five")${five_reset:+ (resets $five_reset)}"
[ -n "$week" ] && line+=" | week $(paint "$week")${week_reset:+ (resets $week_reset)}"
printf '%s\n' "$line"

Make it executable:

chmod +x ~/.claude/statusline.sh

Why it is built this way: one jq call keeps the script fast (Claude Code re-runs it after every message), and the |-joined output keeps empty fields in place, so a missing weekly window never shifts the five-hour value into the wrong slot. Reset times print in your local time zone.

Step 2: test it before you wire it up

Feed it a trimmed copy of the sample JSON from the docs:

echo '{"model":{"display_name":"Opus 5.5"},"context_window":{"used_percentage":8},"rate_limits":{"five_hour":{"used_percentage":23.5,"resets_at":1738425600},"seven_day":{"used_percentage":41.2,"resets_at":1738857600}}}' | ~/.claude/statusline.sh

You should see the model, ctx 8%, 5h 23% and week 41% with reset times in your time zone. Now check the API-key case, where rate_limits is absent:

echo '{"model":{"display_name":"Sonnet 5.5"}}' | ~/.claude/statusline.sh

That prints only [Sonnet 5.5], with no error.

Step 3: point Claude Code at it

Add a statusLine entry to ~/.claude/settings.json (or a project’s .claude/settings.json):

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

Restart Claude Code and send one message. The limit percentages appear after the first response. Claude Code re-runs the script when a new message arrives, after /compact, and when a rate-limit window reaches its reset time, so the numbers stay current without a timer.

Prefer not to write it yourself? The built-in /statusline command generates a script from a plain-English request, for example /statusline show 5-hour and weekly rate limit usage with reset times. Review what it writes before you approve it. Community projects such as ccstatusline and claude-hud offer configurable status lines too; check which fields they read before you rely on their numbers.

If it doesn’t work

Symptom	Fix
Nothing shows at all	Run the Step 2 test. If it fails, check that the file is executable and that jq is on your PATH
Only the model name shows	You are on an API key, or no message has been sent yet in this session. rate_limits appears for Pro and Max after the first response
jq: error: strflocaltime/1 is not defined	Your jq is older than 1.6. Upgrade it
Colours show as ^[[32m	Your terminal does not render ANSI colours. Remove the \033[...m parts in paint
Works in the terminal but not on Windows	Claude Code uses Git Bash when installed, otherwise PowerShell. Install Git Bash and jq, or port the script to PowerShell

What to do with the numbers

• 5h climbing fast? Your context is probably large. /clear between unrelated tasks; see how to reduce Claude token usage.
• Week above 80% midweek? Plan around the reset shown, turn on usage credits, or check whether a bigger plan pays off with the plan picker.
• Want the breakdown, not just the total? Run /usage to see which skills, subagents, plugins and MCP servers used the allowance.

Status lines can also show cost, git branch and more; our Claude Code best practices cover the rest of a daily setup.