Guide

Claude Code statusline: your limits under the prompt

Claude Code runs a script of your choice after every reply and shows whatever it prints. That script gets your usage limits for free.

The short answer

Set statusLine in ~/.claude/settings.json to a command. After each reply, Claude Code sends that command JSON on stdin, including rate_limits.five_hour and rate_limits.seven_day with used_percentage and resets_at on Pro and Max. Print them, and your limits sit under the prompt.

How the status line works

The status line is a row under Claude Code's prompt. You point it at a command in settings.json; Claude Code runs it when a session starts, after each reply, and at a few other moments, passes it JSON about the session on stdin, and shows what it prints. Colors (ANSI codes) and multiple lines work.

The JSON includes the model, the working folder, context window use, cost, and on Pro and Max plans, rate_limits:

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

resets_at is a Unix timestamp. rate_limits appears after the first reply in a session, each window can be missing, and a window drops out once its reset time passes, so scripts should handle absence.

A status line that shows your limits

Save this as ~/.claude/statusline.sh and run chmod +x on it. It needs jq.

#!/bin/bash
input=$(cat)
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')
line="$(echo "$input" | jq -r '.model.display_name')"
[ -n "$five" ] && line="$line · 5h ${five%.*}%"
[ -n "$reset" ] && line="$line (resets $(date -r "$reset" +%-I:%M%p))"
[ -n "$week" ] && line="$line · week ${week%.*}%"
echo "$line"

Then add it to ~/.claude/settings.json:

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

It shows up after Claude's next reply: Opus · 5h 23% (resets 3:00PM) · week 41%. On Linux, use date -d "@$reset" instead of date -r.

A status line that forecasts

A percentage tells you where you are, not where you're headed. Fuel Gauge adds a line that does the math at your recent pace:

⛽ 5h 55% out ~11:50a · wk 41% ok

Turn it on from the app, or run fuelgauge install-statusline. If you already have a status line, it keeps running and prints above the forecast, and your settings.json is backed up first. fuelgauge uninstall-statusline puts things back.

Other status line tools

ccstatusline is a popular, highly customizable status line with dozens of widgets, including session and weekly usage. It works alongside Fuel Gauge: keep it as your status line and Fuel Gauge adds its line underneath.

Sources

Checked on October 20, 2026. Anthropic changes plans from time to time, so the help pages are the final word.

Questions

Where is the Claude Code statusline configured?

In settings.json, usually ~/.claude/settings.json, under statusLine with a type of command and the command to run.

Can the status line show my usage limits?

Yes, on Pro and Max. Claude Code passes rate_limits.five_hour and rate_limits.seven_day, each with used_percentage and resets_at, to the status line command.

Why doesn't my status line show rate limits?

They appear only for Pro and Max subscribers, and only after the first reply in a session. A window drops out once its reset time passes.

Can I use two status line tools?

Claude Code runs one command. Fuel Gauge's installer wraps your existing one, so both print: yours first, the forecast under it.

Know if you'll make it to reset.

Free. No account, no subscription.

Download for Mac View source code

brew install --cask coreyhaines31/tap/fuelgauge

Or ask your coding agent:

Install Fuel Gauge on my Mac: run `brew install --cask coreyhaines31/tap/fuelgauge`, open Fuel Gauge, then run `fuelgauge install-statusline` and `fuelgauge status`.

macOS 14 Sonoma or later · Apple Silicon and Intel