claude-statusbar: official 5h and 7d Claude Code rate limits on one line
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
At a glance
- What is it?
- claude-statusbar renders Claude Code's own rate-limit numbers, reset countdowns, model and context window into the status line, with a floating HUD for the macOS desktop app. It is a display layer for numbers Claude Code already enforces, not a usage estimator.
- Who is it for?
- Adopt claude-statusbar if you run Claude Code in a terminal all day and keep losing track of when the 5h window resets, or if you use the macOS desktop app and want the same numbers in a floating panel. Skip it if you need quota data on Windows, or if you want to track spend across accounts rather than read the limits Claude Code already enforces in one session.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What claude-statusbar actually answers
Claude Code enforces a 5-hour and a 7-day rate limit, and the README's framing is blunt: the tool "tells you almost nothing about where you stand" against them. claude-statusbar exists so you stop opening a second window to answer how much is left and when it resets. The line shows the official 5h and 7d usage figures, reset countdowns, end-of-window projections written as `→NN%`, the current model with context occupancy in the form `Opus 4.8 · 350k/1M`, and a prompt-cache countdown such as `cache 4m23s` that tells you when the next turn stops being cheap. Optional segments cover per-session cost, git branch and diff stats, session activity, and a few narrower integrations.
The audience is narrow on purpose. This is for someone who lives in Claude Code's terminal session and wants ambient awareness without leaving the prompt. It is not an analytics dashboard, it does not aggregate across machines, and it does not tell you what a token costs. The README also states plainly that the 5h and 7d numbers are the same ones Claude Code enforces, not a local estimate, which is the main claim separating it from scripts that parse transcripts and guess.
Where the numbers come from, and what the daemon does
The rendering path is a statusLine hook: Claude Code hands the bar a payload, and the bar prints one line. The README's refresh table is the clearest description of the data flow. Countdown and elapsed time are recomputed from timestamps on every render, so they stay live between data pulls. Context, model and session cost come from the latest statusLine input. Transcript activity reuses unchanged snapshots and reads only appended tail bytes, with a bounded rebuild when a file is replaced or truncated. Git dirty/ahead/behind state is shared per worktree behind a 30-second cache and only one refresh runs at a time. Configuration and language progress reload when file metadata changes, and balance or optional model caps are shared per account with background refresh, where failures are cached rather than retried in a loop.
Fast mode is the part worth understanding before you judge the CPU cost. Release bundles ship a native cache reader and two persistent render workers, with git and network collection on separate bounded background queues. The native reader is only in the macOS arm64 and Linux x86_64 release archives; pip and uv installs keep using the Python client. The repository includes two benchmark scripts, `scripts/benchmark_native.py` and `scripts/benchmark_daemon.py`, and the README says both run against temporary fixtures rather than live sessions or credentials. The daemon writes aggregate timing and worker counters to `~/.cache/claude-statusbar/scheduler.json`, and the README states that file holds no payloads or tokens.
Installing claude-statusbar and getting a first render
The fastest path is the install script, which the README describes as downloading a prebuilt standalone binary for macOS Apple Silicon or Linux x86_64 and wiring up the status line. It needs no Python and no pip. On macOS the same command also registers the floating desktop HUD to start at login if the Claude desktop app is present, because the macOS binary bundles it.
curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bashPiping a remote script into bash deserves scrutiny, and the README addresses it directly: it suggests downloading and reading the script first, noting that its header lists exactly what it touches. On platforms without a prebuilt binary, the script falls back to pip.
If you would rather manage the package yourself, install from PyPI and run the setup command. The project exposes three console scripts, `claude-statusbar`, `cstatus` and `cs`, all pointing at the same entry point.
pip install claude-statusbar
cs --setupThe README says `cs --setup` wires the statusLine hook and installs the skill, and that you should restart Claude Code afterwards. What you should see is a single line at the bottom of the terminal showing the 5h and 7d bars, a reset countdown, your model and context occupancy, and the cache countdown. If the line does not appear, the hook was not registered; the README points to docs/install.md for skill-only, plugin marketplace and Codex/AgentParty paths.
The macOS HUD and the upgrade warning you should not skip
The desktop app has no status line, so `cs hud` adds an always-on-top floating panel. The README says the usage figures there are sampled by the desktop app itself rather than estimated, which matters because a HUD that guessed would be worse than no HUD. The HUD extra is macOS-only in pyproject.toml: the `hud` optional dependency group pulls `pyobjc-framework-Cocoa` and `pyobjc-framework-Quartz` behind a `sys_platform == 'darwin'` marker. On anything else, installing that extra gets you nothing.
The README carries an important notice aimed at macOS standalone users: upgrade to v3.32.5, because older onefile releases could leave a new roughly 11 MB PyInstaller `_MEI*` runtime directory on every one-second refresh that was killed during startup. Re-running the installer switches to an onedir bundle and removes inactive leftovers. That is a real failure mode with a real cost, disk churn on a timer, and it is the kind of thing a status bar should never cause. If you installed a standalone macOS build before that fix, re-run the install command rather than waiting.
show_per_model, OAuth credentials and the opt-in you should read twice
Per-model weekly limits are off by default and gated behind one config key:
cs config set show_per_model trueThe README is unusually explicit about what that flips on. It enables read-only OAuth credential access through `~/.claude/.credentials.json` or the macOS login Keychain, plus background requests to what the README calls Anthropic's undocumented usage endpoint. No token is logged or stored in a cache. Requests are account-scoped, cached for five minutes, and unsupported responses hide the segment rather than showing a wrong number. Relay and no-quota sessions never request these limits at all. The segment renders on its own line below the main usage row.
The honest reading is that this is a dependency on an interface Anthropic has not committed to. The mitigation is graceful degradation, not stability. If you are not specifically chasing per-model weekly caps, leave the key alone; the default configuration touches no credentials. If you do enable it, understand that you are granting a third-party tool read access to your Claude credentials in exchange for one extra line.
Platform gaps and the cases where this is the wrong tool
The README names prebuilt binaries for macOS Apple Silicon and Linux x86_64 only, and pyproject.toml declares the package itself as OS Independent with Python 3.9 through 3.12. So the pip route can run on other platforms, but the native fast path cannot, and the HUD is macOS-only. Anyone searching for a Windows story will not find one in this README; the install guide is the place that would say otherwise, and the README does not.
There are two more limits worth stating. First, this is a per-session display. It reads the limits Claude Code enforces for the session in front of you, and nothing in the README describes aggregating usage across accounts, machines or teammates. Second, the optional `full` extra depends on `claude-monitor>=3.0.0`, so cost-oriented features inherit that project's behavior rather than being self-contained. If your actual question is "what did this project cost last quarter," a status line is the wrong instrument. If your question is "can I finish this refactor before the 5h window resets," it is exactly the right one.
Alternatives and the difference in approach
The obvious comparison is a hand-rolled statusLine script that parses Claude Code's transcript files and computes its own totals. The difference is not cosmetic. A transcript parser reconstructs usage after the fact and can disagree with the number Claude Code will actually enforce; claude-statusbar's stated position is that it displays the official 5h and 7d figures with reset countdowns and end-of-window projections rather than a local guess. If you have ever watched a self-computed percentage hit 100 while the session kept working, that distinction is the whole product.
The second comparison is claude-monitor, which appears here as an optional dependency of the `full` extra rather than as a rival. Where claude-statusbar optimizes for one line of ambient information inside the terminal, a monitor-style tool is about observing usage over time. They can coexist: the `full` extra exists precisely because someone wanted both. The trade-off claude-statusbar accepts is scope. It renders; it does not store history, chart trends, or answer questions about last week.
Maintenance, licensing and what an upgrade costs
The repository is not archived, and the last push was on 2026-09-13. Release cadence is high: v3.42.0 on 2026-09-05 introduced the native fast path and channel-aware auto-updates, then v3.43.0 and v3.43.1 both landed on 2026-09-13 with small layout changes. Two patch releases in the same hour for status-line formatting tells you the surface area being tuned is presentation, not architecture.
Upgrade cost is low by design. The README states that existing `cs render` commands keep working and that binary upgrades take effect on the next invocation, so there is no restart ritual beyond what you already do. Auto-updates are channel-aware. The one migration that is not optional is the macOS standalone move to v3.32.5 described above, and it is a re-run of the installer rather than a manual cleanup.
The licence is MIT, declared in both the LICENSE file and pyproject.toml. That is permissive and imposes no source-disclosure obligation on your own code. It also means the maintainer offers no warranty, and the project ships no support commitment. The one licensing-adjacent thing to weigh is not legal at all: enabling `show_per_model` points the tool at your Claude credentials and an endpoint Anthropic has not documented. That is a decision about trust and blast radius, and it is worth making deliberately rather than by pasting a config command.
Editorial conclusion
Adopt claude-statusbar if you run Claude Code in a terminal all day and keep losing track of when the 5h window resets, or if you use the macOS desktop app and want the same numbers in a floating panel. Skip it if you need quota data on Windows, or if you want to track spend across accounts rather than read the limits Claude Code already enforces in one session. Before wiring it in, run cs --setup and confirm the bar renders your model and context window, then decide whether to leave show_per_model off: turning it on grants read-only access to ~/.claude/.credentials.json and background requests to an undocumented Anthropic usage endpoint, and the README is silent on what happens when that endpoint changes shape beyond hiding the segment.
Frequently asked questions
How does Claude Code usage work in claude-statusbar?
The bar displays the official 5h and 7d rate-limit numbers that Claude Code enforces, together with reset countdowns and end-of-window projections, rather than a locally computed estimate. Countdown and elapsed time are recomputed from timestamps on each render, while context, model and session cost come from the latest statusLine input.
Does the Claude code show usage on its own?
The README's premise is that Claude Code tells you almost nothing about where you stand against your rate limits, which is the gap the project fills. claude-statusbar adds a statusLine hook that prints the 5h and 7d usage, reset countdowns, model and context window on one line.
What is the Claude code usage bar on a Mac?
On macOS the install script downloads a standalone binary that wires the terminal statusLine and, if the Claude desktop app is installed, registers a floating always-on-top HUD that auto-starts on login. The README says the desktop app samples the official 5h and 7d usage itself rather than estimating it.
What is the purpose of using the Claude code usage bar?
It removes the context switch of opening a separate window to answer how much quota is left and when it resets. The line also shows context occupancy and a prompt-cache countdown, so you can see when the next turn stops benefiting from a warm cache.
Community notes