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. 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
• Troubleshooting
• Upgrading
• Comparison with alternatives
• Integrations
• Contributing
• Acknowledgments
• Contributors

Latest release

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 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 render",
    "refreshInterval": 1
  }
}

cs --setup (since v3.6.0) writes cs render + refreshInterval: 1 by default — daemon mode, under 1% CPU continuously, smooth per-second ticks for the cache-age countdown. 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. To opt out and use the legacy inline path, run cs --setup --inline (writes plain cs, ~3% CPU at 1Hz). To go quieter regardless of mode, set refreshInterval to a higher value (30, 60) — cs --setup preserves 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), 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 true	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. Disable with cs config set show_cache_age false.
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 (daemon) — default since v3.6.0

cs --setup writes cs render + refreshInterval: 1 by default. A long-lived cs daemon pre-renders into ~/.cache/claude-statusbar/rendered.ansi; the statusLine command (cs render) is a thin reader that just cats the file. Each tick is ~3-5ms, so total CPU stays under 1% continuously. The legacy inline path (~30ms/tick, ~3% CPU at 1Hz) is still available via cs --setup --inline.

cs --setup               # default: daemon mode, auto-starts the daemon
cs --setup --inline      # opt out, use legacy inline path
cs daemon status         # check the daemon is 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.

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 false  # hide prompt-cache age segment
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 (default since v3.6.0; v3.2 introduced it as opt-in)
cs --setup                      # default: writes `cs render` + starts daemon
cs --setup --inline             # opt out, use legacy inline path
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 enabled-by-default 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

Comparison with alternatives

There are a few good Claude Code usage monitors. They solve overlapping but distinct problems — pick the one that matches where you want the information.

Tool	Lives in	Optimized for
claude-statusbar (cs)	Claude Code's statusLine (one line at the bottom)	Glanceable while you work; zero context-switching
ccusage	Standalone TUI in a separate terminal window	Long-form usage analytics, cost breakdowns over weeks
Claude Code Usage Monitor	Standalone TUI with predictive burn-rate	Real-time burn-rate forecast for paid plans

cs is intentionally one line of color and one decision per second. If you want a dashboard with charts, daily/weekly aggregates, and burn-rate prediction, run a TUI in a side pane. The two coexist nicely.

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. The full contributor guide — local setup, test commands, architecture map, coding conventions, release flow — lives in CONTRIBUTING.md. Security issues: see SECURITY.md.

Quick start:

git clone https://github.com/leeguooooo/claude-code-usage-bar
cd claude-code-usage-bar
uv sync
PYTHONPATH=src uv run pytest tests/   # 320+ tests, ~1.5s

Render path is hot (60×/min at refreshInterval: 1) — tests/test_import_perf.py pins which modules can't be imported on the fast path. Read CONTRIBUTING.md before adding dependencies.

Acknowledgments

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

Contributors

Made with contrib.rocks.

---

License

MIT

Star History

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