claude-quota-bar

Fast Rust statusline for Claude Code. Battery-style 5-hour / 7-day quota bars, context-window indicator, session active time, and dir:branch *N — at ~2.5ms cold start and a ~0.5MB binary.

5h[███42%░░░░]⏰26m | 7d[███35%░░░░]⏰8d3h | Opus 4.7(71.0k/1.0M) | ⏳2h15m | proj:main *3

Requires Claude Code ≥ 2.1.132 (where context_window.total_input_tokens reports the current context occupancy rather than a cumulative session total).

Why this and not the Python ones

• Speed. Claude Code renders statusLine on every prompt. Python is ~50ms cold start; this is ~2.5ms. Subjective UX difference is real.
• No runtime deps. One stripped binary; no claude-monitor, no pip.
• Focused. Shows what you need to make in-session decisions (how much quota is left, when does it reset) — not what you already did (cost, lines changed).

Install

# npm (recommended — works on any platform with Node ≥ 16)
npm install -g claude-quota-bar

# cargo (compiles from source — npm ships a prebuilt binary, so it's faster)
cargo install claude-quota-bar

# pre-built binary (macOS arm64 example)
curl -L https://github.com/xrf9268-hue/claude-quota-bar/releases/latest/download/claude-quota-bar-aarch64-apple-darwin.tar.gz | tar xz
mv claude-quota-bar /usr/local/bin/

Then wire it into Claude Code (~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "claude-quota-bar",
    "padding": 0
  }
}

Segments

Default layout: 5h,7d,model,session,dir.

| Segment | Source | What it shows | |---------|--------|---------------| | 5h | rate_limits.five_hour | Battery bar with % inside, plus ⏰ countdown to reset | | 7d | rate_limits.seven_day | Same, weekly window | | model | model + context_window | Opus 4.7(71.0k/1.0M) — model + ctx tokens used / window | | session | own ledger per session_id | ⏳2h15m — active time this session, idle gaps excluded | | dir | workspace.current_dir + git | proj:main *3 ↑1 ↓2 — dir, branch, dirty count, ahead/behind |

How session counts time

Claude Code's own cost.total_duration_ms is wall-clock since process start: it keeps growing while you're at lunch and resets to zero on --resume. Instead, this bar keeps its own per-session ledger (~/.cache/claude-quota-bar/sessions/<session_id>.json), treating each statusline render as a heartbeat:

• Gaps ≤ 15 minutes between renders count as active time (think-time, long builds). Longer gaps are interruptions and are dropped.
• A render only accrues when the payload shows progress (total_api_duration_ms changed), so statusLine.refreshInterval users don't accumulate idle wall-clock.
• --resume / --continue keep their session_id, so the counter picks up where it left off. --fork-session / /branch get a fresh counter.

Ledgers untouched for 7 days are swept automatically.

When Anthropic hasn't yet shipped rate_limits (first few renders of a fresh session), the bar displays --%. A cross-session cache at ~/.cache/claude-quota-bar/last_stdin.json restores the most recent values, so opening a new terminal doesn't blank the bar.

Configuration

Configured via environment variables:

| Variable | Default | Meaning | |----------|---------|---------| | STATUSLINE_LAYOUT | 5h,7d,model,session,dir | Comma-separated segment names (order matters) | | NO_COLOR | unset | If set, strips all ANSI — falls back to █/░ glyphs |

Severity thresholds (green / yellow / red) flip at 30% and 70% quota used.

Development

Requires Rust ≥ 1.85 (Edition 2024).

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

# Manual visual test
cat <<EOF | cargo run --release
{
  "model": {"display_name": "Opus 4.7"},
  "workspace": {"current_dir": "/tmp"},
  "rate_limits": {"five_hour": {"used_percentage": 42, "resets_at": $(($(date +%s) + 26*60))}}
}
EOF

Releases are fully automated (release-plz Release PR → crates.io + npm + GitHub Release via OIDC). See docs/RELEASING.md.

License

MIT — see LICENSE.

Acknowledgements

Visual inspired by leeguooooo/claude-code-usage-bar. Release / NPM publishing pattern adapted from Haleclipse/CCometixLine.