I Turned My Claude Code Status Bar Into a Budget Dashboard

claude-code-statusline

I spend a lot of time in Claude Code. Enough that I’ve started to develop a feel for when I’m burning through my weekly quota too fast — but “a feel” isn’t the same as knowing. So I built a custom status line that tells me exactly where I stand, at a glance, every time I look at the terminal.

It shows context window usage, which git branch I’m on, session and weekly quota burn rates, and a percentage showing how much of my weekly budget window has actually elapsed. That last number turns out to be pretty great.

The Problem With Pace Alone

Claude Code’s built-in status line is minimal. It shows you the model and not much else. If you’re on a Pro or Max plan with weekly limits, there’s no native way to see your pace for quota usage without leaving your terminal. You can use /usage to identify your percent of weekly window burned, but not how that compares to the percent you are through your weekly window in time.

ccburn fills part of this gap nicely — it’s a CLI tool that reads Claude Code’s OAuth token and queries the (undocumented) usage API to show session, weekly, and Sonnet-class utilization. It even gives you pace indicators: are you behind pace, on pace, or ahead.

But pace is relative to what? ccburn calculates it against the full weekly window, which is useful, but I wanted something more visceral: a number I can compare directly to my usage percentage and immediately know if I’m in trouble. It’s like being on lap 60 of 99 in a racing sim and being able to see the ghostly outline of your pace car just ahead of you.

The Time Budget Trick

My Claude budget resets every Monday at 11 AM. So if it’s Wednesday at 11 AM, I’m exactly 2/7 of the way through my weekly window — about 29%.

If my weekly usage at that point is 25%, I’m doing fine. If it’s 50%, I need to ease off. The math is dead simple, but doing it in your head every time you glance at the terminal is exactly the kind of thing computers should handle.

So the status line now shows:

weekly: 55%_~ (29%)

The first number is quota used. The parenthetical is time elapsed. If the first number is lower than the second, you’re pacing well. If it’s higher, you’re on track to hit your limit before reset. That’s the whole concept.

What It Looks Like

The full status line reads left to right:

Each element:

• ctx — context window usage, dynamically color-coded: grey before you type, green when you have room, yellow when it’s getting full, red when you’re about to hit compression
• location — current git branch or folder name
• session — session quota with pace indicator and minutes until reset
• weekly — weekly quota with pace indicator, plus the time-budget percentage
• sonnet — weekly Sonnet-class model utilization

The pace indicators are simple: ~ means behind pace (you’re fine), = means on pace, ! means ahead (watch it).

The Rainbow

This is the part that’s entirely unnecessary but fun. The status line uses a nine-color gradient that flows cool to warm from left to right: magenta, blue, cyan, teal, green, lime, yellow, orange, red. Each section title and value gets its own color, excluding the dynamically colored CTX section.

It started as just picking distinct colors so the sections were easy to scan, but once I had six ANSI colors assigned, the non-spectral ordering bugged me. So I shuffled them into ROYGBIV order, realized I needed three more to fill the gaps, and pulled in 256-color codes for teal, lime, and orange.

Is this useful? Debatable. Does it make me happy every time I open a terminal? Yes.

How It Works

Claude Code supports a custom status line via settings.json. You point it at a shell script, and Claude Code pipes JSON to stdin on every render — including context window stats and the current working directory.

The script does three things:

1. Parses the input JSON for context percentage and cwd (using grep, not jq, for speed)
2. Checks git for the current branch name
3. Reads cached ccburn output for quota data

The ccburn cache is the key to keeping things fast. ccburn calls an undocumented Anthropic API endpoint, so you don’t want it firing on every status line render. The script caches ccburn’s JSON output and only refreshes it every two minutes. The status line itself runs in under 50ms — all local, no API calls on the hot path.

The weekly time-budget calculation is pure bash arithmetic:

RESET_DAY=1    # Monday
RESET_HOUR=11  # 11 AM

dow=$(date +%u)
h=$((10#$(date +%H))); m=$((10#$(date +%M)))
secs_since_reset=$(( (dow - 1) * 86400 + h * 3600 + m * 60 - RESET_DAY * 86400 - RESET_HOUR * 3600 + 86400 ))
if [ "$secs_since_reset" -lt 0 ]; then
  secs_since_reset=$(( secs_since_reset + 604800 ))
fi
time_pct=$(( secs_since_reset * 100 / 604800 ))

Seconds since your reset point, divided by seconds in a week, times 100. The negative check handles the wrap-around when you’re before your reset time on reset day.

Try It

The whole thing is one bash script — no dependencies beyond jq and optionally ccburn. It degrades gracefully: without ccburn, you still get context percentage and git branch.

I’ve published it on GitHub: claude-code-statusline. The README covers installation, configuring your own reset schedule, and customizing the color gradient.

The configuration is just two lines in ~/.claude/settings.json:

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

If you’re spending real time in Claude Code and you’re on a plan with limits, knowing where you stand at a glance changes how you work. You stop wondering “should I start this big task or will I run out?” and start just knowing.

---

Update (March 9, 2026): The statusline caught its first real problem the morning after I published this. When my weekly window reset on Monday at 11 AM, the status bar still showed 84% — last week’s usage. The Anthropic API was returning stale data: the resets_at timestamp was 40 minutes in the past, but utilization hadn’t zeroed out yet.

Two fixes: the statusline script now checks for negative time remaining and overrides to 0%, and I submitted a PR to ccburn that adds effective_utilization — a property that returns 0 when the window has expired. Both the script and the upstream repo are updated.

The time-budget percentage turned out to be useful for more than pacing. It was the (0%) next to the 84% that made the staleness obvious — if you’re 0% through a new window but showing 84% usage, something is clearly wrong.