Claude Code tells you almost nothing about where you stand against your rate limits. claude-statusbar puts the numbers that matter on one quiet line at the bottom of your terminal — so you never switch context to a separate window to answer "how much have I got left, and when does it reset?"

Features

• Official 5h / 7d usage — the same rate-limit numbers Claude Code enforces, with reset countdowns and end-of-window projections (→NN%), not a local guess.
• Model & context window — current model and how full the context is (Opus 4.8 · 350k/1M).
• Prompt-cache countdown — see how long your cache stays warm (cache 4m23s) so you know when the next turn pays full price.
• Cost & balance — optional per-session cost, or live relay/API balance in no-quota setups.
• Two surfaces — inline statusLine in the terminal, or an always-on-top floating HUD for the Claude desktop app (macOS).
• 3 styles × 9 themes — switch the whole look with one command: battery-bar, capsule, or hairline.
• Fast by design — an optional daemon renders in well under 1% CPU even at a 1-second refresh.
• More when you want it — git branch & diff stats, session activity, AgentParty/Codex presence, IELTS writing-coach progress — each opt-in.
• Zero-dependency install — a single prebuilt binary (no Python needed) or a pip package. Auto-updates.

Install

Claude Code (terminal)

One line — no Python, no pip. Downloads a prebuilt standalone binary for your platform (macOS Apple Silicon, Linux x86_64) and wires up the status line:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bash

_{Security-conscious? Download and read it first — the header lists exactly what it touches. On platforms without a prebuilt binary it falls back to pip.}

On macOS this one line does everything — it wires the terminal statusLine and, if the Claude desktop app is installed, registers the floating desktop HUD to auto-start on login. The macOS binary bundles the HUD, so there's no separate pip install '[hud]' and no extra config.

Prefer pip / uv, or want the desktop HUD extra? Install the Python package:

pip install claude-statusbar     # or: uv tool install / pipx install
cs --setup                       # wires the statusLine hook + installs the skill

Restart Claude Code and the bar appears at the bottom. Other paths (skill-only, plugin marketplace, Codex/AgentParty bridge) are in the install guide.

Deep dive: Is that cache 4m23s line actually accurate? — how the prompt-cache countdown is computed

Claude desktop app (macOS) — cs hud

The desktop app has no status line, so cs hud adds an always-on-top floating panel with the same official 5h / 7d usage (sampled by the desktop app itself, not an estimate) and your active AgentParty channels.

If you used the curl … install.sh | bash one-liner above, the HUD is already installed — the macOS binary bundles it and the installer auto-registers it when the desktop app is present. The commands below are only for a manual/pip setup:

pip install 'claude-statusbar[hud]'   # adds PyObjC (macOS GUI deps)
cs hud install                        # launchd: auto-start on login + keep-alive

Collapsed pill → click to expand → drag anywhere; it hides when the desktop app isn't open. Full details in the Desktop HUD guide.

What it shows

The default bar — classic style, graphite theme:

At a full refresh it can render up to three lines, each segment optional:

Line	Segments
Usage	5h / 7d rate-limit bars, reset countdowns, end-of-window projections (→NN%), model & context window, prompt-cache countdown, optional session cost or relay balance
Project	project name, git branch, session +/− lines, duration, version
Mode	session effort / thinking / fast / style

Every icon, color threshold, and toggle is documented in the segment reference. Nine themes and three styles are in styles & themes.

Documentation

Guide	What's inside
Install	Binary, PyPI, one-shot installer, skill-only, plugin, Codex bridge
What it shows	Full per-segment reference table
Styles & themes	3 styles × 9 themes, previews, slash commands
Configuration	Config file, all show_* keys, env vars, JSON output, CLI cheatsheet
Desktop HUD (cs hud)	macOS floating panel for the Claude desktop app
Fast mode (daemon)	Sub-1% CPU daemon, launchd / systemd auto-start
No-quota mode	Relay / Bedrock / Vertex layout, context battery, balance
AgentParty / Codex bridge	Local workspace-presence line
Cache countdown	Data source + how cache 4m23s is computed
Troubleshooting	cs doctor, common problems, upgrading

Comparison

There are a few good Claude Code usage monitors. They solve overlapping but distinct problems — pick the one that matches where you want the information.

Tool	Lives in	Optimized for
claude-statusbar (cs)	Claude Code's statusLine (one line at the bottom)	Glanceable while you work; zero context-switching
ccusage	Standalone TUI in a separate terminal window	Long-form usage analytics, cost breakdowns over weeks
Claude Code Usage Monitor	Standalone TUI with predictive burn-rate	Real-time burn-rate forecast for paid plans

cs is intentionally one line of color and one decision per second. If you want a dashboard with charts, daily/weekly aggregates, and burn-rate prediction, run a TUI in a side pane. The two coexist nicely.

Integrations

prompt-language-coach — install the plugin to track IELTS band progress. The bar then shows your writing level and trend automatically (no config; appears when ~/.claude/language-progress.json exists):

... | Opus 4.8(350k/1M) | EN:6.0↑ JA:5.0→

↑ improved · ↓ dropped · → no change since last session.

Contributing

PRs welcome. The full contributor guide — local setup, test commands, architecture map, coding conventions, release flow — is in CONTRIBUTING.md. Security issues: SECURITY.md.

git clone https://github.com/leeguooooo/claude-code-usage-bar
cd claude-code-usage-bar
uv sync
PYTHONPATH=src uv run pytest tests/   # 900+ tests, ~3s
``$

\text{The} \text{render} \text{path} \text{is} \text{hot} (\text{up} \text{to} 60 \times /\text{min} \text{at} $refreshInterval: 1`) — `tests/test_import_perf.py`
pins which modules can't be imported on the fast path. Read CONTRIBUTING.md before adding
dependencies.

Every version's changes: **[CHANGELOG.md](CHANGELOG.md)** · [GitHub Releases](https://github.com/leeguooooo/claude-code-usage-bar/releases).

## Acknowledgments

- [@marcwimmer](https://github.com/marcwimmer) — original `show_cache_age` widget ([#9](https://github.com/leeguooooo/claude-code-usage-bar/pull/9))
- [claude-monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) — token-usage analysis library used as the optional fast-path data source

<a href="https://github.com/leeguooooo/claude-code-usage-bar/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=leeguooooo/claude-code-usage-bar" alt="Contributors" />
</a>

## Star history

<a href="https://star-history.com/#leeguooooo/claude-code-usage-bar&Date">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/star-history-dark.svg">
    <img alt="Star history" src="docs/images/star-history.svg">
  </picture>
</a>

<sub>Static snapshot taken at v3.3.x; <a href="https://star-history.com/#leeguooooo/claude-code-usage-bar&Date">click for the live chart</a>.</sub>

---

<div align="center">
<sub>MIT © <a href="https://github.com/leeguooooo">leeguooooo</a> · Built for people who live in Claude Code.</sub>
</div>