ClaudeCodeStatusLine: A Shell Status Line for Claude Code Tokens, Rate Limits and Git State

What ClaudeCodeStatusLine puts on the line

Claude Code lets you replace its built-in status bar with an external command. This project is that command: a shell script for macOS and Linux, a PowerShell script for Windows, called on each render. The README lists the segments it prints: the current model name, the working folder with git branch and file change counts, used versus total context window tokens with a percentage, the reasoning effort level, 5-hour and 7-day rate limit percentages with reset times, extra usage credits when enabled, and an update notice.

The audience is narrow and specific. Rate-limit percentages and extra-usage credits come from Anthropic's API over OAuth, so the README states a Pro or Max subscription is required for those segments. An API-key user still gets model, tokens and git info, but the two limit columns that make this project interesting would be empty. The colour coding is the other selling point: green below 50 percent, yellow at 50, orange at 70, red at 90. That turns an abstract quota into something you notice while typing.

How the script gets its numbers without slowing Claude Code

The README is explicit that the status line runs as an external shell command, so it does not slow down Claude Code or consume extra tokens. That matters because a status line is rendered often; anything that blocks on a network call each time would be felt. The project avoids that with caching. Usage data from the Anthropic API is cached for 60 seconds at /tmp/claude/statusline-usage-cache-<hash>.json on macOS and Linux, or under %TEMP%\claude\ on Windows. Release checks are cached for 24 hours. Both caches are shared across concurrent Claude Code instances, which the README says avoids rate limits.

The update check is the only outbound call described beyond the usage fetch: once every 24 hours to api.github.com. When a newer release exists, a second line appears below the status line. The README states the check fails silently if the API is unreachable, and that STATUSLINE_CHECK_UPDATES=false disables it entirely, with no network calls. For anyone working on a restricted network, that switch is the difference between usable and not.

Git information comes from git itself, which is why the README lists git in PATH as a requirement. The repository holds two scripts, statusline.sh and statusline.ps1, plus INSTALL.md. There is no daemon, no background service, no database. The whole architecture is: Claude Code calls a script, the script reads a cache file or fetches usage, then prints one line.

Installing ClaudeCodeStatusLine and seeing it render

The README does not ask you to run an installer. It asks you to ask Claude Code. The documented prompt tells Claude to clone the repository into ~/.claude/statusline/ on macOS and Linux, or %USERPROFILE%\.claude\statusline\ on Windows, and to configure it as the status bar by following INSTALL.md. Claude picks the right script for your OS and updates settings.json. The full step-by-step instructions Claude follows live in INSTALL.md.

If you prefer to do it yourself, the README gives one command for updating an installed copy:

git -C ~/.claude/statusline pull

The README notes no settings.json changes are needed because the path stays valid across versions. The same command is what you run when the status line shows that a new release is available.

Before you start, check the requirements the README lists. On macOS and Linux you need jq and curl, plus git in PATH. On Windows you need PowerShell 5.1 or later, which ships with Windows 10 and 11. If jq is missing, the script has no parser for the cached JSON and the usage segments will not render.

If you would rather not have the status line contact GitHub for releases, the README documents one environment variable:

export STATUSLINE_CHECK_UPDATES=false

With that set, no request goes to api.github.com and the second line never appears. Restart Claude Code after the configuration is saved.

Where ClaudeCodeStatusLine falls short

The dependency on OAuth is the biggest limitation, and it is easy to miss. The README ties rate-limit and extra-usage data to a Pro or Max subscription. If your team runs Claude Code against an API key, you get a status line with model, tokens, effort and git, but the 5-hour and 7-day segments that most people install this for will not populate. Check which authentication mode your Claude Code uses before assuming the numbers will appear.

The 60-second cache is a deliberate trade-off with a visible consequence. Immediately after a burst of work, the percentage on screen can lag the real quota by up to a minute. That is fine for ambient awareness and wrong for anyone trying to time a request against a hard limit to the second.

There is also a privacy dimension the README does not discuss. The script reads usage data from Anthropic's API and, by default, contacts api.github.com every 24 hours. On a machine where outbound requests are audited, that second call needs explaining. Disabling it with STATUSLINE_CHECK_UPDATES=false is documented, but the README does not document rollback or uninstall steps, so removing the status line means reversing the settings.json change yourself.

Finally, this is a status line, not a monitor. There is no history, no graph, no alert when you cross 90 percent. The colour changes and that is all. If you need a record of usage over time, this is the wrong tool.

How it compares with writing your own status line command

The realistic alternative is not another product. It is a ten-line script you write yourself and point Claude Code at. That approach gives you exactly the fields you want and nothing else, with no update check, no cache directory under /tmp/claude, and no third-party code reading your usage data. The cost is that you implement the usage fetch, the cache, the JSON parsing with jq, the colour thresholds and the git formatting yourself, and you maintain them when Claude Code's status line interface changes.

This project is essentially that script, already written, with the rate-limit and cache logic handled and both a bash and a PowerShell implementation. The trade is convenience for a dependency you did not write. Because it is MIT licensed and the repository is two scripts plus INSTALL.md, the honest middle path is to read statusline.sh before installing it. If the fetch and cache logic looks acceptable, keep it. If not, the same file is a working reference for your own version.

One comparison worth noting: the README's install flow is itself unusual. Instead of a curl pipe to bash, it hands the job to Claude Code, which reads INSTALL.md and edits settings.json. That is convenient and also means an agent is modifying your configuration. Review the diff afterward.

Maintenance, updates and the MIT licence

The last push to the default branch was on 2026-05-26, the same day as the v1.4.4 release. The two prior releases, v1.4.3 and v1.4.2, landed on 2026-05-11 and 2026-04-23. The release cadence in that window was roughly every two to three weeks, and the repository is not archived. Nothing in the repository shows activity after May 2026, so treat the project as one whose update rhythm you should verify against the releases page rather than assume.

Upgrade cost is low by design. Because the script lives at a fixed path and settings.json points at that path, a git pull is the whole upgrade. The README states no settings.json changes are needed. The update notification exists precisely so you do not have to watch the repository: it checks once every 24 hours and prints a second line when a newer version is available.

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is the plain reading of the licence text; it is not legal advice, and if you vendor the script into a product, have your own counsel confirm the notice requirements.

One maintenance risk is worth naming. The script depends on Anthropic's usage API shape and on Claude Code's status line invocation contract. Neither is controlled by this project. A change to either can break the usage segments, and the README does not describe a fallback beyond the cache. Pinning to a known-good commit is possible but forfeits the update notification.

Editorial conclusion

Adopt it if you run Claude Code on a Pro or Max subscription and want context usage and rate-limit resets visible while you work; the script is small enough to read before you trust it with your terminal. Skip it if you authenticate with an API key, since the rate-limit and extra-usage segments depend on OAuth data, or if you want a status line with no outbound requests at all. Before installing, read INSTALL.md and confirm that jq and curl are present on macOS or Linux, or PowerShell 5.1 or later on Windows.

Frequently asked questions

Official sources

1. daniel3303/ClaudeCodeStatusLine on GitHub
2. License: MIT
3. Project website
4. README
5. Releases