claude-code-usage-bar

README

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 Code tells you almost nothing about where you stand against your rate limits. cs puts the numbers that matter on one quiet line at the bottom of your terminal: how much you have left, and when it resets.

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) / ⑂ main checkout (3)), project name, branch, session +/− lines, duration, version

• Official numbers — the same 5h / 7d limits Claude Code enforces, not a local guess.
• Prompt-cache countdown — ❄ 4m23s tells you when the next turn pays full price.
• Two surfaces — the terminal statusLine, or a floating HUD for the Claude desktop app (macOS).
• Fast — native cache reader plus a background daemon; well under 1% CPU at one refresh per second.
• Opt-in extras — cost, relay balance, git ahead/behind, activity, IP checks, IELTS writing-coach progress.

Install

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

A prebuilt binary for macOS Apple Silicon and Linux x86_64 — no Python needed. On macOS it also registers the desktop HUD when the Claude app is installed. Other platforms fall back to pip.

Windows (PowerShell, no admin):

irm https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.ps1 | iex

pip / uv:

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. cs upgrades itself every 6 hours; if you're stuck on an old version, run cs upgrade or re-run the one-liner (why). More paths in the install guide.

Customize

Three looks — aurora with block bars (default), aurora with a thin line, and classic:

cs theme                         # pick one with a live preview (↑/↓, Enter)
cs config set bar_glyph thin     # thin ━ line instead of ■ blocks (default)
cs config set style classic      # the original battery-bar look
cs preview                       # all three looks, with your real numbers
cs config show                   # every key, and which ones you changed

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 usage. The one-liner installs it; for pip use pip install 'claude-statusbar[hud]' && cs hud install.

Documentation

Guide	What's inside
Install	Binary, PyPI, skill-only, plugin, Codex bridge
What it shows	Every segment, icon and color threshold
Looks	The three looks, slash commands
Configuration	All keys, env vars, JSON output
Desktop HUD	The macOS floating panel
Fast mode (daemon)	Daemon, auto-start, refresh and caching
No-quota mode	Relay / Bedrock / Vertex layout and balance
Cache countdown	How ❄ 4m23s is computed
Troubleshooting	cs doctor, IP checks, upgrading

Want charts and weekly cost breakdowns instead of one line? Run ccusage or Claude Code Usage Monitor in a side pane — they coexist with cs.

Contributing

PRs welcome — see CONTRIBUTING.md (setup, tests, architecture, release flow) and SECURITY.md. Changes per version: CHANGELOG.md.

Acknowledgments

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

---

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

Author

Built by 郭立 (Guo Li / leeguoo) — leeguoo.com · GitHub · X · more tools in the *-use family.