Claude Status Bar
Lightweight Claude Code status-line monitor. Shows your 5h / 7d rate-limit usage, reset timers, current model, context window, prompt-cache freshness, and (optionally) session cost — in a single compact line driven by Claude Code's statusLine hook.
5h[ 27% ]⏰1h28m →42% | 7d[ 79% ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s
3 styles × 9 themes, configurable in one command. Auto-updates from PyPI. Just run pip install claude-statusbar && cs --setup and restart Claude Code.
Contents
- Latest release
- What it shows
- Install
- Styles & themes
- Configuration
- Fast mode (daemon)
- Slash commands
cs doctor— self-diagnostic- Usage cheatsheet
- Environment variables
- How the cache countdown works
- Troubleshooting
- Upgrading
- Comparison with alternatives
- Integrations
- Contributing
- Acknowledgments
- Contributors
Latest release
v3.11.0 (2026-06-02) — rate-limit projections (show_projection, default on): after each ⏰<reset> timer the bar shows →NN%, your expected end-of-window usage. The 5h model blends recent pace, whole-window average, and a local baseline; the 7d model integrates learned coarse rhythm buckets (work hours, non-work hours, night, weekend) so a busy first day is not blindly extrapolated across the whole week. show_forecast remains the separate ⚠<eta> warning chip for imminent cap hits. Plus: context_window.used_percentage = null handled gracefully, and the daemon only renders windows active in the last 10s.
v3.10.0 (2026-06-02) — live-activity line (in-progress todo, active tool, completed-tool rollup), git ahead/behind + session duration/lines on the project line, running-subagent lines, an opt-in bar_shimmer starfield on the battery bars, and a self-hosted plugin marketplace. Plus: auto-update now actually runs in daemon mode (detached, non-blocking), and the cache countdown is per-session-correct. All new segments are opt-in except the todo line.
v3.6.0 (2026-05-08) — cs --setup now defaults to daemon (fast) mode: under 1% CPU continuously instead of ~3% inline. Pass --inline to opt back. Also: py3.9 compat fixes, GitHub Actions CI, animated hero GIF.
v3.5.1 — npx skills add install path, show_cache_age on by default.
v3.5.0 — consolidated claude-statusbar skill: say "switch theme to nord" / "余量颜色改成 #4ec85b" and Claude Code routes it to the right cs command.
v3.4 — per-segment color management (each metric colors itself by its own severity), classic style finally respects themes, two new themes (catppuccin-mocha, tokyo-night), per-severity color overrides via cs config set color_ok|warn|hot.
v3.2 — daemon fast-mode (now the default in v3.6.0) for ~5× lower CPU at refreshInterval=1.
📋 Full changelog: CHANGELOG.md · GitHub Releases — every version's changes, also linked from the PyPI page.
What it shows
5h[ 27% ]⏰1h28m →42% | 7d[ 79% ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s | $ 1.42
⤷ claude-code-usage-bar ⎇ main● · +182 -47 · ⏱ 12m · v3.12.0
⚙ effort:high · think:on · fast:off · style:default
| Segment | Meaning |
|---|---|
5h[27%] |
5-hour rate-limit usage (rolling window from Anthropic API headers) |
⏰1h28m |
Time until the 5-hour window resets |
7d[79%] |
7-day rate-limit usage |
⏰11h28m |
Time until the 7-day window resets |
→42% / →88% |
Projected end-of-window usage at your current rhythm (show_projection, on by default). Muted < 80%, yellow ≥ 80%, red ≥ 100%. The 5h model blends recent pace + whole-window average + a local baseline; the 7d model integrates learned day/night/weekend buckets so a busy first day isn't extrapolated across the week. |
⚠~18m |
At-risk warning chip — only when a window is projected to hit 100% and the cap is imminent (≤ 1 h). Separate from the projection (show_forecast, on by default). |
Opus 4.8(350.0k/1.0M) |
Model name + current context window usage |
cache 4m23s / cache COLD |
Countdown to prompt-cache expiry — the TTL (5min vs 1h) is auto-detected from the transcript, so it's right on a subscription (1h) or an API key (5min). Green when comfortable, yellow under 1min, red on COLD. Cache hits consume ~10× less rate-limit quota — for subscribers, letting it go COLD eats your 5h / 7d windows ~10× faster. Enabled by default; disable with cs config set show_cache_age false |
$ 1.42 |
Session cost in USD as Claude Code reports it. For Pro/Max subscribers this is the API-equivalent value of your usage (i.e. what it would cost on the API), not money owed. Useful as an ROI signal. Opt-in: cs config set show_cost true |
⤷ <project> ⎇ <branch>●↑2↓1 · +182 -47 · ⏱ 12m |
Second-line identity + session line. Project comes from Claude Code's workspace.repo.name (cwd-basename fallback); branch reads .git/HEAD directly; the ● dirty marker is refreshed by a background helper, cached 5 s. Enabled by default — turn off with cs config set show_project_branch false. +added -removed session lines (show_lines, +green/−red) also show by default. Opt-in extras live here too: ↑2↓1 commits ahead/behind upstream (show_ahead_behind, reuses the dirty-state git status — no extra spawn) and session ⏱ duration (show_duration). |
▸ <task> (3/7) · ◐ Edit auth.py · ✓ Read×3 |
Third "activity" line — what's happening right now, parsed from the transcript: the in-progress todo + done/total (show_todos, on by default), the active tool (◐, show_tools), and an optional completed-tool rollup (✓ name×N, show_tool_rollup, default off). Omitted entirely when nothing is active. |
◐ explore[haiku] <task> 2m15s |
Bottom line(s) — one per running subagent (show_agents, opt-in, default off). Note: Claude Code already shows background agents in its own native panel, so this largely duplicates that; off by default for that reason. |
⚙ effort:high · think:on · fast:off · style:default |
Session-mode line (show_mode, on by default) — how this turn is configured, from stdin. Tinted with a per-effort static gradient (mode_gradient) so the level reads at a glance. |
📚 EN:6.0↑ JA:5.0→ |
IELTS band progress (requires prompt-language-coach) |
Colors default to green / yellow / red at 30% and 70% — both thresholds configurable.
Install
Recommended: PyPI
pip install claude-statusbar # or: uv tool install claude-statusbar
# or: pipx install claude-statusbar
cs --setup # wires the statusLine hook + installs the skill
Restart Claude Code to see the bar. cs --setup writes the following into ~/.claude/settings.json (existing files are backed up first, other keys are preserved):
{
"statusLine": {
"type": "command",
"command": "cs render",
"refreshInterval": 1
}
}
Since v3.6.0 cs --setup defaults to daemon mode (cs render + refreshInterval: 1), which keeps CPU under 1% continuously while ticking the cache-age countdown every second. The daemon is auto-started by cs --setup and lazy-respawns on cs render if it ever dies, so you never see a frozen bar. Opt out with cs --setup --inline (writes plain cs, ~3% CPU at 1Hz) or set refreshInterval to a higher value — cs --setup preserves any explicit value you've already chosen.
Alternative: one-shot installer (audit first, then run)
A bash helper is available if you'd rather not chain pip install + cs --setup manually. Please read it before running — it modifies ~/.claude/settings.json and (with your explicit [y/N] consent) ~/.bashrc / ~/.zshrc:
curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/web-install.sh -o /tmp/cs-install.sh
less /tmp/cs-install.sh # audit it
bash /tmp/cs-install.sh
Or, if you've already audited the script and trust this repo:
curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/web-install.sh | bash
The header of web-install.sh lists exactly what it touches.
Skill-only install (already have cs)
If you already have the cs binary installed (e.g. via pip install) and just want the conversational claude-statusbar skill so Claude Code routes natural-language requests like "switch theme to nord" or "余量颜色改成 #4ec85b" to the right cs command:
npx skills add leeguooooo/claude-code-usage-bar -g -y
This installs only the skill globally. It does not install cs itself — the skill's actions all call out to the cs CLI, so you still need one of the install paths above for the binary. Use this path whe