CC Usage Band

Watch Claude Code's 5-hour and 7-day limits

·

source at 60cd609

·

MIT license

A one-line band above the prompt with your 5-hour and 7-day limit use and reset times, the context window's tokens, and the last turn's prompt-cache hit rate.

What this mod can do

  • Reviewed at commit 60cd609
  • Reads environment variables
3 more things it can do
  • Remembers data between sessions
  • Adds the /usage-band-preview command
  • Runs on a timer
Good to know (3)
  • The 5h and 7d figures come from subscription rate-limit headers, so they show only on a plan, after a reply.
  • Icons are Nerd Font in Ghostty and plain Unicode elsewhere. Set USAGE_BAND_ICONS to override.
  • On a narrow terminal it drops the bars first, then the countdowns.
Are mods safe?

Preview

Terminal

≡ 44K/200K ● 5% [-]

Claude Desktop

CC Usage Band in Claude Desktop

What it does

In the author's words

A band above the prompt showing your 5-hour and 7-day limits, context window and prompt-cache hit rate, styled for the terminal and the desktop app

What you see
A one-line band above the prompt
Works in
Terminal and Claude Desktop
Slash commands
/usage-band-preview
Uses your tokens
No
Changes files
Nothing
Network access
None
Reviewed commit
60cd609
Preview recorded with
Claude Code 2.1.309

How it works

  1. Reads the session's usage figures as each turn completes.
  2. Shows 5h and 7d bars with the percent used and time to reset, then context tokens.
  3. Ends with the cache hit rate, the share of the last turn's input the prompt cache served.
  4. Turns a metric red past 80% for limits and context, or under 50% for cache hits.

Common questions

How do I see my Claude Code 5-hour and weekly limits while I work?

Usage Band puts them in a band above the prompt, as a bar per window with the percent used and the time until it resets. The figures come from your subscription's rate-limit headers, so they appear after the session's first response and only on a subscription.

What does the prompt-cache hit rate mean?

It's the last turn's cache reads over all of its input (uncached tokens, cache reads and cache writes), summed over the turn's requests. Usage Band turns it red when it falls under 50%.

How do I change the band's icons?

Set USAGE_BAND_ICONS in your shell profile to auto, nerd, unicode or ascii, for example export USAGE_BAND_ICONS=unicode. Run /usage-band-preview to see every terminal style side by side.

Does Usage Band read files or contact the internet?

No. Its README says it reads the session's usage figures and the TERM_PROGRAM and USAGE_BAND_ICONS environment variables, adds /usage-band-preview, and draws the band. statuslin.es's checks found no file writes, programs or internet access.

More like this

Token Weather Usage in Claude Desktop

One line above the prompt: context tokens with their weather, a bar per recent prompt, your 5-hour and 7-day limits against the time elapsed, the prompt cache with its time left, the session cost with the last prompt's share in dollars and in points of the 5-hour limit, and the subagents running. Labels in English, French or Russian. After Token Weather (Anthropic, Apache-2.0) and the ideas of usage-meter (HolyGrail) and prompt-cache-control (Daniel San).

Deck in Claude Desktop

A cockpit for Claude Code: plan bars and subagent strips, context, usage limits with reset countdowns and burn rates, spend, the model route and a pet. Six bar styles, three collapsed looks. CLI and Desktop.

Flightdeck in Claude Desktop

Flightdeck: a live agent dashboard for Claude Code. Main model vitals, an on-call architect, every permission check, subagent cards and swimlanes, a turn receipt and a session log, all from real session events

▀▄ ▄▀ [-] ▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▄ ▄▀ ▀▀▀▄▄▄ ▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀ ctx 22% [ Pet ♥ ] [ ⚙ ] [ ↻ Adventurer ] [ Hide ]

A little pixel cat that wanders above the Claude Code prompt, watches your usage limits and announces when work finishes; or switch packs for an adventurer who mines, chops trees and fights zombies

app · main · Opus-4.8 · effort high · ctx 22% · 5h 26% ↻2h6m · 7d 7% ↻2d0h

One-line status bar showing your directory, git branch (with a * when dirty), model, live effort level, context-window usage, and 5-hour/7-day rate-limit usage.

Opus 4.8 [high] ~/app main 16:20:55 | ⛁ ██░░░░░░░░ 22% | 5h ●◔○○○ 26% ↻2h7m | 7d ◔○○○○○○ 7% ↻2d1h │ $0.41 ⏱ 10m

Two-line status with a block context bar and quarter-step dot meters (◔◑◕●) for the 5-hour and weekly limits (fill shows usage, color shows whether you are ahead of or behind pace), plus model, effort, git and cost. Needs no jq.

████▊░░░░░░░░░░░░░░░░░ 22% of 200K · GOOD │ ↓ 44.0K ↑ 1.4K │ $0.41 │ ⏱ 10m 12s │ +128/-34 │ 5h 26% ↻2h06m │ 7d 7% ↻2d0h │ ◆ Opus 5.5 · main · 03:53

One-line adaptation of @kyleledbetter's Dreambase Panel: a context bar with status word, token/cost/duration/lines-changed stats, and model + git branch + clock, all on a single line in a terracotta Claude-brand palette.

Opus 4.8 high ✦ │ ctx 22% │ app (main) │ PR #1287 ● │ $0.41 · 10m +128 -34 Session ● ● ● ● ● ● ● ● ○ ○ ○ 74% left Resets in 2h 6m Weekly ● ● ● ● ● ● ● ● ● ● ○ 93% left Resets in 2d 0h Fable ● ● ● ● ● ● ● ● ● ○ ○ 85% left Resets in 2d 0h ◐ Read:index.ts ✓ Read×1 ✓ Bash×1 ✓ Edit×1 ✓ Grep×1 ◐ code-reviewer Review the change for regressions

A header with model, context and burn rate per hour, then live tool and agent activity parsed from the session transcript.