claude-code-usage-bar

Using Codex CLI? Try the sibling project Codex Statebar — the same status bar, built for Codex.

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) / worktree (🌳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.
• 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. 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 picks one with a live preview:

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 config set narrow_layout stack # stack quota bars in narrow panes
cs preview                       # all three looks, with your real numbers
cs config show                   # every key, and which ones you changed

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
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.

ccx — keeps a Claude Code session and a Codex thread linked on macOS. With the bar installed, ccx’s menu bar app warns you when Claude’s 5-hour window passes 90% or its weekly quota is exhausted, and offers to continue the newest session in Codex in one click (no config; ccx reads rate_limits from ~/.cache/claude-statusbar/last_stdin.json while it’s fresh).

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

---

Author

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