Claude Status Bar

Your Claude Code usage, at a glance. 5h / 7d rate-limit bars, reset countdowns, model, context window, and prompt-cache freshness — inline in Claude Code's status line, or a floating HUD on the desktop app.

English · 简体中文 · Install · Documentation

claude-statusbar live demo

[!IMPORTANT] macOS standalone users should upgrade to v3.32.5 now. Older onefile releases could leave a new ~11 MB PyInstaller _MEI* runtime directory on every one-second refresh that was killed during startup. Re-running the installer switches to an onedir bundle and safely removes inactive leftovers: curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bash

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:

default status bar

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	git worktree marker (`⑂ name (3)` / `⑂ trunk (3)` with the repo's worktree total, its own hue, leads the line), 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

The render path is hot (up to 60×/min 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 · GitHub Releases.

Acknowledgments

@marcwimmer — original show_cache_age widget (#9)
claude-monitor — token-usage analysis library used as the optional fast-path data source

Star history

_{Static snapshot taken at v3.3.x; click for the live chart.}

_{MIT © leeguooooo · Built for people who live in Claude Code.}

Metadata

Release files for claude-statusbar 3.41.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for claude-statusbar 3.41.0
File	Size	Uploaded
claude_statusbar-3.41.0.tar.gz	313.1 kB	Sep 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for claude-statusbar 3.41.0
File	Interpreter	ABI	Platform	Reset
claude_statusbar-3.41.0-py3-none-any.whl 195.1 kB Sep 1, 2026	Python 3	none	any	Details

Total release size: 508.1 kB

Release files / claude_statusbar-3.41.0.tar.gz

Download URL	claude_statusbar-3.41.0.tar.gz
Size	313.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`5fe3a5ab083ca248bebd5126127e657500ca7cb66ff4b363a0050bc343f63f4b`
BLAKE2b-256 checksum How to use checksums	`3364314cabbc482baa8328c9db77c0ba95bfd5ad144fe54535ac5149e91357c2`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.5`

Release files / claude_statusbar-3.41.0-py3-none-any.whl

Download URL	claude_statusbar-3.41.0-py3-none-any.whl
Size	195.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8c23a6c6f2613a01cfc02fa0e9563c4abc6818670c39de504600bfa778d58051`
BLAKE2b-256 checksum How to use checksums	`7db9e9ca11d88bb8dae151fed511fc53ee4c58da48da43fcec046c6133e3dc67`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.5`