leeguooooo/claude-code-usage-bar

Claude Status Bar – Quick glance at your Claude Code limits

What it is

• A tiny utility that shows the official 5‑hour / 7‑day rate‑limit counters, reset timers, model name, context‑window usage, prompt‑cache warm‑up time and optional cost/balance directly in Claude Code’s status line (or as a floating HUD on macOS).
• It works with the Claude Code terminal client and, on macOS, with the Claude desktop app.

How you use it

• One‑line installer (macOS/Linux) downloads a pre‑built binary that automatically hooks into Claude Code’s statusLine and, if the desktop app is present, registers a floating HUD that starts on login.
• Python package (pip install claude-statusbar) gives the same functionality plus optional extras ([hud] for the macOS panel) and lets you run the cs CLI to configure, install the skill, or launch the HUD manually.
• Windows: a PowerShell one‑liner installs the uv tool and the binary without needing admin rights.

What you see

• A single coloured bar at the bottom of the terminal, e.g.

  5h/7d  →12%  Opus 4.8·350k/1M  cache 4m23s  $0.12
  

  • 5h/7d – current usage vs the official limits.
  • →12% – projected percentage of the window that will be used by the end of the period.
  • Opus 4.8·350k/1M – model name and how much of its context window is filled.
  • cache 4m23s – time left before the prompt‑cache “cools down”.
  • $0.12 – optional per‑session cost or live balance for relay/no‑quota sessions.
• Optional extra segments: git branch/diff stats, session activity, language‑coach progress, etc., all togglable via the config file.

Key features

• Official numbers – pulls the exact usage data from Anthropic’s undocumented endpoint (when you enable show_per_model). No local guessing.
• Zero‑dependency install – a single binary (macOS arm64, Linux x86_64) or a pure‑Python wheel; no Python runtime needed for the binary.
• Fast mode – native cache reader + two persistent render workers keep the per‑second refresh under 1 % CPU.
• Customisable look – three styles (battery‑bar, capsule, hairline) × nine colour themes, switchable with a single command.
• Desktop HUD – on macOS the HUD floats above the Claude desktop app, collapses to a pill, and can be dragged anywhere.
• Extensible – integrates with the author’s prompt-language-coach plugin to show IELTS band progress automatically.

Configuration & docs

• All knobs live in a JSON/YAML config (cs config set …).
• Docs cover installation, segment reference, styles/themes, fast‑daemon mode, no‑quota mode, cache‑countdown math, troubleshooting, and HUD setup.
• The project ships a full test suite (900+ tests) and CI badges to assure stability.

Who might need it

• Anyone who uses Claude Code heavily and wants to avoid surprise rate‑limit blocks.
• Developers who run many Claude sessions in a terminal and need a glanceable indicator without opening a separate dashboard.
• macOS users of the Claude desktop app who prefer a persistent on‑screen panel.

---

TL;DR: Claude Status Bar is a lightweight, install‑once‑and‑forget tool that injects an always‑up‑to‑date usage bar into Claude Code’s UI, letting you monitor limits, model state and cost in real time, with optional macOS HUD and plenty of customisation.