claude-statusbar 3.4.1

Lightweight status bar monitor for Claude AI token usage

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 | 7d[   79%    ]⏰11h28m | Opus 4.7(350.0k/1.0M) | cache 4m23s

3 styles × 9 themes, configurable in one command. Auto-updates from PyPI. New in v3.4: per-segment color management — each metric (5h / 7d / context / cache) colors itself by its own severity, classic style finally respects themes, and two community-favorite palettes ship in the box.

Contents

• What's new in v3.4
• What's new in v3.2
• What it shows
• Install
• Styles & themes
• Configuration
• Fast mode (daemon)
• Slash commands
• cs doctor — self-diagnostic
• Usage cheatsheet
• Environment variables
• Troubleshooting
• Upgrading
• Integrations
• Contributing
• Acknowledgments

What's new in v3.4

• Per-segment color management — before, when 7d hit warning the entire line tinted yellow (5h label, separators, model, all sharing a single overall_color = max(severity)). Now each numeric segment colors itself by its own pct: 5h sees only msgs_pct, 7d sees only weekly_pct, the model+context block sees ctx_used_pct, cache keeps its own string-age severity. No color leaks across segments.
• Classic style now respects themes — progress.py previously used raw 8-color ANSI (\033[32/33/31m) regardless of theme. Switching theme had zero effect on classic. Now classic pulls from theme.s_ok / s_warn / s_hot, so all 9 themes finally apply to it.
• Hierarchy via mute — [ ] brackets, (used/size) parens, and the | separator move to theme.mute so the bright severity colors only paint actual data. Numbers and time stay the visual focus.
• Two new themes — catppuccin-mocha (community-favorite pastel, easy on long viewing) and tokyo-night (deeper neon-blue mood with restrained accents). Both honor the per-segment severity contract.
• Per-severity color overrides (v3.4.1) — cs config set color_ok "#4ec85b" (and color_warn / color_hot) layers your own RGB on top of any theme without touching the theme's other fields. Empty string clears the override; supports #rgb, #rrggbb, with or without the leading #. Useful when you like a theme's overall feel but want a sharper "calm" green or a softer warning color.
• theme.pill_cost field — capsule's $ cost pill stops sharing pill_lang with the language pill (a longstanding color collision). New mandatory field on every theme; existing fields unchanged.
• ctx_pct plumbed through — core.py now computes a nullable Optional[float] from context_window_size > 0 (not falsy raw_pct == 0, which would conflate genuine 0% with "no context info"). All three styles consume it; capsule gains a model-pill severity dot, hairline colors the model text.

Visual identity unchanged: battery bar with overlaid percentage, [ ] brackets, 🕐 / ⏰ clock emojis, and | separators all kept. This is a palette + scoping refinement, not a redesign. 293 tests pass.

What's new in v3.2

• Daemon fast-mode — cs --setup --fast swaps the statusLine command to cs render backed by a long-lived cs daemon. At refreshInterval: 1 this cuts continuous CPU from ~6% to ~2%, render wall-clock from ~60ms to ~5ms. Crash-safe (auto-falls-back to inline render if the daemon dies; lazy-respawns).
• OS-managed daemon — cs daemon install installs a launchd agent (macOS) or systemd user unit (Linux) so the daemon auto-starts on login and is restarted on crash by the OS.
• cache 4m23s countdown — opt-in via cs config set show_cache_age true. Counts down to Anthropic's prompt-cache expiry (default 5min TTL); flips through green → yellow (<1min) → red cache COLD. Configurable TTL via cs config set cache_ttl_seconds 3600 for users on the 1-hour extended cache. For Pro/Max subscribers, cache hits consume ~10× less of your 5h / 7d rate-limit quota — letting it go COLD costs you ~10× more quota on the next prompt. The widget tells you whether to send now or wrap up first.
• cs doctor 1Hz hint — detects refreshInterval ≤ 2s with the inline command and recommends cs --setup --fast.
• Import-shaving on the inline path — even users who don't opt into daemon mode get ~30% faster renders.

Existing users: nothing changes by default. Daemon mode is opt-in.

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. Opt-in: cs config set show_cache_age true
$ 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.

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": false
}

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), not money owed; many subscribers use it as a "subscription ROI" gauge. Opt-in because the "session" boundary is what Claude Code reports — not necessarily what you intuitively call one.
show_cache_age	bool, default false	Append a cache 4m23s countdown to Anthropic's prompt-cache expiry. Three-level color: green (>1min remaining), yellow (<1min), red cache COLD (expired). Cache hits consume ~10× less rate-limit quota — for Pro/Max subscribers, letting it go COLD eats your 5h / 7d windows ~10× faster. cs --setup writes refreshInterval: 1 by default so this segment ticks visibly. Original implementation contributed by @marcwimmer in #9.
cache_ttl_seconds	int, default 300	TTL the show_cache_age segment uses to decide warm vs. COLD. Defaults to Anthropic's 5-minute prompt cache. Set to 3600 if you've enabled the 1-hour extended cache via ENABLE_PROMPT_CACHING_1H.

