claude-statusbar 3.2.1

Lightweight status bar monitor for Claude AI token usage

Claude Status Bar

Lightweight Claude Code status bar monitor for the built-in statusLine hook.

It shows your current Claude.ai rate-limit usage, reset timers, and context window usage in a compact single-line format.

What it shows

5h[███38%░░░░]⏰2h14m | 7d[███87%███░]⏰3d05h | Opus 4.6(90.0k/1.0M)

Segment	Meaning
5h[███38%░░░░]	5-hour rate-limit usage
⏰2h14m	Time until the 5-hour window resets
7d[███87%███░]	7-day rate-limit usage
⏰3d05h	Time until the 7-day window resets
Opus 4.6(90.0k/1.0M)	Model name plus current context usage
📚 EN:6.0↑ JA:5.0→	IELTS band progress (requires prompt-language-coach)

Colors default to green / yellow / red at 30% and 70%, and can be customized.

Styles & themes (v2.7+)

The default style (classic) stays the same forever. Two new 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

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

Style and theme are independent: any of the 3 styles × 7 themes = 21 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)
/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	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 a $ X.XX segment with the current session's cost (from Claude Code's stdin payload). 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 15s (green) / cache COLD (red) segment showing how long since Claude's last assistant turn. Anthropic's prompt cache TTL is 5 minutes — the segment flips to COLD past that. Useful to see at a glance whether your next request will hit the warm cache. Requires "refreshInterval": N in your ~/.claude/settings.json statusLine block (e.g. 30) — without it Claude Code only re-renders on activity, so the value freezes. 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.

Install

One-line install (recommended)

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

This installs the package, configures Claude Code statusLine, and sets up aliases. Restart Claude Code to see it.

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

Usage

cs                            # show status bar (shortest alias)
cs --style capsule            # render with capsule style for one run
cs --theme twilight           # override theme
cs config show                # show persistent config
cs config set style hairline  # save style to ~/.claude/claude-statusbar.json
cs config set theme linen     # save theme
cs config set show_cost true  # show this session's $ cost on the bar
cs config reset               # wipe config back to defaults
cs styles                     # list available styles
cs themes                     # list available themes
cs preview                    # render every style × theme using your real data
cs doctor                     # self-diagnostic — paste this in any bug report
cs --json-output              # machine-readable JSON
cs --no-color                 # disable ANSI colors
cs --warning-threshold 40 --critical-threshold 85
cs --no-auto-update           # disable auto-update checks

--plan still exists for older scripts, but it is deprecated and no longer changes the status line 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 data comes directly from Anthropic's official API headers exposed to Claude Code status-line commands through stdin.

Context-window usage comes from the same stdin payload that Claude Code sends to custom statusLine commands.

Requires Claude Code v2.1.80+.

Upgrading

Auto-updates once per day. To upgrade manually:

pip install --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.6(90k/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.

---

License

MIT

Star History