README
¶
HowMuchLeft
howmuchleft is the fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms. It is for Pro, Max and Team subscribers who want to see how much of every limit is left without leaving the terminal. Usage comes from the credentials Claude Code has already stored, so there is no API key to supply and no separate login.
What each bar tracks:
| Bar | What it tracks |
|---|---|
| Context window | How full your conversation is, plus subscription tier and model |
| 5-hour usage | Rolling rate limit, time until reset, git branch and the session's line counts |
| Weekly usage | Rolling 7-day rate limit, time until reset, current directory |
Works with Pro, Max 5x, Max 20x, and Team subscriptions. API key users see context bar only.
Install
go install github.com/smm-h/howmuchleft@latest
Pre-built binaries for all platforms are available on GitHub Releases.
Setup
howmuchleft profile install
This registers the binary with Claude Code's settings.json.
Uninstall
howmuchleft profile uninstall
Config
Config lives at ~/.config/howmuchleft/config.toml, auto-created on first run.
Commands
| Command | Purpose |
|---|---|
howmuchleft profile install |
Register with Claude Code |
howmuchleft profile uninstall |
Remove from Claude Code |
howmuchleft profile list [--live] |
Multi-profile dashboard |
howmuchleft demo |
Animated demo of all bars |
howmuchleft colors |
Preview current gradient |
howmuchleft config |
Show config path and values |
howmuchleft version |
Print version |
Performance
Claude Code spawns the statusline on every render, so start-up cost is paid every time. Medians of 100 warm runs per tool on one machine, every tool fed the same status object:
| Tool | Language | Median ms |
|---|---|---|
| howmuchleft | Go | 5.9 |
| cship | Rust | 8.3 |
| CCometixLine (ccline) | Rust | 15.0 |
| best-claude-hud | Rust | 15.3 |
| claude-code-statusline-pro | Rust | 19.7 |
| claude-powerline | TypeScript on Node | 194.5 |
Spawning /bin/true on the same machine medians 2.8 ms, so a good part of every compiled tool's number is the cost of starting a process at all. The full table, what each tool shows, the caveats and the harness that produced the numbers are in Comparison with other statuslines.
License
MIT
Documentation
¶
Overview ¶
Command howmuchleft is the fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms.
Claude Code pipes a JSON status object on stdin on every render; the binary writes three lines of ANSI text to stdout and exits. Invoked without piped stdin it behaves as an ordinary CLI, with commands for installing the statusline into a Claude Code profile, listing profiles, running the demo, previewing colors, inspecting the config and printing the version.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cache
Package cache fetches the Claude usage windows from the platform API and stores them in a file cache with a TTL, error backoff and stale-data fallback, so a statusline render costs at most one network call per minute.
|
Package cache fetches the Claude usage windows from the platform API and stores them in a file cache with a TTL, error backoff and stale-data fallback, so a statusline render costs at most one network call per minute. |
|
cli
Package cli builds howmuchleft's strictcli command tree and runs the statusline itself: it parses the status object Claude Code pipes on stdin, gathers usage, git and profile data, and hands the result to internal/render.
|
Package cli builds howmuchleft's strictcli command tree and runs the statusline itself: it parses the status object Claude Code pipes on stdin, gathers usage, git and profile data, and hands the result to internal/render. |
|
config
Package config loads ~/.config/howmuchleft/config.toml, validates and clamps its values, and supplies the defaults every other package builds on.
|
Package config loads ~/.config/howmuchleft/config.toml, validates and clamps its values, and supplies the defaults every other package builds on. |
|
dashboard
Package dashboard discovers the registered Claude Code profiles and renders their usage bars side by side, once or refreshing in place.
|
Package dashboard discovers the registered Claude Code profiles and renders their usage bars side by side, once or refreshing in place. |
|
demo
Package demo animates the statusline from synthetic sawtooth usage waves, so the bars and their gradient can be seen without waiting for real usage.
|
Package demo animates the statusline from synthetic sawtooth usage waves, so the bars and their gradient can be seen without waiting for real usage. |
|
git
Package git reports the current branch by reading the repository's HEAD file directly.
|
Package git reports the current branch by reading the repository's HEAD file directly. |
|
migrate
Package migrate brings the on-disk howmuchleft config up to the shape the current binary expects: it creates ~/.config/howmuchleft/config.toml when it is missing, and fills in any key a newer version introduced.
|
Package migrate brings the on-disk howmuchleft config up to the shape the current binary expects: it creates ~/.config/howmuchleft/config.toml when it is missing, and fills in any key a newer version introduced. |
|
oauth
Package oauth reads the credentials Claude Code already stores, refreshes an expired access token, and reports whether the session is an OAuth subscription and which tier it is on.
|
Package oauth reads the credentials Claude Code already stores, refreshes an expired access token, and reports whether the session is an OAuth subscription and which tier it is on. |
|
platform
Package platform answers the host-specific questions the statusline needs: where the Claude Code directory is, which profile and Claude Code version are in use, how long the session has been running, whether the desktop is in dark mode, and which GitHub user is signed in.
|
Package platform answers the host-specific questions the statusline needs: where the Claude Code directory is, which profile and Claude Code version are in use, how long the session has been running, whether the desktop is in dark mode, and which GitHub user is signed in. |
|
render
Package render composes the three-line ANSI statusline: horizontal and vertical progress bars with fractional block characters, the green-to-red gradients that fill them, and the labels laid out around them.
|
Package render composes the three-line ANSI statusline: horizontal and vertical progress bars with fractional block characters, the green-to-red gradients that fill them, and the labels laid out around them. |