Your usage limits, in the Claude Code status line

The short version

What Claude Code gives your script

The status line runs a command you choose and sends session data to it on stdin. For claude.ai subscribers, that data includes a rate_limits object:

• rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage: 0 to 100.
• rate_limits.five_hour.resets_at and rate_limits.seven_day.resets_at: Unix epoch seconds.

Some caveats from the docs: rate_limits appears only for 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 reset time passes. Your script has to handle missing fields, which is what // empty does below.

Do it yourself

1. Save the script as ~/.claude/statusline.sh. It needs jq (brew install jq).

#!/bin/bash
# ~/.claude/statusline.sh: model, 5-hour and weekly usage, next reset
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
reset=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')

out="$model"
[ -n "$five" ] && out="$out · 5h $(printf '%.0f' "$five")%"
[ -n "$week" ] && out="$out · wk $(printf '%.0f' "$week")%"
[ -n "$reset" ] && out="$out · resets $(date -r "$reset" +%H:%M)"
echo "$out"

date -r is the macOS form. On Linux, use date -d @"$reset" +%H:%M.

2. Make it executable: chmod +x ~/.claude/statusline.sh

3. Point Claude Code at it in ~/.claude/settings.json:

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

The script runs when a session starts, after each new assistant message, and when a rate-limit window it last saw reaches its reset time. Updates are debounced by 300 ms. Add "refreshInterval": 60 if you also want it re-run every minute while the session is idle. Prefer not to write it by hand? Run /statusline and describe what you want.

This is the approach in Anthropic’s own status line docs, which include Bash, Python and Node versions. If you only need Claude’s numbers in one terminal, this is all you need.

Variation: color by how full each window is

The status line supports ANSI colors (your terminal has to as well), and each line your script prints becomes a row. This version colors each window green, yellow or red and adds the weekly reset day, which matters more than the time once you’re near the weekly limit:

#!/bin/bash
# ~/.claude/statusline.sh: 5-hour and weekly usage, colored by how full they are
input=$(cat)
color() {  # green under 50, yellow under 80, red from 80
  p=${1%.*}
  if [ "$p" -ge 80 ]; then printf '\033[31m'; elif [ "$p" -ge 50 ]; then printf '\033[33m'; else printf '\033[32m'; fi
}
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
wreset=$(echo "$input" | jq -r '.rate_limits.seven_day.resets_at // empty')
out=""
[ -n "$five" ] && out="$out$(color "$five")5h $(printf '%.0f' "$five")%\033[0m "
[ -n "$week" ] && out="$out$(color "$week")wk $(printf '%.0f' "$week")%\033[0m"
[ -n "$wreset" ] && out="$out · week resets $(date -r "$wreset" '+%a %H:%M')"
printf '%b\n' "$out"

The thresholds are ours; pick your own. Anthropic’s docs note that complex escape sequences can occasionally garble output and suggest plain text if that happens. date -r with a format is the macOS form; on Linux use date -d @"$wreset" '+%a %H:%M'.

Other fields worth adding

• context_window.used_percentage: how full this conversation is. It’s calculated from input tokens only and can be null early in a session.
• cost.total_cost_usd: an estimated session cost at list price. On a subscription it isn’t your bill.
• prompt_cache: hit ratio and whether the cache is warm (v2.1.251+), useful if usage climbs after breaks.

And Codex?

Codex has its own status line. Run /statusline in the Codex CLI and turn on the rate-limits item. The two tools don’t share one line, though, so with plain DIY scripts each terminal shows only its own tool.

The one-switch option: Quotchi

Quotchi, our Mac menu bar app, has an opt-in, Free status line integration under Settings → AI tools → Claude. Here’s what it does differently from the DIY script:

• Previews the change first and shows the exact before and after of your statusLine entry. Nothing is written until you confirm.
• Backs up settings.json and changes only the statusLine value. Everything else stays byte-for-byte.
• Chains your existing status line. Your current command still runs, and Quotchi appends a segment such as Claude 5h 42% · wk 61% · Codex 30%.
• Adds Codex to the same line, from the reading in the menu bar. A Codex reading older than five minutes shows as stale instead of an old number.
• Removes cleanly. Turning it off restores your previous status line exactly.

It won’t touch a file it can’t parse safely, and it explains when your organization’s managed settings control the status line. If you’re happy with the script above, keep it. Quotchi is for when you also want Codex, menu bar alerts and reset times without opening a terminal.

Troubleshooting

echo '{"model":{"display_name":"Opus"},"rate_limits":{"five_hour":{"used_percentage":42,"resets_at":1791900000},"seven_day":{"used_percentage":61,"resets_at":1792200000}}}' | ~/.claude/statusline.sh

Common mistakes and myths

“The status line polls Anthropic for my usage.”

Your script doesn’t fetch anything. Claude Code passes the latest data to your script on stdin when events happen, or on your refreshInterval.

“It works with an API key too.”

rate_limits appears for claude.ai Pro and Max subscribers (or behind a Claude apps gateway with spend limits). API-key sessions have no plan windows to show.

“Context percentage is my usage limit.”

It’s how full this conversation is. Your plan usage is in rate_limits.

“A status line replaces /usage.”

It shows the two percentages and reset times. /usage also explains what used the allowance.

What changed recently

Sources

Official pages we read on October 9, 2026. If anything here disagrees with them, they win.

• Claude Code docs: Customize your status line
• Claude Code docs: Commands
• Codex docs: Slash commands in Codex CLI

FAQ