Set via cs config set <key> <value>. Wipe everything back to defaults with cs config reset.

Override per-invocation via --style / --theme flags or CLAUDE_STATUSBAR_STYLE / CLAUDE_STATUSBAR_THEME env vars.

Fast mode — for refreshInterval: 1

If you've set "refreshInterval": 1 in settings.json (so the cache-age widget ticks every second), the default cs command runs ~45ms per render = ~4% CPU continuously. Fast mode brings that down to ~3-5ms per render = under 1% CPU by keeping a long-lived cs daemon that pre-renders into ~/.cache/claude-statusbar/rendered.ansi. The statusLine command becomes cs render — a thin reader that just cats the file.

cs --setup --fast        # writes settings.json + spins up the daemon
cs daemon status         # check it's alive
cs daemon stop           # stop the daemon (statusLine falls back to inline)
cs daemon start          # start it again

Crash safety: if the daemon dies or freezes, cs render notices rendered.meta.json is older than 5s and falls back to inline render — and lazily re-spawns the daemon in the background. You never see a frozen status line.

To revert: cs --setup (no --fast) restores the bare-cs legacy command.

Optional: auto-start on login (launchd / systemd)

Lazy-spawn (above) covers most cases — the daemon comes up on first cs render. If you want stronger guarantees (auto-start at login, OS restarts the daemon on crash, survives reboots without cs render needing to fire first):

cs daemon install        # installs ~/Library/LaunchAgents (macOS) or
                          # ~/.config/systemd/user (Linux), starts the daemon
cs daemon service        # report whether the OS-level service is registered
cs daemon uninstall      # remove the LaunchAgent / systemd unit

On macOS, the LaunchAgent has KeepAlive=true and ThrottleInterval=10 — kill the daemon and launchd respawns it within 10 seconds. On Linux, the systemd user unit uses Restart=always (you may need loginctl enable-linger $USER for the daemon to survive logout).

cs doctor — self-diagnostic

If the status bar isn't behaving the way you expect, run:

cs doctor

It prints (with red ✗ for anything off):

