A lightweight statusline monitor for Claude Code that displays rate-limit usage, reset timers, model info, context window, and prompt-cache age. It supports multiple display styles and themes, integrates with AgentParty workflows, and can run as a fast daemon to minimize CPU overhead.
Lightweight Claude Code statusLine: 5h/7d rate-limit usage, reset countdowns, model + context window, prompt-cache age — one line, 3 styles × 9 themes, daemon fast-mode
315Stars
20Forks
0Open issues
3Watching
Python MIT v3.29.12 Updated 6 days ago
README
Claude Status Bar
Lightweight status-line monitor for Claude Code, with a local AgentParty bridge for Codex workflows. In Claude Code it shows your 5h / 7d rate-limit usage, reset timers, current model, context window, prompt-cache freshness, and (optionally) session cost. In Codex + AgentParty workflows it can append the current AgentParty channel, identity, listener, unread count, and last-message preview from a local cache.
On the Claude desktop app (macOS), cs hud adds a floating panel with the
same official 5h / 7d usage and your active AgentParty channels — see
Desktop HUD.
5h[ 27% ]⏰1h28m →42% | 7d[ 79% ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s
📖 Deep dive: Is that
cache 4m23sline actually accurate? — how the prompt-cache countdown is computed
3 styles × 9 themes, configurable in one command. Auto-updates from PyPI.
Quick start
For Claude Code:
pip install claude-statusbar # or: uv tool install / pipx install
cs --setup # wires the statusLine hook + installs the skill
Restart Claude Code to see the bar. Other install paths (one-shot installer, skill-only, plugin marketplace, Codex/AgentParty) are in the install guide.
What it shows
5h[ 27% ]⏰1h28m →42% | 7d[ 79% ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s | $ 1.42
⤷ claude-code-usage-bar ⎇ main● · +182 -47 · ⏱ 12m · v3.12.0
⚙ effort:high · think:on · fast:off · style:default
- Line 1 — 5h / 7d rate-limit usage + reset timers + end-of-window projections, model & context window, prompt-cache countdown, optional session cost / relay balance.
- Line 2 — project + git branch, session
+/−lines, duration, version. - Line 3 — session mode (effort / thinking / fast / style).
- Plus optional activity and AgentParty lines.
The full per-segment breakdown — every icon, color threshold, and toggle — is in the segment reference.
Documentation
| Guide | What's inside |
|---|---|
| Install | PyPI, one-shot installer, skill-only, plugin, Codex bridge |
| What it shows | Full per-segment reference table |
| Styles & themes | 3 styles × 9 themes, previews, slash commands |
| Configuration | Config file, all show_* keys, env vars, JSON output, CLI cheatsheet |
Desktop HUD (cs hud) |
macOS floating panel for the Claude desktop app |
| Fast mode (daemon) | Sub-1% CPU daemon, launchd / systemd auto-start |
| No-quota mode | Relay / Bedrock / Vertex layout, context battery, balance |
| AgentParty / Codex bridge | Local workspace-presence line |
| Cache countdown | Data source + how cache 4m23s is computed |
| Troubleshooting | cs doctor, common problems, upgrading |
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.8(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.jsonexists.
Latest release
Unreleased — Desktop HUD (cs hud, macOS): a floating panel for the Claude desktop app showing official 5h / 7d usage + your active AgentParty channels, with launchd auto-start. See Desktop HUD.
v3.29.12 (2026-07-15) — AgentParty status is session-correct end to end.
v3.28.0 (2026-07-09) — AgentParty / Codex bridge line (show_party).
v3.11.0 (2026-06-02) — rate-limit projections (→NN%).
v3.6.0 (2026-05-08) — cs --setup defaults to daemon (fast) mode.
📋 Full changelog: CHANGELOG.md · GitHub Releases — every version's changes, also linked from the PyPI page.
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_agewidget (#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.
Comments (0)
Sign in to join the discussion.
No comments yet
Be the first to share your take.