{"_id":"@aliyar/claude-statusline","_rev":"2-3cbc5160266b92acefb029c60624184a","name":"@aliyar/claude-statusline","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@aliyar/claude-statusline","version":"1.0.0","keywords":["claude","claude-code","statusline","usage","rate-limits","cli"],"author":{"name":"Aliyar"},"license":"MIT","_id":"@aliyar/claude-statusline@1.0.0","maintainers":[{"name":"aliyar","email":"aliyar@aliyar.com"}],"homepage":"https://github.com/aliyar/claude-statusline#readme","bugs":{"url":"https://github.com/aliyar/claude-statusline/issues"},"os":["darwin","linux"],"bin":{"claude-statusline":"bin/cli.js"},"dist":{"shasum":"2a5cba159fd63ce8b62eb4a81f1112d8ab8253ed","tarball":"https://registry.npmjs.org/@aliyar/claude-statusline/-/claude-statusline-1.0.0.tgz","fileCount":6,"integrity":"sha512-G1KCbsckxn0Yfw7LUD7UuzO3CZsLfwUnBPkFDURnbEZwl+ml3e96hN0EIea8YkpWYwASssTcFHsYWW/FfpQLOw==","signatures":[{"sig":"MEQCIGLNweCJ+nlgdlXXR4cKs2em/cuUdGzYALfnsoyQkfZiAiBlQktkJmBRlOO7c/40XqVKz6LUp8CdtoOVay3XiPWVzg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20168},"engines":{"node":">=16"},"gitHead":"e52482e1f2406c0f06824011f76f1d5ffa345abe","_npmUser":{"name":"aliyar","email":"aliyar@aliyar.com"},"repository":{"url":"git+https://github.com/aliyar/claude-statusline.git","type":"git"},"_npmVersion":"10.9.2","description":"Claude Code statusline showing context, session, weekly and per-model usage limits","directories":{},"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/claude-statusline_1.0.0_1786464024219_0.05028879096169114","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aliyar/claude-statusline","version":"1.1.0","description":"Claude Code statusline showing context, session, weekly and per-model usage limits, with every segment configurable","bin":{"claude-statusline":"bin/cli.js"},"keywords":["claude","claude-code","statusline","usage","rate-limits","cli"],"repository":{"type":"git","url":"git+https://github.com/aliyar/claude-statusline.git"},"homepage":"https://github.com/aliyar/claude-statusline#readme","bugs":{"url":"https://github.com/aliyar/claude-statusline/issues"},"license":"MIT","author":{"name":"Aliyar"},"os":["darwin","linux"],"engines":{"node":">=16"},"_id":"@aliyar/claude-statusline@1.1.0","gitHead":"604cffd5e7fbeb4589c290d425f65f78972b18b4","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-YmvduFKbBR1VKK2qA5f+bkDVipAagd/Dn+SHQpi7zafHQ8Tyzeen10ugutcVywPEVRaaGRwE4IpagRcvwxPDyA==","shasum":"7b83d8394924b288d830e48570426c59ebcf1b81","tarball":"https://registry.npmjs.org/@aliyar/claude-statusline/-/claude-statusline-1.1.0.tgz","fileCount":13,"unpackedSize":370887,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBPdWFABAJolRY+XqhFxdKY1YjwfNzbTnx+y3UtPLH76AiBkt2at3oxgitiPwCm9cX0C2lHRbQ/iAFO5z5Q3u1IeBg=="}]},"_npmUser":{"name":"aliyar","email":"aliyar@aliyar.com"},"directories":{},"maintainers":[{"name":"aliyar","email":"aliyar@aliyar.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-statusline_1.1.0_1786469735637_0.8868923953481671"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-11T16:00:24.020Z","modified":"2026-08-11T17:35:35.940Z","1.0.0":"2026-08-11T16:00:24.363Z","1.1.0":"2026-08-11T17:35:35.783Z"},"bugs":{"url":"https://github.com/aliyar/claude-statusline/issues"},"author":{"name":"Aliyar"},"license":"MIT","homepage":"https://github.com/aliyar/claude-statusline#readme","keywords":["claude","claude-code","statusline","usage","rate-limits","cli"],"repository":{"type":"git","url":"git+https://github.com/aliyar/claude-statusline.git"},"description":"Claude Code statusline showing context, session, weekly and per-model usage limits, with every segment configurable","maintainers":[{"name":"aliyar","email":"aliyar@aliyar.com"}],"readme":"# claude-statusline\n\nYour Claude Code usage limits, in the statusline, so you stop opening `/usage`\nto find out how much of the week you've burned.\n\n![The statusline showing model, project, context and usage limits](assets/statusline.png)\n\nTwo lines under the prompt. The first says where you are: model, reasoning\neffort, project, branch, elapsed time. The second says how much you have left:\n\n| | |\n|---|---|\n| `ctx` | how full the context window is |\n| `sess` | the 5-hour session limit, and when it resets |\n| `week` | the weekly limit across all models |\n| `Fable` | the weekly limit for that model specifically. The label comes from the server, so you see whichever model your plan meters |\n\nPercentages are muted below 70%, amber at 70-90%, red above 90%. Everything\nelse stays dim, so the only thing that catches your eye is a limit you should\nactually care about. If you'd rather see a meter, `STYLE=bar` and `STYLE=dot`\ndraw one next to each number.\n\n## Install\n\n```sh\nnpx @aliyar/claude-statusline\n```\n\nRestart Claude Code and it's there.\n\n## Uninstall\n\n```sh\nnpx @aliyar/claude-statusline --uninstall\n```\n\nThis restores whatever statusline you had before, script and setting both, and\nclears the cache. Your settings file is left alone, so a reinstall picks up\nwhere you left off.\n\n<sub>No Node? `curl -fsSL https://raw.githubusercontent.com/aliyar/claude-statusline/main/install.sh | bash`\ndoes the same, and takes the same flags after `bash -s --`.</sub>\n\nNeeds `jq` and `curl`. On macOS `brew install jq`, on Debian `sudo apt install jq`.\n\n## Settings\n\nEvery segment can be turned off, and the thresholds and colors changed:\n\n```sh\nnpx @aliyar/claude-statusline config                        # see everything\nnpx @aliyar/claude-statusline config set SHOW_ELAPSED off   # change one\nnpx @aliyar/claude-statusline config toggle SHOW_BRANCH     # flip an on/off\nnpx @aliyar/claude-statusline config get STYLE              # read one back\nnpx @aliyar/claude-statusline config reset                  # back to defaults\n```\n\nChanges apply on the next render. No restart.\n\nSettings live in `~/.claude/statusline.conf` as plain `KEY=value` lines, so you\ncan edit the file directly if you'd rather. Spacing, indentation, inline\ncomments, `ON`/`true`/`1` and Windows line endings are all understood, and the\nCLI reads the file through the statusline itself, so the two never disagree\nabout what is in effect.\n\n### What you can change\n\n| Key | Default | |\n|---|---|---|\n| `SHOW_MODEL` | `on` | the model name |\n| `SHOW_EFFORT` | `on` | the reasoning effort next to the model |\n| `SHOW_DIR` | `on` | the project directory |\n| `SHOW_BRANCH` | `on` | the git branch |\n| `SHOW_ELAPSED` | `on` | how long the session has been running |\n| `SHOW_CTX` | `on` | context window usage |\n| `SHOW_SESSION` | `on` | the 5-hour session limit |\n| `SHOW_WEEK` | `on` | the weekly limit across all models |\n| `SHOW_MODEL_WEEK` | `on` | the per-model weekly limit, the only one costing a request |\n| `SHOW_RESETS` | `on` | the countdown after each limit |\n| `STYLE` | `percent` | `percent`, `bar` or `dot` |\n| `BAR_WIDTH` | `5` | cells in the bar, when `STYLE=bar` |\n| `LINES` | `2` | `1` puts everything on a single line |\n| `WARN_AT` | `70` | percent at which a value turns amber |\n| `CRIT_AT` | `90` | percent at which it turns red |\n| `HIDE_BELOW` | `0` | hide a limit until it reaches this percent |\n| `COLOR_NORMAL` | `38;5;108` | ANSI color below `WARN_AT` |\n| `COLOR_WARN` | `33` | ANSI color from `WARN_AT` |\n| `COLOR_CRIT` | `31` | ANSI color from `CRIT_AT` |\n| `COLOR_MODEL` | `36` | ANSI color of the model name |\n| `COLOR_EMPTY` | `90` | ANSI color of the unfilled part of a meter |\n| `USAGE_TTL` | `900` | seconds between per-model refreshes, minimum 60 |\n| `USAGE_BACKOFF` | `1800` | seconds to wait after a failed refresh |\n\n### What each switch does\n\nThe top line, one setting off at a time:\n\n| | |\n|---|---|\n| default | `Opus 5 high · my-project (main) · 12m34s` |\n| `SHOW_MODEL=off` | `high · my-project (main) · 12m34s` |\n| `SHOW_EFFORT=off` | `Opus 5 · my-project (main) · 12m34s` |\n| `SHOW_DIR=off` | `Opus 5 high · main · 12m34s` |\n| `SHOW_BRANCH=off` | `Opus 5 high · my-project · 12m34s` |\n| `SHOW_ELAPSED=off` | `Opus 5 high · my-project (main)` |\n\nThe limits line, shown here as bare percentages so the rows stay short:\n\n| | |\n|---|---|\n| default | `ctx 34% · sess 42% 41m · week 78% 2d2h · Fable 23% 2d3h` |\n| `SHOW_CTX=off` | `sess 42% 41m · week 78% 2d2h · Fable 23% 2d3h` |\n| `SHOW_SESSION=off` | `ctx 34% · week 78% 2d2h · Fable 23% 2d3h` |\n| `SHOW_WEEK=off` | `ctx 34% · sess 42% 41m · Fable 23% 2d3h` |\n| `SHOW_MODEL_WEEK=off` | `ctx 34% · sess 42% 41m · week 78% 2d2h` |\n| `SHOW_RESETS=off` | `ctx 34% · sess 42% · week 78% · Fable 23%` |\n| `HIDE_BELOW=50` | `ctx 34% · week 78% 2d2h` |\n\n`HIDE_BELOW` is the one worth knowing about: limits stay invisible until they\npass the percent you set, so the statusline is quiet on a fresh week and speaks\nup when it matters.\n\nAnd how each limit is drawn:\n\n| | |\n|---|---|\n| `STYLE=percent` (default) | `ctx 34% · sess 42% 41m` |\n| `STYLE=bar` | `ctx ▬▬▬▬▬ 34% · sess ▬▬▬▬▬ 42% 41m` |\n| `STYLE=dot` | `ctx ●●●●● 34% · sess ●●●●● 42% 41m` |\n| `BAR_WIDTH=12` | `ctx ▬▬▬▬▬▬▬▬▬▬▬▬ 34% · sess ▬▬▬▬▬▬▬▬▬▬▬▬ 42% 41m` |\n\n`WARN_AT`, `CRIT_AT` and the `COLOR_*` keys only change color, which these\ntables can't show. Lower `WARN_AT` to be nagged earlier.\n\n### Arrangements\n\nEverything on one line, `LINES=1`:\n\n![Single line layout](assets/single-line.png)\n\nA meter next to each number, `STYLE=bar`:\n\n![Bar style](assets/bar.png)\n\nOr dots, `STYLE=dot`:\n\n![Dot style](assets/dot.png)\n\nStripped down: no countdowns, no branch, no effort:\n\n![Minimal layout](assets/minimal.png)\n\nOnly the limits, if the rest is already in your shell prompt:\n\n![Limits only](assets/limits-only.png)\n\nYou don't have to guess: `config` and every `config set` print a preview of the\nstatusline as it will look, using your real settings.\n\n![The config listing with a live preview](assets/config.png)\n\n## How it works\n\nClaude Code runs a statusline command on every render and hands it a JSON blob\non stdin. `ctx`, `sess` and `week` are all in that blob. No network call, and\nthey're current as of the last API response.\n\nThe per-model weekly window is not. For that one number the script calls\n`api.anthropic.com/api/oauth/usage`, the same endpoint the `/usage` screen\nuses, with the OAuth token Claude Code already stored on your machine.\n\nThat endpoint rate-limits, and a weekly number moves by a percent or two a day,\nso it is not polled. The response is cached in `~/.claude/cache/usage.json` and\nrefreshed at most every 15 minutes, in a background process the statusline never\nwaits on. A failed refresh backs off for 30 minutes, and the attempt is stamped\n*before* the request goes out, so a dead network can't spawn a request per\nrender, and several Claude Code windows share one budget rather than multiplying\nit. Turning `SHOW_MODEL_WEEK` off stops the request entirely.\n\nNothing is sent anywhere. The token is read at runtime from your keychain\n(macOS Keychain, `secret-tool`, or `~/.claude/.credentials.json`) and used for\nthat single request.\n\n### When something is missing\n\nThe script degrades one field at a time instead of failing:\n\n- **No `Fable` segment**: your plan has no per-model weekly window, or the\n  cache hasn't been written yet (first run, offline, or the endpoint is\n  rate-limiting). The other three keep working and it comes back on its own.\n- **No `sess` / `week`**: plan limits don't apply to your session (API key,\n  Bedrock, Vertex), so Claude Code doesn't send them.\n- **Malformed payload or config**: each value is checked against its type and\n  anything unusable keeps its default, so a typo costs you that one setting and\n  nothing else. The config is parsed, not sourced, so a stray line in it cannot\n  execute, and colours are validated before they reach an escape sequence.\n\nSanity check:\n\n```sh\nprintf '{}' | bash ~/.claude/statusline.sh\n```\n\nThat should print two lines and no errors.\n\n## Notes\n\nTested on macOS with Claude Code 2.1.x. The Linux paths are implemented but less\ntravelled, so issues are welcome.\n\n## Disclaimer\n\nAn unofficial personal project. Not affiliated with, endorsed by, or supported\nby Anthropic. \"Claude\" is Anthropic's trademark and is used here only to say\nwhat this tool works with.\n\nThe usage endpoint it reads is not a documented, stable API. It's what Claude\nCode calls internally, and it can change or stop working at any time. If it\ndoes, the per-model segment disappears and the rest keeps running.\n\nProvided as is, with no warranty of any kind, and with no liability for any\ndamage arising from its use. See the full terms in [LICENSE](LICENSE). You are\nresponsible for what you run on your machine; read the script before installing\nit. It is one bash file and it makes exactly one network request.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","readmeFilename":"README.md"}