• Which cs binary the OS will resolve, plus its version + Python interpreter
• Whether ~/.claude/settings.json has our statusLine entry (vs missing / vs another tool's)
• How fresh ~/.cache/claude-statusbar/last_stdin.json is (so you can tell if Claude Code is actually pushing data)
• If the daemon is running (fast mode) — its pid and how stale rendered.ansi is
• Terminal size and TERM
• Current resolved style / theme / all show_* toggles
• Slash commands installed under ~/.claude/commands/

Paste the output verbatim in any bug report — it's almost always enough to diagnose remotely.

Install as a Claude Code plugin

The repo ships a .claude-plugin/plugin.json, distributed via the leeguooooo/plugins marketplace. Inside Claude Code:

/plugin marketplace add leeguooooo/plugins
/plugin install claude-statusbar@leeguooooo-plugins

You still need the cs CLI (pip install claude-statusbar or uv tool install claude-statusbar) — the plugin only carries the slash commands; the heavy lifting is the Python package.

Usage

cs                              # render the status line (default command)
cs --style capsule              # render with a one-off style
cs --theme twilight             # render with a one-off theme

# Configuration
cs config show                  # show all persistent config
cs config set style hairline    # persist style → ~/.claude/claude-statusbar.json
cs config set theme linen       # persist theme
cs config set show_cost true    # session $ cost segment
cs config set show_cache_age true   # prompt-cache age segment (needs refreshInterval)
cs config set cache_ttl_seconds 3600  # for users on Anthropic's 1h cache
cs config reset                 # wipe config back to defaults

# Discovery
cs styles                       # list available styles
cs themes                       # list available themes
cs preview                      # render every style × theme with YOUR real data
cs preview --theme nord         # filter to one theme
cs preview --style hairline --theme dracula   # one specific combo

# Daemon mode (v3.2+, opt-in)
cs --setup --fast               # switch statusLine to `cs render` + start daemon
cs daemon start                 # start daemon (manual)
cs daemon stop                  # stop daemon
cs daemon status                # pid + rendered.ansi freshness
cs daemon install               # install LaunchAgent (macOS) / systemd unit (Linux)
cs daemon uninstall             # remove the OS-level service
cs daemon service               # report whether the OS service is registered

# Diagnostics + flags
cs doctor                       # self-diagnostic — paste output in bug reports
cs --json-output                # machine-readable JSON
cs --no-color                   # disable ANSI colors
cs --warning-threshold 40 --critical-threshold 85
cs --no-auto-update             # skip the per-day PyPI version check

--plan still exists for older scripts, but is deprecated and no longer changes the rendered output.

Environment variables

Variable	Effect
CLAUDE_STATUSBAR_STYLE=capsule	Render with this style (overrides config file)
CLAUDE_STATUSBAR_THEME=twilight	Render with this theme (overrides config file)
CLAUDE_STATUSBAR_NO_UPDATE=1	Disable automatic update checks
CLAUDE_STATUSBAR_WARNING_THRESHOLD=40	Switch from green to yellow at 40%
CLAUDE_STATUSBAR_CRITICAL_THRESHOLD=85	Switch from yellow to red at 85%
NO_COLOR=1	Disable ANSI colors

CLAUDE_PLAN is still accepted for legacy compatibility, but it no longer changes the rendered status line.

JSON output

Use --json-output if you want a machine-readable payload instead of the formatted status line:

cs --json-output

Data source

Rate-limit percentages come directly from Anthropic's official API headers, surfaced into the JSON payload Claude Code injects on stdin to every statusLine command. Context-window usage comes from the same payload. The optional cache 4m23s countdown is computed locally by tail-reading the active transcript JSONL — Anthropic's prompt cache TTL is 5 minutes by default (Mar 2026 change) or 1 hour with ENABLE_PROMPT_CACHING_1H.

Requires Claude Code v2.1.80+.

Troubleshooting

Status line doesn't appear after install — Restart Claude Code (settings.json is read at session start). If still missing, run cs doctor and check the statusLine entry row.

cs doctor says "missing" — A Claude Code upgrade can wipe statusLine from ~/.claude/settings.json. Run cs --setup (or cs --setup --fast if you want daemon mode) to restore it. The package also self-heals once per day automatically.

Numbers stuck / not updating — Two possibilities:

1. refreshInterval not set — Claude Code only re-renders on activity. Add "refreshInterval": 30 (or 1 for live cache-age).
2. Daemon mode running stale data — cs daemon stop && cs daemon start. Or just cs doctor and check daemon row freshness.

Cache-age segment shows cache 0s and never moves — refreshInterval is unset; Claude Code only re-invokes the statusLine on each user/assistant turn. Set "refreshInterval": 1 in settings.json. For 1Hz refresh you'll also want cs --setup --fast so the per-second invocation stays cheap.

cs --setup --fast then daemon shows wrong rate-limits — Fixed in v3.2.1. Upgrade with pip install -U claude-statusbar.

Auto-update is annoying / blocked — export CLAUDE_STATUSBAR_NO_UPDATE=1 in your shell rc.

For anything else: open a GitHub issue with the output of cs doctor attached — it captures version, paths, settings.json state, daemon state, and recent cache freshness in one paste.

Upgrading

Auto-updates once per day from PyPI. To upgrade manually:

pip install -U claude-statusbar
# or
uv tool upgrade claude-statusbar

To disable auto-updates: export CLAUDE_STATUSBAR_NO_UPDATE=1

Integrations

prompt-language-coach

Install the prompt-language-coach Claude Code plugin to get IELTS band progress tracking. After setup, the status bar automatically shows your current writing level and trend:

... | Opus 4.7(350k/1M) | 📚 EN:6.0↑ JA:5.0→

• ↑ improved from last session · ↓ dropped · → no change
• No configuration needed — the segment appears automatically when ~/.claude/language-progress.json exists.

Contributing

PRs welcome. Quick guide:

git clone https://github.com/leeguooooo/claude-code-usage-bar
cd claude-code-usage-bar
pip install -e .                    # editable install
pytest                              # 240+ tests, all should pass
PYTHONPATH=src python3 -m pytest -q tests/test_import_perf.py  # perf regression guards

A few conventions to know:

• Render path is hot — every module loaded at import time multiplies its cost by 60×/min at refreshInterval: 1. tests/test_import_perf.py pins this; if your change adds a heavy stdlib import on the path, the test fails.
• Atomic file writes use the helper in cache.py (atomic_write_text) — never path.write_text(...) for state files.
• The daemon path (daemon.py + render_thin.py) is opt-in. The legacy inline path (core.py:main()) must stay working without the daemon.
• New config keys: bump config.StatusbarConfig, VALID_KEYS, the _*_KEYS sets, and document in this README.

Acknowledgments

• @marcwimmer — original show_cache_age widget (#9)
• claude-monitor — token-usage analysis library used as the optional fast-path data source

---

License

MIT

Star History

_{Static snapshot taken at v3.3.x; click for live chart.}