Latest release

v3.5.1 (2026-05-08) — 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 for ~5× lower CPU at refreshInterval=1.

Full release notes in CHANGELOG.md.

What it shows

5h[   27%    ]⏰1h28m | 7d[   79%    ]⏰11h28m | Opus 4.7(350.0k/1.0M) | cache 4m23s | $ 1.42

| 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 | | Opus 4.7(350.0k/1.0M) | Model name + current context window usage | | cache 4m23s / cache COLD | Countdown to prompt-cache expiry (5min TTL by default). Green when comfortable, yellow under 1min, red on COLD. Cache hits consume ~10× less rate-limit quota — for subscribers this means COLD prompts eat 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 | | 📚 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

One-line install (recommended)

curl -fsSL "https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/web-install.sh?v=$(date +%s)" | bash

Installs the package, configures Claude Code's statusLine, sets up shell aliases. Restart Claude Code to see the bar.

Package managers

pip install claude-statusbar     # pip
uv tool install claude-statusbar # uv
pipx install claude-statusbar    # pipx

Then add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "cs",
    "refreshInterval": 1
  }
}

cs --setup writes refreshInterval: 1 by default so the cache-age countdown ticks visibly. At 1Hz, the inline cs command runs ~30ms per render (~3% CPU continuously); if that's a concern, run cs --setup --fast instead — daemon mode brings it under 1%. To go quieter, set refreshInterval to a higher value (30, 60) — cs --setup will preserve any explicit value you've already chosen.

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 when distributing into environments that already manage Python tooling separately, or when you want to update only the skill without touching cs.

cs --setup already installs the same skill alongside the slash commands, so most users don't need this path.

Styles & themes

The default style (classic) stays the same forever. Two alternative styles, plus a palette of seven themes, are opt-in.

cs --style capsule  --theme graphite   # try once
cs --style hairline --theme twilight   # try once
cs config set style capsule            # persist
cs config set theme twilight
cs styles                              # list available styles
cs themes                              # list available themes
cs preview                             # render every style × theme together

Styles

| Style | Look | |-------|------| | classic | Original [bar] \| pipe engineering layout. Default. | | capsule | Each metric is a colored pill — type badge (◷ 5H / ☷ 7D / ◆ / 📚) on the left, value, severity dot on the right. Subway-signage feel. | | hairline | One-character mini-bar (▁▃▆█) per metric, dashed ┊ separators, tight typography. Maximally calm. |

Capsule — graphite · twilight · nord · dracula · sakura · linen · mono · catppuccin-mocha · tokyo-night

Hairline — same theme set, different layout

Classic — kept identical to the pre-v2.7 look

Themes

| Theme | Vibe | |-------|------| | graphite | Cool dark graphite — default, fits most dark terminals | | twilight | Soft purples/roses — warm dark | | linen | Cream/beige — for light terminal themes | | nord | Nord palette — familiar Arctic blue | | dracula | Dracula palette — high-contrast purple/black | | sakura | Pink/cream — soft, light backgrounds | | mono | Pure grayscale — no chromatic distraction | | catppuccin-mocha | Catppuccin Mocha — community-favorite pastel, easy on long viewing | | tokyo-night | Tokyo Night — deeper neon-blue mood with restrained accents |

Style and theme are independent: any of the 3 styles × 9 themes = 27 combinations.

Slash commands inside Claude Code

After running cs --setup (or cs install-commands), the following slash commands work inside Claude Code:

| Slash command | What it does | |---------------|--------------| | /statusbar | Show current config + lists styles/themes | | /statusbar-preview | Render every style × theme combination using your real data | | /statusbar-style <name> | Switch style (classic / capsule / hairline) | | /statusbar-theme <name> | Switch theme (graphite / twilight / linen / nord / dracula / sakura / mono / catppuccin-mocha / tokyo-night) | | /statusbar-doctor | Self-diagnostic — paste output in bug reports | | /statusbar-reset | Wipe config back to defaults |

Configuration file

Persisted to ~/.claude/claude-statusbar.json:

{
  "style": "capsule",
  "theme": "twilight",
  "density": "regular",
  "auto_compact_width": 100,
  "show_weekly": true,
  "show_language": true,
  "show_cost": false,
  "show_cache_age": true
}

| Key | Values | What it does | |-----|--------|--------------| | style | classic / capsule / hairline | Layout | | theme | graphite / twilight / linen / nord / dracula / sakura / mono / catppuccin-mocha / tokyo-night | Colors | | density | compact / regular / cozy | Padding around segments (capsule + hairline only) | | auto_compact_width | integer (e.g. 100) | Force hairline when terminal narrower than this. 0 = disabled | | show_weekly, show_language | bool | Hide individual segments | | show_cost | bool, default false | Append $ X.XX — the current session's cost as Claude Code reports it. For Pro/Max subscribers this is the API-equivalent value of your usage (what it would cost on the API),