
claude-statusbar
Lightweight Claude Code status-line monitor: 5h/7d rate-limit usage, reset timers, projection/forecast, model + context, prompt-cache countdown, optional cost/balance, project/branch/session/activity lines. 3 styles x 9 themes. Install the `cs` CLI with the GitHub Release installer.
- GitHub stars
- 393
Install
/plugin install claude-statusbar@claude-statusbarRun it inside Claude Code after adding the marketplace with /plugin marketplace add leeguooooo/claude-code-usage-bar.
Contents
Discovered from sourceSkills 1
claude-statusbar control skill
Use this skill any time the user wants to inspect, change, customize, or
diagnose the cs status bar. Replaces the older individual slash commands
(/statusbar, /statusbar-style, /statusbar-preview,
/statusbar-doctor, /statusbar-reset) — they still work but this skill
covers all of them with conversational intent.
Decision tree
Match the user's intent to the right cs command. Run it via Bash, then
give a short confirmation (one line, no lecture).
| User intent | Command |
|---|---|
| Inspect current config | cs config show |
| Pick a look interactively (user is in their own terminal) | tell them to run cs theme — ↑/↓ with live previews, Enter applies; from Claude Code use the config commands below instead |
Hide the ✦ New looks available line without picking | cs config set looks_seen 1 (it goes away for good once cs theme has been opened) |
| List styles | cs styles |
| Aurora with ■ block bars (default look) | cs config set style aurora + cs config set bar_glyph block |
| Aurora with a thin ━ line ("细一点") | cs config set style aurora + cs config set bar_glyph thin |
| Original battery-bar look | cs config set style classic |
| Change density | cs config set density <compact|regular|cozy> |
| Show the three looks side by side | cs preview |
| Diagnose problem | cs doctor |
| Return one key to its default | cs config unset <key> (the config stores only what you changed) |
| Wipe config | cs config reset |
| Install / first-time setup | cs --setup |
| Upgrade / update to latest version | cs upgrade — NEVER guess uv tool install / pip install -U / pipx upgrade: it detects the install channel that is actually running cs and picks the right one (many users don't have uv at all) |
| Turn auto-upgrade off | cs config set auto_upgrade false (default true — a detached once-a-day check upgrades every install channel, binaries included; CLAUDE_STATUSBAR_NO_UPDATE=1 also wins) |
| Enable fast mode (daemon) | cs --setup --fast |
| Disable fast mode | cs daemon stop then re-run cs --setup |
| Toggle session cost display | cs config set show_cost true|false |
| Toggle prompt-cache countdown | cs config set show_cache_age true|false |
| Toggle project + branch 2nd line | cs config set show_project_branch true|false (default true) |
Toggle the ocs line (ocs boss · claude-7d5a5d07 · ✉3 · lan win: address, unread DMs, LAN bridge; own line; auto-hidden without ocs ≥ 0.5.0, ✉ needs an ocs whose inbox accepts --session) | cs config set show_ocs true|false (default true) |
Toggle todo progress (▸ task 3/7, 3rd line) | cs config set show_todos true|false (default true) |
Toggle active-tool indicator ◐ (3rd line) | cs config set show_tools true|false |
Toggle completed-tool rollup ✓ name×N (3rd line) | cs config set show_tool_rollup true|false (default off — volume tally) |
| Toggle running-subagent bottom line(s) | cs config set show_agents true|false (default off — Claude Code shows background agents natively) |
Toggle session duration ⏱ (on identity line) | cs config set show_duration true|false |
Toggle lines added/removed +/- (on identity line) | cs config set show_lines true|false |
Toggle git ahead/behind ↑↓ (on identity line) | cs config set show_ahead_behind true|false |
Toggle the bar_shimmer twinkling starfield (experimental, classic only) | cs config set bar_shimmer true|false (default off) |
| Toggle the rate-limit forecast (→NN% projected use / ⚠eta warning) | cs config set show_forecast true|false (default on) |
Toggle the faint version + update hint at the identity-line end (· vX.Y.Z ↑new) | cs config set show_version true|false (default on) |
| Toggle the ⚙ session-mode line (effort/thinking/fast/output-style) | cs config set show_mode true|false (default off) |
| Toggle the per-effort colour gradient on the mode line | cs config set mode_gradient true|false (default on) |
| Hide weekly bar | cs config set show_weekly false |
| Narrow panes: stack the quota bars one per line instead of dropping forecast/projection | cs config set narrow_layout stack|drop (default drop) |
| Set warning threshold | cs config set warning_threshold <0-100> |
| Set critical threshold | cs config set critical_threshold <0-100> |
| Force / disable no-quota (API) mode | cs config set api_mode <auto|on|off> |
| Show working directory | cs config set show_cwd true|false + cs config set cwd_style <basename|full> |
| Relay balance fuel gauge | cs config set show_balance true|false + cs config set balance_bar true|false (no-quota mode only; auto-hidden when the relay has no balance API) |
Exit-IP purity segment — temporarily disabled for privacy; show_ip_risk is ignored and no IP lookups are made | — |
| Local custom-endpoint notice (no watermark or account prediction) | cs config set show_fp_risk true|false |
Window-end projection →NN% | cs config set show_projection true|false |
Worktree count glyph (worktree (🌳3)) | cs config set worktree_glyph ⑂ (default 🌳; any 1-2 cell symbol) |
| Worktree marker color | cs config set color_worktree "#bd93f9" (empty string restores the theme's hue) |
No-quota mode (third-party relay / Bedrock / Vertex)
When Claude Code points at a third-party relay (ANTHROPIC_BASE_URL ≠
api.anthropic.com) or a cloud backend (CLAUDE_CODE_USE_BEDROCK /
CLAUDE_CODE_USE_VERTEX), the official 5h/7d quota doesn't exist. cs detects
this and switches to a no-quota layout: the two quota battery bars are
dropped and the context window is promoted to its own ctx[…] battery bar
(green→yellow→red on 70/85% used), followed by the model name + the usual
live-activity tail. This mirrors claude-hud's behavior and is what to reach for
when a user says "用 API 就没状态了 / 连上下文都没了".
- Detection is automatic (
api_mode = auto, the default). A transcript-based heuristic also catches relays whose env var didn't reach the statusLine subprocess (an assistant turn exists yet quota never arrived → no-quota). - Force it on a setup where auto-detect misses:
cs config set api_mode on(or per-shellCS_API_MODE=on). Force the official layout back withapi_mode off.CS_API_MODEenv wins over the saved config. - Works under both the inline and fast-mode (daemon) render paths.
Per-severity color overrides (v3.4.1+)
The user can override the three severity colors independently of theme:
cs config set color_ok "#4ec85b" # calm / safe
cs config set color_warn "#e8b260" # warning
cs config set color_hot "#e87474" # critical
cs config set color_ok "" # clear back to theme default
Accepts #rrggbb, #rgb, or bare rrggbb. The override layers on top of
the graphite theme.
When user says "make 余量颜色 / safe color / green sharper", "warning 偏淡", "critical too red" — go to the override.
Looks and themes
There are three looks — aurora ■ (default), aurora ━, classic — and one
theme, graphite. The other styles (capsule, hairline) and eight themes were
removed in 3.50.0; old configs fall back to the defaults. If a user asks for
a different palette, reach for the color_* overrides above.
Render anatomy (so you can explain what you're changing)
5h[██16% ░░░]⏰2h27m | 7d[██32% ░░]⏰4d05h | Opus 4.7(280k/1M) | $ 1.42 | cache 4m23s
└─ 5h ─────┘└──5h──┘ └─ 7d ──┘ └─7d─┘ └────context───────┘ └cost┘ └─cache─┘
Every numeric segment colors itself by its own severity (since v3.4):
- 5h →
theme.s_*chosen frommsgs_pct - 7d →
theme.s_*chosen fromweekly_pct - model+context →
theme.s_*chosen fromctx_used_pct(None → neutral) - cache → its own string-age severity (COLD → red, <1m → yellow, else green)
[ ],( ),|→theme.mute(recede behind data)
Common diagnostic flows
"Status bar isn't showing" → cs doctor. It self-checks:
- Claude Code's
~/.claude/settings.jsonhas thestatusLineblock - the
csbinary is on PATH - whether the daemon is alive (if fast-mode configured)
- whether the cache files are stale
"refreshInterval too high" → cs doctor will recommend cs --setup --fast
when it sees refreshInterval ≤ 2s on the inline command. Fast mode drops
1Hz CPU from ~6% to ~2%.
"Look won't change after cs config set …" → check the user
isn't on a Claude Code session that read settings.json at start. Ask
them to send a new prompt; the next render picks up the change.
Don't
- Don't lecture about ANSI codes or terminal compatibility unless asked.
- Don't suggest editing
~/.claude/claude-statusbar.jsonby hand. Usecs config set <key> <value>. - To tune one color use the
color_ok / color_warn / color_hotoverrides. - Don't run destructive commands (
cs config reset,cs daemon stop) without confirming with the user.
Style of response
Be terse. Run the command, paste the one-line confirmation, point at the next step if relevant. The status bar is on screen — they can see the result immediately, no need to describe it.
Commands 5
Status Bar — doctor
Run:
cs doctor
The output covers:
- Whether
csis on PATH and where it resolves to - Version + Python interpreter
- Whether
~/.claude/settings.jsonhas our statusLine entry (and whether something else is occupying it) - Last
last_stdin.jsoncache age (i.e. is Claude Code actually pushing data) - Terminal size and
TERM - Current resolved
style/theme/show_*toggles - Number of
/statusbar*slash commands installed
Show the user the full output as-is. If anything is flagged with ✗, point at that line specifically and propose the obvious next step (cs --setup to create the statusLine entry, cs upgrade to upgrade — never a raw pip/uv command, cs upgrade picks the channel the install actually uses, etc.). Don't editorialize beyond what the output already says.
Status Bar — preview the looks
Run:
cs preview
This renders the three looks — aurora with ■ blocks (default), aurora with a thin ━ line, and classic — with the user's real numbers from ~/.cache/claude-statusbar/last_stdin.json.
After running it, ask the user which look they want and offer to switch with /statusbar-style block|thin|classic. Do not pick for them.
Status Bar — reset
Run:
cs config reset
This deletes ~/.claude/claude-statusbar.json so every key falls back to its built-in default (style=classic, theme=graphite, density=regular, all show_* toggles at their defaults). Idempotent — running it twice is harmless.
Then confirm with cs config show and tell the user the original look is restored.
Status Bar — set look
Argument: $ARGUMENTS
There are three looks:
| Look | Commands |
|---|---|
block — aurora with ■ bars (default) | cs config set style aurora && cs config set bar_glyph block |
thin — aurora with a thin ━ line | cs config set style aurora && cs config set bar_glyph thin |
classic — the original battery bar | cs config set style classic |
Steps:
- If
$ARGUMENTSis empty, runcs previewto show all three and ask the user to pick. - Otherwise run the commands for that look from the table above.
- Render a one-line preview from cached real data so the user sees the result:
If the cache file does not exist, skip this step — no Claude Code session has populated it yet.cat ~/.cache/claude-statusbar/last_stdin.json | cs - Tell the user the change is persistent for all future Claude Code sessions.
If $ARGUMENTS is not block, thin or classic, list the three looks and ask which one they meant.
Status Bar — overview
Run these two commands and present the output to the user, then briefly tell them how to switch:
cs config show
cs styles
Then point out:
- Switch look:
/statusbar-style block|thin|classic - See all three side-by-side:
/statusbar-preview - Show this session's $ cost on the bar:
cs config set show_cost true - One-shot trial without saving:
cs --style classic - Wipe everything back to defaults:
/statusbar-reset - Diagnose problems (paste in any bug report):
/statusbar-doctor
Keep the response short. Don't lecture about ANSI colors or terminal compatibility.
Sponsors
Details
- Marketplace
- leeguooooo/claude-code-usage-bar
- Category
- Monitoring