claude-statusline

Your Claude Code usage limits, in the statusline, so you stop opening /usage to find out how much of the week you've burned.

Two lines under the prompt. The first says where you are: model, reasoning effort, project, branch, elapsed time. The second says how much you have left:

| | | |---|---| | ctx | how full the context window is | | sess | the 5-hour session limit, and when it resets | | week | the weekly limit across all models | | Fable | the weekly limit for that model specifically. The label comes from the server, so you see whichever model your plan meters |

Percentages are muted below 70%, amber at 70-90%, red above 90%. Everything else stays dim, so the only thing that catches your eye is a limit you should actually care about. If you'd rather see a meter, STYLE=bar and STYLE=dot draw one next to each number.

Install

npx @aliyar/claude-statusline

Restart Claude Code and it's there.

Uninstall

npx @aliyar/claude-statusline --uninstall

This restores whatever statusline you had before, script and setting both, and clears the cache. Your settings file is left alone, so a reinstall picks up where you left off.

No Node? curl -fsSL https://raw.githubusercontent.com/aliyar/claude-statusline/main/install.sh | bash does the same, and takes the same flags after bash -s --.

Needs jq and curl. On macOS brew install jq, on Debian sudo apt install jq.

Settings

Every segment can be turned off, and the thresholds and colors changed:

npx @aliyar/claude-statusline config                        # see everything
npx @aliyar/claude-statusline config set SHOW_ELAPSED off   # change one
npx @aliyar/claude-statusline config toggle SHOW_BRANCH     # flip an on/off
npx @aliyar/claude-statusline config get STYLE              # read one back
npx @aliyar/claude-statusline config reset                  # back to defaults

Changes apply on the next render. No restart.

Settings live in ~/.claude/statusline.conf as plain KEY=value lines, so you can edit the file directly if you'd rather. Spacing, indentation, inline comments, ON/true/1 and Windows line endings are all understood, and the CLI reads the file through the statusline itself, so the two never disagree about what is in effect.

What you can change

| Key | Default | | |---|---|---| | SHOW_MODEL | on | the model name | | SHOW_EFFORT | on | the reasoning effort next to the model | | SHOW_DIR | on | the project directory | | SHOW_BRANCH | on | the git branch | | SHOW_ELAPSED | on | how long the session has been running | | SHOW_CTX | on | context window usage | | SHOW_SESSION | on | the 5-hour session limit | | SHOW_WEEK | on | the weekly limit across all models | | SHOW_MODEL_WEEK | on | the per-model weekly limit, the only one costing a request | | SHOW_RESETS | on | the countdown after each limit | | STYLE | percent | percent, bar or dot | | BAR_WIDTH | 5 | cells in the bar, when STYLE=bar | | LINES | 2 | 1 puts everything on a single line | | WARN_AT | 70 | percent at which a value turns amber | | CRIT_AT | 90 | percent at which it turns red | | HIDE_BELOW | 0 | hide a limit until it reaches this percent | | COLOR_NORMAL | 38;5;108 | ANSI color below WARN_AT | | COLOR_WARN | 33 | ANSI color from WARN_AT | | COLOR_CRIT | 31 | ANSI color from CRIT_AT | | COLOR_MODEL | 36 | ANSI color of the model name | | COLOR_EMPTY | 90 | ANSI color of the unfilled part of a meter | | USAGE_TTL | 900 | seconds between per-model refreshes, minimum 60 | | USAGE_BACKOFF | 1800 | seconds to wait after a failed refresh |

What each switch does

The top line, one setting off at a time:

| | | |---|---| | default | Opus 5 high · my-project (main) · 12m34s | | SHOW_MODEL=off | high · my-project (main) · 12m34s | | SHOW_EFFORT=off | Opus 5 · my-project (main) · 12m34s | | SHOW_DIR=off | Opus 5 high · main · 12m34s | | SHOW_BRANCH=off | Opus 5 high · my-project · 12m34s | | SHOW_ELAPSED=off | Opus 5 high · my-project (main) |

The limits line, shown here as bare percentages so the rows stay short:

| | | |---|---| | default | ctx 34% · sess 42% 41m · week 78% 2d2h · Fable 23% 2d3h | | SHOW_CTX=off | sess 42% 41m · week 78% 2d2h · Fable 23% 2d3h | | SHOW_SESSION=off | ctx 34% · week 78% 2d2h · Fable 23% 2d3h | | SHOW_WEEK=off | ctx 34% · sess 42% 41m · Fable 23% 2d3h | | SHOW_MODEL_WEEK=off | ctx 34% · sess 42% 41m · week 78% 2d2h | | SHOW_RESETS=off | ctx 34% · sess 42% · week 78% · Fable 23% | | HIDE_BELOW=50 | ctx 34% · week 78% 2d2h |

HIDE_BELOW is the one worth knowing about: limits stay invisible until they pass the percent you set, so the statusline is quiet on a fresh week and speaks up when it matters.

And how each limit is drawn:

| | | |---|---| | STYLE=percent (default) | ctx 34% · sess 42% 41m | | STYLE=bar | ctx ▬▬▬▬▬ 34% · sess ▬▬▬▬▬ 42% 41m | | STYLE=dot | ctx ●●●●● 34% · sess ●●●●● 42% 41m | | BAR_WIDTH=12 | ctx ▬▬▬▬▬▬▬▬▬▬▬▬ 34% · sess ▬▬▬▬▬▬▬▬▬▬▬▬ 42% 41m |

WARN_AT, CRIT_AT and the COLOR_* keys only change color, which these tables can't show. Lower WARN_AT to be nagged earlier.

Arrangements

Everything on one line, LINES=1:

A meter next to each number, STYLE=bar:

Or dots, STYLE=dot:

Stripped down: no countdowns, no branch, no effort:

Only the limits, if the rest is already in your shell prompt:

You don't have to guess: config and every config set print a preview of the statusline as it will look, using your real settings.

How it works

Claude Code runs a statusline command on every render and hands it a JSON blob on stdin. ctx, sess and week are all in that blob. No network call, and they're current as of the last API response.

The per-model weekly window is not. For that one number the script calls api.anthropic.com/api/oauth/usage, the same endpoint the /usage screen uses, with the OAuth token Claude Code already stored on your machine.

That endpoint rate-limits, and a weekly number moves by a percent or two a day, so it is not polled. The response is cached in ~/.claude/cache/usage.json and refreshed at most every 15 minutes, in a background process the statusline never waits on. A failed refresh backs off for 30 minutes, and the attempt is stamped before the request goes out, so a dead network can't spawn a request per render, and several Claude Code windows share one budget rather than multiplying it. Turning SHOW_MODEL_WEEK off stops the request entirely.

Nothing is sent anywhere. The token is read at runtime from your keychain (macOS Keychain, secret-tool, or ~/.claude/.credentials.json) and used for that single request.

When something is missing

The script degrades one field at a time instead of failing:

• No Fable segment: your plan has no per-model weekly window, or the cache hasn't been written yet (first run, offline, or the endpoint is rate-limiting). The other three keep working and it comes back on its own.
• No sess / week: plan limits don't apply to your session (API key, Bedrock, Vertex), so Claude Code doesn't send them.
• Malformed payload or config: each value is checked against its type and anything unusable keeps its default, so a typo costs you that one setting and nothing else. The config is parsed, not sourced, so a stray line in it cannot execute, and colours are validated before they reach an escape sequence.

Sanity check:

printf '{}' | bash ~/.claude/statusline.sh

That should print two lines and no errors.

Notes

Tested on macOS with Claude Code 2.1.x. The Linux paths are implemented but less travelled, so issues are welcome.

Disclaimer

An unofficial personal project. Not affiliated with, endorsed by, or supported by Anthropic. "Claude" is Anthropic's trademark and is used here only to say what this tool works with.

The usage endpoint it reads is not a documented, stable API. It's what Claude Code calls internally, and it can change or stop working at any time. If it does, the per-model segment disappears and the rest keeps running.

Provided as is, with no warranty of any kind, and with no liability for any damage arising from its use. See the full terms in LICENSE. You are responsible for what you run on your machine; read the script before installing it. It is one bash file and it makes exactly one network request.

License

MIT. See LICENSE.