claude code statusline

A compact, information-dense status line for Claude Code that focuses on the two things that actually matter while you work: how full your context window is and how much of your plan you've used.

The headline feature: the context bar is colored by absolute token count with per-model thresholds, not by a flat percentage — because model quality degrades with the number of tokens in context (the "dumb zone"), and a fixed percentage means a wildly different token load on a 1M-window model vs a 200K one.

~/projects/foo │ Opus 4.8·xhigh │ ctx ██▌░░░░░░░ 25% 250k/1M │ $0.42 +156/-23 │ 5h 12%↻2h49m 7d 42%↻27h39m

What it shows

Left to right, separated by │:

• ~/projects/foo — current directory (relative to $HOME; long paths shorten to …/parent/leaf).
• Opus 4.8·xhigh — model and effort level (⚡ appended in fast mode).
• ctx ██▌░░░░░░░ 25% 250k/1M — context usage. The bar fills by % of the window (so you see headroom) but is colored by absolute tokens (so it warns about quality, not just space). Sub-block characters (▏▎▍▌▋▊▉) give precision even at low percentages.
• $0.42 +156/-23 — session cost in USD, plus lines added/removed (only shown when non-zero).
• 5h 12%↻2h49m 7d 42%↻27h39m — plan usage: the 5-hour and 7-day rate-limit windows, each with a percentage and a countdown to reset (↻).

All of this is rendered locally — the status line does not consume any plan tokens.

Color thresholds

Context bar — colored by absolute tokens, with the boundaries depending on the model (more capable models hold up better at longer context):

Model (matched by model.id substring)	🟢 → 🟡	🟡 → 🔴
fable	150k	350k
opus	150k	300k
sonnet	120k	250k
haiku	60k	120k
(unknown — fallback)	100k	200k

So on a 1M-window Opus the bar can be only ~20% full and already amber — exactly the right signal: you have window to spare, but you've loaded enough tokens that quality starts to slip.

These numbers are deliberately conservative heuristics (the goal is "never reach the dumb zone"); there's no published hard cliff. Tune them to taste — see below.

Plan windows (5h / 7d) use a simpler percentage scheme — 🟢 <50%, 🟡 <80%, 🔴 ≥80% — which is the right model for a quota.

Requirements

• Python 3 at /usr/bin/python3 (used to parse the status-line JSON robustly — no jq dependency). If your python3 lives elsewhere, edit the /usr/bin/python3 path near the top of statusline.sh.

Install

1. Copy the script somewhere stable, e.g.:

   mkdir -p ~/.claude
   curl -fsSL https://raw.githubusercontent.com/leofishman/claude-code-statusline/main/statusline.sh \
     -o ~/.claude/statusline.sh

2. Point Claude Code at it in ~/.claude/settings.json:

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

3. Start (or restart) Claude Code — the status line updates on activity.

Customizing

Open statusline.sh. The pieces you're most likely to touch:

• Per-model token thresholds — the CTX_THRESHOLDS tuple and CTX_DEFAULT. Each entry is (model-id substring, yellow, red).
• Bar width — the width=10 default on ctx_bar.
• Plan-window scheme — the by_pct function.
• Segments — comment out any parts.append(...) block to drop a segment (cost, lines changed, reset countdowns, etc.).

How the model knows what to draw

Claude Code pipes a JSON object to the status-line command on stdin. The fields this script reads:

• cwd, workspace.current_dir
• model.id, model.display_name, effort.level, fast_mode
• context_window.used_percentage, context_window.context_window_size
• cost.total_cost_usd, cost.total_lines_added, cost.total_lines_removed
• rate_limits.five_hour.{used_percentage,resets_at}, rate_limits.seven_day.{…}

License

Unlicense — public domain. Do whatever you want with it.