claude-code-statusbar

A minimal, information-dense statusbar for Claude Code. Shows directory, git branch, model, context window, and rate-limit windows with time-until-reset.

Example

wealthuman main | Opus 4.7 (1M) | ctx 87% | 2h 33m · 76% | 5d 12h · 59%

Segment by segment:

| Segment | Source | Color | |---|---|---| | wealthuman | Current directory (basename) | Blue | | main | Git branch — main* with * if dirty | Green clean, magenta dirty | | Opus 4.7 (1M) | Model name (normalized, strips "Claude " prefix) | Blue | | ctx 87% | Context window remaining | Green >50%, yellow 20–50%, red ≤20% | | 2h 33m · 76% | 5-hour session window: time until reset · percent remaining | Green >40%, yellow 15–40%, red ≤15% | | 5d 12h · 59% | 7-day weekly window: time until reset · percent remaining | Same thresholds as 5h |

The rate-limit segments only appear for Claude Pro/Max subscribers and only after the first API response in the session. Values come from the rate_limits.*.used_percentage and rate_limits.*.resets_at fields Claude Code passes to the statusline script via stdin JSON — they refresh on both turn-start (when you submit a prompt) and turn-end (when the assistant finishes), so the countdown stays fresh without polling.

Install

Requires jq (brew install jq on macOS).

Option 1 — npx (recommended)

npx @robertoecf/claude-code-statusbar

Installs the script to ~/.claude/statusline-command.sh and merges the statusLine entry into ~/.claude/settings.json (without clobbering your other settings).

Option 2 — manual

curl -fsSL https://raw.githubusercontent.com/robertoecf/claude-code-statusbar/main/statusline-command.sh \
  -o ~/.claude/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

Then add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline-command.sh"
  }
}

Restart Claude Code. The statusbar appears at the bottom of the CLI.

Design choices

• No labels where the metric is obvious. 24% · 2h 33m not session: 24% resets in 2h 33m. Reading it is faster than reading prose.
• Remaining, not used. 76% = you have 76% left. Consistent with how people actually think about quota.
• Color follows health, not value. Green = you're fine, red = pay attention. ctx 5% is red because you're low, 5h · 5% is red because you're close to the limit.
• Middle dot (·) inside a segment, pipe (|) between segments. The pipe marks a hard boundary between unrelated facts (dir vs branch vs model). The dot pairs two facets of the same fact (time-left and quota-left of the same window).
• Graceful fallbacks. No rate_limits in the JSON (non-subscriber, pre-first-response): segment disappears. resets_at in the past: percent stays, time disappears.
• Readonly git. Uses --no-optional-locks so the statusline never touches .git/index.lock during reads.

Credits

Rate-limit visualization inspired by the OpenAI Codex CLI statusbar. Data source (stdin JSON per Claude Code's statusline docs).

License

MIT.