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

Run it inside Claude Code after adding the marketplace with /plugin marketplace add leeguooooo/claude-code-usage-bar.

Contents

Discovered from source

Skills 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 intentCommand
Inspect current configcs 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 pickingcs config set looks_seen 1 (it goes away for good once cs theme has been opened)
List stylescs 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 lookcs config set style classic
Change densitycs config set density <compact|regular|cozy>
Show the three looks side by sidecs preview
Diagnose problemcs doctor
Return one key to its defaultcs config unset <key> (the config stores only what you changed)
Wipe configcs config reset
Install / first-time setupcs --setup
Upgrade / update to latest versioncs 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 offcs 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 modecs daemon stop then re-run cs --setup
Toggle session cost displaycs config set show_cost true|false
Toggle prompt-cache countdowncs config set show_cache_age true|false
Toggle project + branch 2nd linecs 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 linecs config set mode_gradient true|false (default on)
Hide weekly barcs config set show_weekly false
Narrow panes: stack the quota bars one per line instead of dropping forecast/projectioncs config set narrow_layout stack|drop (default drop)
Set warning thresholdcs config set warning_threshold <0-100>
Set critical thresholdcs config set critical_threshold <0-100>
Force / disable no-quota (API) modecs config set api_mode <auto|on|off>
Show working directorycs config set show_cwd true|false + cs config set cwd_style <basename|full>
Relay balance fuel gaugecs 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 colorcs 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-shell CS_API_MODE=on). Force the official layout back with api_mode off. CS_API_MODE env 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 from msgs_pct
  • 7d → theme.s_* chosen from weekly_pct
  • model+context → theme.s_* chosen from ctx_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.json has the statusLine block
  • the cs binary 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.json by hand. Use cs config set <key> <value>.
  • To tune one color use the color_ok / color_warn / color_hot overrides.
  • 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 cs is on PATH and where it resolves to
  • Version + Python interpreter
  • Whether ~/.claude/settings.json has our statusLine entry (and whether something else is occupying it)
  • Last last_stdin.json cache 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:

LookCommands
block — aurora with ■ bars (default)cs config set style aurora && cs config set bar_glyph block
thin — aurora with a thin ━ linecs config set style aurora && cs config set bar_glyph thin
classic — the original battery barcs config set style classic

Steps:

  1. If $ARGUMENTS is empty, run cs preview to show all three and ask the user to pick.
  2. Otherwise run the commands for that look from the table above.
  3. Render a one-line preview from cached real data so the user sees the result:
    cat ~/.cache/claude-statusbar/last_stdin.json | cs
    
    If the cache file does not exist, skip this step — no Claude Code session has populated it yet.
  4. 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