How to show your 5-hour and weekly usage in the status line

by vortwangUpdated Sep 18, 2026

Claude Code passes rate_limits to your status-line script: 'The rate_limits object contains a rolling five_hour window and a weekly seven_day window', each with used_percentage (0 to 100) and resets_at (Unix epoch seconds). It appears only for Pro and Max subscribers and only after the first API response, so scripts use jq's '// empty'. Codex has /statusline: pick items in a picker, saved to tui.status_line in config.toml; the rate-limit items are five-hour-limit and weekly-limit.

What the official docs say

The rate_limits object contains a rolling five_hour window and a weekly seven_day window.
Quoted from Claude Code docs: Status line — Rate limit usage (rate_limits.five_hour / seven_day: used_percentage, resets_at)
Each window provides used_percentage, from 0 to 100, and resets_at, the Unix epoch seconds when the window resets.
Quoted from Claude Code docs: Status line — Rate limit usage (rate_limits.five_hour / seven_day: used_percentage, resets_at)
only present for claude.ai Pro and Max subscribers, or behind a Claude apps gateway with spend limits, and only after the first API response
Quoted from Claude Code docs: Status line — Rate limit usage (rate_limits.five_hour / seven_day: used_percentage, resets_at)
To watch your remaining allowance continuously, add the rate_limits fields to a custom status line
Quoted from Claude Code docs: Error reference — "You've hit your session limit" (Desktop Auto-continue checkbox; 85% warning; rate_limits in the status line)
Configure TUI status-line fields interactively.
Quoted from Codex docs: Slash commands — Configure footer items with /statusline (persists to tui.status_line in config.toml)
The footer status line updates immediately and persists to tui.status_line in config.toml.
Quoted from Codex docs: Slash commands — Configure footer items with /statusline (persists to tui.status_line in config.toml)
Ordered list of TUI footer status-line item identifiers. null disables the status line.
Quoted from Codex docs: Configuration reference — tui.status_line (ordered list of footer status-line item identifiers)
Remaining usage on the primary usage limit (omitted when unavailable)
Quoted from openai/codex repository source: codex-rs/tui/src/bottom_pane/status_line_setup.rs — StatusLineItem enum (five-hour-limit, weekly-limit)

Steps

Claude Code. A status line is a script named in the statusLine setting of ~/.claude/settings.json; Claude Code pipes session JSON to it. The docs: 'The rate_limits object contains a rolling five_hour window and a weekly seven_day window. Each window provides used_percentage, from 0 to 100, and resets_at, the Unix epoch seconds when the window resets.' Behind a Claude apps gateway a spend_limit window with the same two fields is added (v2.1.251+). The Error reference recommends this to 'watch your remaining allowance continuously' before a 'You've used 85% of your session limit' warning turns into a block.

The object is 'only present for claude.ai Pro and Max subscribers, or behind a Claude apps gateway with spend limits, and only after the first API response'. Each window 'may be independently absent', and 'Claude Code drops a window once its resets_at time passes'. The official Bash example therefore reads jq -r '.rate_limits.five_hour.used_percentage // empty' and prints nothing when the field is missing.

Codex. /statusline is documented as 'Configure TUI status-line fields interactively': a picker to toggle and reorder items that 'persists to tui.status_line in config.toml'. The docs list the item kinds (model, context stats, rate limits, git branch, token counters, session id, and so on) and the default list ['model-with-reasoning', 'context-remaining', 'current-dir'], but not the identifiers for the rate-limit items. In the openai/codex source those are five-hour-limit ('Remaining usage on the primary usage limit (omitted when unavailable)') and weekly-limit, rendered like 'weekly 82% left'. Neither tool's status line changes when a limit resets; it reads the same windows that /usage and /status show.

Claude Code: let /statusline write the script
Run /statusline with a description such as 'show model, 5-hour and weekly usage percentages'. The command table says: 'Describe what you want, or run without arguments to auto-configure from your shell prompt.' Claude Code generates a script in ~/.claude/ and updates your settings.
Or write the statusLine setting yourself
Add a statusLine field to ~/.claude/settings.json with type 'command' and command pointing at your script. The script receives session JSON on stdin; the official Bash example reads FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty') and WEEK from .rate_limits.seven_day.used_percentage, then prints '[Model] | 5h: 42% 7d: 17%'.
Read the four fields
rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage run from 0 to 100. rate_limits.five_hour.resets_at and rate_limits.seven_day.resets_at are Unix epoch seconds when each window resets, so a script can print a countdown. Behind a Claude apps gateway, rate_limits.spend_limit carries the same two fields (v2.1.251 or later) and its percentage can exceed 100.
Handle the object being absent
rate_limits appears only for claude.ai Pro and Max subscribers (or behind a gateway with spend limits) and only after the first API response in the session; each window may be independently absent, and a window is dropped once its resets_at passes. Use '// empty' in jq, or .get() in Python, so the line still renders without it.
Codex: open the /statusline picker
Type /statusline in the Codex CLI, toggle and reorder items in the picker, then confirm. The docs: 'The footer status line updates immediately and persists to tui.status_line in config.toml.' Available items include model, context stats, rate limits, git branch, token counters and session id.
Codex: name the rate-limit items in config.toml
tui.status_line is an 'Ordered list of TUI footer status-line item identifiers'; the docs' default is ['model-with-reasoning', 'context-remaining', 'current-dir']. The rate-limit identifiers are not in the docs' sample; the openai/codex source defines them as five-hour-limit and weekly-limit, each 'omitted when unavailable', for example status_line = ['model', 'five-hour-limit', 'weekly-limit'].
Cross-check with /usage and /status
The status line reads the same windows the in-app screens show: /usage in Claude Code and /status in Codex. When the bar in the status line says 100% and the reset is hours away, the wait-and-continue options on this site apply; an account-wide reset by the vendor shows on the board, not in the status line.

FAQ

Why is rate_limits missing from my Claude Code status line?

Three documented reasons: you are not on a claude.ai Pro or Max subscription (API keys and usage-based billing get no rate_limits), the session has not yet received its first API response, or that window's resets_at has passed and Claude Code dropped it. Scripts should print the line without it.

Is resets_at the same time /usage shows?

Yes. resets_at is the Unix epoch seconds when the five_hour or seven_day window resets, the same reset times /usage displays for the session and weekly bars. It is your own account clock, not an account-wide reset.

Where did five-hour-limit and weekly-limit come from?

From the openai/codex repository source (codex-rs/tui/src/bottom_pane/status_line_setup.rs), where the StatusLineItem enum serializes to kebab-case. The official docs describe the picker and tui.status_line but list only some identifiers; use /statusline if you prefer not to hand-edit config.toml.

Does the status line update when a limit resets?

Claude Code reruns the script on events (debounced at 300ms) or on a refreshInterval timer you set, and shows whatever the API last reported; it drops a window once its resets_at passes, so the percentage disappears or restarts after the reset. Neither status line announces a vendor-wide reset; this board does.

Sources

Want the next reset on your phone?

Get alerted Page me