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

> The rate_limits fields Claude Code passes to your script, a short script that prints both windows, the widget route, and a way to hear about a low window when the terminal is closed.

URL: https://claudegpt.si/news/claude-code-statusline-usage-limits-reset  
Published: 2026-11-04T06:14:43.503Z  
Author: ClaudeGPT Si Newsroom  
Section: Guides  
Topics: Claude Code, Usage limits, Alerts  
Publisher: ClaudeGPT Si

## Key takeaways

- Claude Code passes rate_limits.five_hour and rate_limits.seven_day to status line scripts, each with a percent used and a Unix reset time, for Pro, Max and Ultra subscribers.
- The fields appear only after the first API response, so scripts should print nothing or a placeholder when they are missing, and a refreshInterval keeps countdowns current.
- A status line only shows while the terminal is open, so UsageAtlas adds a desktop alert per reset cycle plus usage history for Claude Code and other coding tools.

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](https://code.claude.com/docs/en/statusline), 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:

```json
"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`.

```bash
#!/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](https://github.com/sirmalloc/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](https://usageatlas.com/guides/ai-coding-usage-alerts) 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.

## Frequently asked questions

### Why does my status line not show usage limits?

The rate_limits object is only sent to claude.ai Pro, Max and Ultra subscribers, or behind a gateway with a spend limit, and only after the session's first API response. API-key users see cost and context fields instead.

### How do I show the weekly reset time?

Read rate_limits.seven_day.resets_at, which is Unix epoch seconds, and subtract the current time. ccstatusline's Weekly Reset Timer widget does this without a script.

### Can I get notified before I hit the limit?

Not from the status line itself. A desktop tracker such as UsageAtlas lets you set a threshold for each window and sends one notification per reset cycle.

## Sources

- [Customize your status line](https://code.claude.com/docs/en/statusline), Anthropic
- [ccstatusline](https://github.com/sirmalloc/ccstatusline), GitHub
- [Statusline integration](https://ccusage.com/guide/statusline), ccusage
- [Get an alert before you hit an AI coding limit](https://usageatlas.com/guides/ai-coding-usage-alerts), UsageAtlas