ClaudeCodeStatusLine: a shell status line for Claude Code's model, tokens and rate limits
Custom status line for Claude Code showing model, tokens, rate limits, and git info in real-time
At a glance
- What is it?
- This repository installs a single external shell command as Claude Code's status bar, surfacing model, context tokens, 5-hour and 7-day rate-limit percentages, git branch and change counts. It is a small, MIT-licensed script for Pro and Max subscribers who want quota visibility without reading logs.
- Who is it for?
- Adopt it if you already run Claude Code with OAuth on a Pro or Max subscription and you want rate-limit percentages visible while you work, on macOS, Linux or Windows with PowerShell 5.1+. Skip it if you authenticate through an API key, if you cannot install jq and curl on macOS or Linux, or if you object to an outbound request to api.github.com every 24 hours and will not set STATUSLINE_CHECK_UPDATES=false.
- 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 113 days ago.
- What is it written in?
- Mainly Shell, 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
The quota blind spot this fills in a Claude Code session
Claude Code does not put your remaining 5-hour or 7-day rate-limit allowance in front of you while you type. You find out where you stand when a request is refused, or by opening a separate usage page. This project puts that number in the terminal's status line, next to the model name and the context-window consumption for the current conversation.
The intended user is a Pro or Max subscriber working interactively in a terminal. The README lists rate-limit and extra-usage data as subscription features, so an API-key setup gets the model, token and git segments and not the quota ones. That is the first thing to check before you spend time on installation: if rate limits are the reason you are here, an API-key configuration will not show them.
The design choice that matters is that the status line runs as an external shell command. The README says it "does not slow down Claude Code or consume any extra tokens." The token claim is the interesting one. Status-line rendering happens outside the model's context, so the numbers you see are not themselves billed as conversation input. Whether that framing survives a long session depends on how often Claude Code invokes the command, which the README does not state.
What each segment on the line actually reports
The README's table enumerates the segments. Model shows the current model name, with Opus 4.7 given as the example. CWD@Branch shows the current folder name, the git branch, and file changes counted as plus and minus. Tokens shows used over total context-window tokens with a percentage. Effort shows the reasoning effort level as low, med, high or xhigh. Then 5h and 7d give rate-limit usage percentages with reset times, Extra shows credits spent against a limit when that is enabled, and Update appears when a newer release exists.
Color is the only compression mechanism described: green below 50 percent, yellow at or above 50, orange at or above 70, red at or above 90. That is a coarse gradient. It tells you the band you are in, not the exact trajectory, and the README does not describe any smoothing or projection of when you will hit a limit. For a heavy session you would still be reading the percentage itself, not the color.
The git segment is the one piece that does not depend on the Anthropic API at all. It reports branch and change counts from the local repository, which means it stays useful even when the usage fetch fails or is cached stale. The README does not say how the change counts are computed or whether untracked files are included, so treat the plus and minus figures as a rough working-tree signal rather than an audit.
Installation is delegated to Claude Code itself
The documented install path is unusual. Rather than a curl pipe or a package manager, the README tells you to ask Claude Code to do it: clone https://github.com/daniel3303/ClaudeCodeStatusLine to ~/.claude/statusline/ on macOS and Linux, or %USERPROFILE%\.claude\statusline\ on Windows, and configure it as the status bar by following INSTALL.md. The README states that Claude will clone the repository, pick the script matching your OS, and update settings.json, and that step-by-step instructions live in INSTALL.md.
That means the actual configuration keys are in INSTALL.md, which is not included in the material here, so I cannot quote the settings.json structure. What the README does confirm is the directory convention and the fact that settings.json is edited in place. Restart Claude Code after the configuration is saved.
Updates are deliberately boring. The README gives one command:
git -C ~/.claude/statusline pull
and states that no settings.json changes are needed because the path stays valid across versions. That is a real property, not marketing: keeping the script at a stable path means the configuration never has to be regenerated. The trade-off is that the repository is a checkout you own, and a local modification will collide with a pull. The README does not discuss that case.
Requirements are short: Claude Code with OAuth authentication, git in PATH, jq and curl on macOS and Linux, and PowerShell 5.1 or later on Windows, which ships with Windows 10 and 11. The jq dependency is worth noting because it is not present by default on many minimal Linux images.
Caching, the 60-second window and shared state between sessions
The status line does not call the Anthropic API on every render. The README states that usage data is cached for 60 seconds at /tmp/claude/statusline-usage-cache-<hash>.json, or under %TEMP%\claude\ on Windows, and that release checks are cached for 24 hours. Both caches are described as shared across concurrent Claude Code instances.
The sharing is the deliberate part. If you run several Claude Code sessions in parallel, they read one cached usage file instead of each issuing their own request, which the README frames as a way to avoid rate limits. The consequence is that a freshly opened terminal can display a usage figure up to a minute old. In a session where you are burning quota quickly, that lag is the difference between seeing 88 percent and already being at 92, and the color band can flip between two renders with no change in your actual usage pattern.
The cache path includes a hash, which suggests it is keyed to something about the account or configuration, but the README does not say what is hashed. If you run multiple accounts, that detail decides whether they share a cache file or not, and the material here does not resolve it. The update check is the one network call that is not about usage: it queries api.github.com once every 24 hours and fails silently when the API is unreachable. Silent failure is the right default for a status line, though it also means a broken network path looks identical to being up to date.
Where this is the wrong tool
The clearest failure mode is authentication. Rate-limit and extra-usage segments depend on OAuth with a Pro or Max subscription. On an API-key setup the line still renders model, CWD@Branch and Tokens, but the two segments most people install this for are absent. If your team runs Claude Code through a gateway or a shared key, this project is not the quota dashboard you are looking for.
The second limitation is platform shape. macOS and Linux need jq and curl installed; Windows needs PowerShell 5.1 or later. That is a wider dependency set than a pure POSIX script, and jq in particular is a common gap on stripped-down containers and CI images. The README does not describe a fallback when jq is missing, so the likely outcome is a broken or partially empty line rather than a clear error.
The third is the update notification, which is also the only outbound call that is not about your usage. It contacts api.github.com every 24 hours. For anyone working in an environment where outbound requests from a developer tool are logged or restricted, that is a decision to make consciously. The README provides the escape hatch directly:
export STATUSLINE_CHECK_UPDATES=false
Setting that variable disables the check entirely, with no network calls. Note that this is documented as an environment variable, so it needs to be set in the environment Claude Code inherits, not in a shell you open afterwards.
Finally, this is a display tool. It shows percentages and reset times. It does not warn, block, queue or throttle a request when you approach a limit. If you want enforcement rather than visibility, a status line is the wrong layer.
The alternative: reading usage from the API yourself
The obvious alternative is not another status-line project but a script you write against the same Anthropic usage endpoint. The difference in approach is where the caching and rendering logic lives. Here you inherit someone else's decisions: a 60-second cache, a shared cache file keyed by a hash, a 24-hour release check against api.github.com, and a fixed color banding at 50, 70 and 90 percent. A script of your own lets you choose a shorter cache, skip the update check by construction, and render the reset time in your own timezone format.
What you give up is the work already done: OS-specific script selection between shell and PowerShell, the settings.json wiring described in INSTALL.md, the git branch and change-count segment, and the version-notification path. That is a real amount of plumbing for a line of text.
The decision rule is whether your requirements fit the defaults. If a one-minute-stale percentage and a four-band color scheme are enough, adopting this is cheaper than writing it. If you need sub-minute freshness, per-model quota breakdowns, or output that feeds another tool rather than a human, the defaults will fight you, and the 60-second cache in /tmp/claude/ is the specific thing you would be rewriting.
Maintenance cost, licence and what the release cadence implies
The repository is MIT licensed. That is permissive: you can modify the scripts, vendor them into an internal repository, or fork them without a copyleft obligation. It is not legal advice, and if you redistribute a modified version you still need to carry the licence text. The README names Daniel Oliveira as the author and links a personal site, X and LinkedIn profile, so this is a single-maintainer project rather than something with an organisational backstop.
The release history shows v1.4.4, v1.4.3 and v1.4.2, dated 2026-05-26, 2026-05-11 and 2026-04-23. The gaps are roughly two to three weeks, and the latest push timestamp matches the v1.4.4 release. That pattern is consistent with active but not frantic maintenance. It also means the update notification will fire reasonably often if you leave the check enabled, which is a mild argument for setting STATUSLINE_CHECK_UPDATES=false and pulling deliberately.
The upgrade procedure is the cheapest part of the whole arrangement. Because the script stays at ~/.claude/statusline/ and settings.json points at that path, updating is one git pull with no reconfiguration. The cost you carry instead is that the checkout is yours to keep clean. If you edit the script locally to change color thresholds or cache timing, a pull can conflict, and the README does not describe a merge strategy or a way to pin a version. Forking is the honest answer there, and MIT permits it.
Editorial conclusion
Adopt it if you already run Claude Code with OAuth on a Pro or Max subscription and you want rate-limit percentages visible while you work, on macOS, Linux or Windows with PowerShell 5.1+. Skip it if you authenticate through an API key, if you cannot install jq and curl on macOS or Linux, or if you object to an outbound request to api.github.com every 24 hours and will not set STATUSLINE_CHECK_UPDATES=false. Before installing, confirm that git is in PATH, that ~/.claude/statusline/ is the path you want the repository cloned to, and that your settings.json already points at the script INSTALL.md selects for your OS, because the update path is a plain git pull and nothing rewrites that configuration for you.
Community notes