ClaudeStatsBar: your session is 486k deep and nothing told you

A Claude Code status line for the number nobody shows you - how big the session has got, 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.

---

Why this exists

Building anything large with Claude means long sessions, and the session grows underneath you whilst you work. Nothing shows you how big it has got, 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".

Why it compounds

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.

---

Install

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.

Manual

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "/absolute/path/to/ClaudeStatsBar/statsbar.py",
    "padding": 0
  }
}

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

Uninstall: delete the statusLine key.

---

Reading the bar

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

49k/turn is rent, not growth

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.

---

What to do about it

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.

---

Configuration

---

Notes and limitations

• 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/<session_id>.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.

---

About

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.

Licence

MIT - see LICENSE.