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

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

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

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:

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
}

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

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.

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.}