Field-Logic-Ltd/ClaudeStatsBar: A Claude Code status line showing how big your session has got and what the next turn costs before you type · GitHub

A Claude Code status line for the number that actually bites. Not how full the
context window is – Claude Code will tell you that in one command – but what the
next turn costs before you type a word, and when it is worth clearing rather
than finding the limit mid-task.

Opus 5 (1M context) · my-project · ▕██████░░░░░░▏ 486k · 49k/turn · 88t · 5h 15% ~162t left · 7d 3%
⚠  486k context — every turn now costs 49k before you type. /clear if you have switched task, /compact to keep going

Pure Python stdlib. No dependencies, no network, no transcript parsing, no proxy.
~25ms per render.

Building anything large with Claude means long sessions, and the session grows
underneath you whilst you work. By default nothing warns you what that is
costing, so the first sign is usually the limit itself – context exhausted, or
the rolling usage window gone, mid-task. The stronger the model the sooner that bites; Fable on a
big codebase will find the ceiling well before you expect it to.

This puts the size on screen whilst you work: how much context the session is
carrying, what the next turn costs before you type a word, and how much of the
5h and 7d windows is left. Enough to clear at a sensible boundary instead of
discovering the limit halfway through a refactor.

Sessions get far bigger than they feel. I measured two weeks of my own Claude
Code usage – 916 transcripts, 711 sessions, 57,451 API requests, 11.6 billion
tokens – and the sizes were not what I expected.

Everything I typed across 711 sessions was 1.3M tokens. The same sample re-read
11.1 billion tokens of context it was already carrying. Shorter prompts are
not the lever; session size is.

The reason is that the API is stateless. Every turn re-sends the entire
conversation – system prompt, instructions, and all prior turns – so what goes
on the wire grows with every message, whether you typed a paragraph or “yes”.

Because turn N re-sends turns 1..N-1, the context a session moves grows with
roughly the square of its length. Taking the medians above (42.8k start, 1.7k
a turn):

Less than half the context, for identical work – and no run gets near the
ceiling. The distribution agrees: the top 10% of sessions accounted for 71% of
every token moved.

The problem is that none of this is visible while you work, and unlike running
out of context window, it never self-limits. A session can sit at 480k for two
hundred turns, never trigger a compaction, and quietly burn millions of tokens.

That is the gap this fills.

git clone <this repo> ClaudeStatsBar && cd ClaudeStatsBar
./install.sh

The installer merges a statusLine entry into ~/.claude/settings.json,
backing the file up first and refusing to clobber an existing status line.

Open a new session, or run /hooks once to reload config.

Windows: "command": "python C:\\path\\to\\ClaudeStatsBar\\statsbar.py"
(the shebang and ~ expansion are POSIX-only).

Uninstall: delete the statusLine key.

ClaudeStatsBar is a statusLine command –
the documented mechanism, not a competing one. Claude Code will write you one:

/statusline show model name and context percentage with a progress bar

That is a real example from those docs, and it takes about ten seconds.
context_window.used_percentage arrives pre-calculated, so a bar is close to a
one-liner. If a progress bar is all you want, use that instead of this.

What this adds on top:

The first row is the one that matters. Percentage full tells you how much room
is left. It does not tell you what a message costs, and on a large window
those diverge badly: 486k of 1M reads as a comfortable 49% full whilst quietly
costing 49k a message – eleven times what the same question cost at the start of
the session. A percentage that says “half empty” is exactly the wrong signal at
that point.

A second warning line appears past 120k of context, or past 80% of the window.

A common misreading. The session grows by roughly 1.7k tokens a turn. The
49k is what you pay to put the existing 486k in front of the model again.

The consequence is counterintuitive: a one-word reply costs the same as a
complex request. “Just one more quick thing” at the end of a long session is
the worst-value message you can send.

Ranked by measured impact:

1. /clear between unrelated tasks – roughly 35%. The whole game, and free.
2. Fewer turns – roughly 20%. Each round-trip costs a full context sweep
   regardless of content. Batch tool calls; don’t re-read files.
3. Trim always-loaded instruction files – roughly 2%. Worth doing, not worth
   agonising over. In my sample only ~8.7k of a 42.8k session baseline was
   user-controlled; the rest is the harness.
4. Lower reasoning effort – roughly 2%. Output is only 9.9% of spend.

• Weights are a proxy. Costs use API list-price ratios (input 1x, cache write
  1.25x, cache read 0.1x, output 5x). The shape is right; treat 49k/turn as an
  index, not a bill. The rate-limit percentages are Anthropic’s own figures and
  need no such caveat.
• The multiplier needs a real baseline. It compares against the smallest
  context observed. Installed mid-session, it never saw the start, so it
  suppresses the ratio rather than printing a reassuring 1.0×.
• The burn projection needs five samples before it extrapolates, and
  re-baselines when the rolling 5-hour window resets.
• State lives in ~/.claude/.statusline-state/.json: the
  minimum context seen and the rate-limit baseline. Pruned after a week.
• It never breaks your session. Any exception prints an empty line and
  exits 0.
• Requires Claude Code 2.1.251+ for prompt_cache, 2.1.260+ for
  last_miss_cause. Older versions degrade gracefully – those fields simply
  do not render.

Developed by Field Logic.

The numbers throughout this README come from instrumenting our own daily Claude
Code use rather than from estimates – 916 transcripts and 11.6 billion tokens
over two weeks. If you find the figures differ materially on your workload, we
would like to hear about it.

MIT – see LICENSE.