Claude Code statusline usage: show your limits, resets and an alert

To show usage in the Claude Code statusline, read the rate_limits object that Claude Code hands your status line script: it carries the percent used and the reset time for the five-hour window and the weekly window. A short script, or a ready-made tool like ccstatusline, turns those numbers into something like 5h 42% (resets in 87m) | week 61% under your prompt. For a warning when you are not looking at the terminal, add a desktop alert from UsageAtlas.

Everything below follows Anthropic's status line reference, checked in November 2026.

What Claude Code sends about your limits

Every time the status line runs, your script receives a JSON object on standard input. The usage part looks like this:

"rate_limits": {
  "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
  "seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
}

Percentages run from 0 to 100, and resets_at is a Unix timestamp in seconds. Three rules decide whether you see it at all:

• It is sent only to claude.ai Pro, Max and Ultra subscribers, or to people behind a Claude apps gateway with a spend limit. On plain API billing the object never appears, so show cost.total_cost_usd instead.
• It arrives after the first API response of a session, not at launch.
• Either window can be missing, and Claude Code removes a window once its reset time passes.

A usage-only status line

Save this as ~/.claude/statusline.sh, run chmod +x on it, and point the statusLine command in ~/.claude/settings.json at the file. It needs jq.

#!/bin/bash
input=$(cat)
now=$(date +%s)
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
reset=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
out=""
[ -n "$five" ] && out="5h ${five%.*}% (resets in $(( (${reset:-$now} - now) / 60 ))m)"
[ -n "$week" ] && out="$out | week ${week%.*}%"
echo "${out:-limits appear after the first reply}"

Two settings make it behave better. Claude Code reruns the script on events such as a new reply or a window reaching its reset time, but a countdown goes stale while the session sits idle. Add "refreshInterval": 60 to the statusLine block so the minutes keep moving. And if you would rather not edit files, type /statusline show my five-hour and weekly usage with reset times and Claude Code writes a similar script for you.

Color it before it bites

Plain numbers are easy to ignore. The status line accepts ANSI color codes, so a few extra lines can turn the segment yellow past one threshold and red past another. Pick the cut-offs from your own habits: someone who burns a window in two hours needs an earlier warning than someone who rarely passes half.

Test the script before you trust it. Pipe a made-up JSON object into it by hand, as Anthropic's docs suggest, because a script that errors or exits with a non-zero code leaves the whole row blank rather than showing a partial line.

The no-script route

ccstatusline, a free community tool, has usage widgets ready to drop in. Block Usage covers the five-hour window, separate widgets track weekly usage overall and per model, Block Reset Timer and Weekly Reset Timer count down, and Block Forecast projects where the five-hour window will land at reset from your recent pace. Run npx -y ccstatusline@latest to pick widgets in a terminal menu. ccusage also has a statusline command that shows the current five-hour block's cost and time left.

When the status line is not enough

A status line only shows while that terminal is open, and only shows Claude. It cannot tap you on the shoulder when you are in another window, and it keeps no record of which days ran hot.

UsageAtlas watches the same five-hour and weekly windows from your tray on Windows, macOS or Linux. You set a remaining-capacity threshold for each window, and it sends one desktop notification per reset cycle when you cross it, so you hear about it once, not every minute. It also keeps daily history of tokens and estimated cost, and covers Codex, Cursor and other coding tools. It is free and open source, needs no account for local tracking, and does not read prompts or responses.

If you sit in one Claude Code session all day and glance down often, the status line alone does the job. If limits catch you mid-task, run both.