Monitoring Claude Code usage in real time

Where live quota data comes from

This is the structural fact that explains every gap in usage tooling, and it changed recently enough that most advice on the internet is wrong about it.

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

The three numbers worth showing

1. Percentage used, per window. This is given to you directly, so there is nothing to compute.
2. Burn rate. Consumption per hour at the current pace. This is what turns a static reading into a prediction.
3. Time to exhaustion. Headroom divided by burn rate, compared against time to reset. The only one of the three that changes a decision.

A gauge showing 60 percent used means nothing on its own. Sixty percent used, burning 25 percent an hour, with 96 minutes left in the window, means the window resets before you run out and you can start the big refactor. Same reading, opposite decision, and the difference is arithmetic you have to do yourself because nothing does it for you.

Build a predictive monitor in twenty lines

Claude Code gives you a percentage but not a trend, because it hands your script one reading at a time. Keep your own samples and the trend falls out. This runs as a status line command, so it costs no screen space and no attention.

#!/usr/bin/env bash
# Live 5-hour quota with a burn-rate projection.
input=$(cat)
now=$(date +%s)

pct=$(jq -r '.rate_limits.five_hour.used_percentage // empty' <<< "$input")
reset=$(jq -r '.rate_limits.five_hour.resets_at // 0'          <<< "$input")
[ -z "$pct" ] && exit 0

# Keep a rolling 30 minutes of samples.
log="$HOME/.claude/quota-5h.log"
printf '%s %s\n' "$now" "$pct" >> "$log"
awk -v cut="$((now - 1800))" '$1 >= cut' "$log" > "$log.new" && mv "$log.new" "$log"

read -r t0 p0 < "$log"   # oldest sample still in the window

awk -v now="$now" -v t0="$t0" -v p="$pct" -v p0="$p0" -v reset="$reset" 'BEGIN {
  dt = now - t0
  if (dt < 120)     { printf "5h %.0f%% | warming up", p; exit }
  burn = (p - p0) * 3600 / dt            # percent per hour
  if (burn <= 0.5)  { printf "5h %.0f%% | steady", p; exit }
  eta  = (100 - p) / burn * 60           # minutes until exhausted
  left = (reset - now) / 60              # minutes until the window resets
  printf "5h %.0f%% | %.0f%%/hr | %s", p, burn,
         (eta < left ? sprintf("%.0fm left", eta) : "resets first")
}'

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

Watching the right window

The weekly cap is the one that ambushes people, precisely because nothing about any individual day looks alarming. Five ordinary days can exhaust it while every 5-hour window stayed comfortable, and the first sign is being blocked on a Thursday with no obvious cause. A monitor that only draws the 5-hour bar will never warn you about this.

When the projection lies

A burn rate assumes the next hour resembles the last twenty minutes. Five documented behaviors break that assumption, and each one moves the line the wrong way.

• A cache miss after a break. Your first message back reprocesses the whole context. Cache lifetime is an hour on a subscription and five minutes on an API key or a cloud provider, so a long lunch produces one very expensive turn that is not a trend.
• Compaction. /compact reads the conversation it is summarising, so it is itself a large request. Your burn rate spikes at exactly the moment you were trying to economise.
• Agent teammates. Each one runs its own context window and keeps consuming until it exits. Anthropic puts agent teams at roughly 7x the tokens of a standard session when teammates run in plan mode, which no trailing average will see coming.
• Scheduled tasks. These fire on their interval even while the session is idle, sending the full context each time. Your burn rate stays non-zero while you are at lunch.
• Model switches. Moving between models changes the price per token by up to five times, so the same volume of work reads as a different rate.

The options

What to do with a warning

• Under 50 percent used: nothing. Do the work.
• 50 to 80 percent: do not start a long autonomous run you cannot finish inside the window.
• Over 80 percent: drop to a cheaper model, finish the current task, commit.
• Over 95 percent: commit now. Getting cut off mid-edit is the one genuinely costly outcome.
• Weekly over 70 percent on a Tuesday: change something structural, not tactically. Clear more often, lower the default model, or move the batch work to an API key.

The habit worth building is committing before a window closes rather than after. An agent interrupted mid-edit leaves a working tree you then have to reason about, and that reconstruction, not the wait, is the real cost of a rate limit.

Questions people ask

Keep reading