Everything context-stats does, in detail.

Install in 60 seconds

Pure Python 3.9+, zero external dependencies. macOS, Linux, and Windows.

$ pip install context-stats
Successfully installed context-stats-1.24.0

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

{
  "statusLine": {
    "type": "command",
    "command": "claude-statusline"
  }
}

Start (or restart) Claude Code — your statusline is now live with context zone, Model Intelligence, and token delta on every prompt.

The commands

Run any of these any time — no session ID needed. Click Copy to paste into your terminal.

Level 1 — Live stats

The always-on statusline shows you, at a glance, the model, branch, and how much context window remains. Run context-stats graph any time to expand that into a full history.

The statusline

A single line rendered by Claude Code on every prompt:

meta-app | feat/85-catalog-visibility-toggle [3] | 132,944 (66.5%)·Code·ᗤ | 3.3 tok/s | Sonnet 4.6 | baaff3c8-2b25-458b-adcd-96ebdeb5125d

Each |-separated segment, left to right — closely related elements are grouped inside a segment with an unspaced · instead:

• meta-app — current project directory.
• feat/85-… [3] — git branch and uncommitted change count.
• 132,944 (66.5%) — remaining context window, colored by zone.
• Code — current context zone.
• ᗤ — pacman icon mirroring that zone, in the same color.
• 3.3 tok/s — rolling model throughput over the last 5 turns.
• Sonnet 4.6 — active model.
• baaff3c8-… — session ID.

Every segment is configurable via ~/.claude/statusline.conf. Optional extras — the MI score (show_mi), token delta (show_delta), and open PR number (show_pr) — slot in when enabled.

The graph dashboard

An on-demand ASCII view of cumulative usage, per-interval delta, and summary stats:

$ context-stats graph

Token Usage Graphs (Session: a3f9c12d…)

Cumulative Token Usage          Max: 53,250  Min: 25,148
53,250 ┤              ▄▄▟████████
37,192 ┤          ▗▄███████████
25,148 ┤▄▄▄▄▄▟████
       └─16:25───────16:27───────16:34

Token Delta Per Interval        Max: 25,148  Min: 0
25,148 ┤▌          ▖      ▟
10,778 ┤▌    ▖     █   ▖  █
     0 ┤█▁▁▁▂▂▁▁▁▁██▁▁▁███▁
       └─16:25───────16:27───────16:34

Summary Statistics
Current Tokens:   53,250
Session Duration: 8m
Data Points:      18
Average Delta:    2,958
Max Delta:        25,148
Total Growth:     28,102

Level 2 — Session deep dive

context-stats export writes a full Markdown report for a single session — summary, key takeaways, an interaction timeline (with MI and zone per step), context growth, and cache statistics — then prints a short confirmation:

$ context-stats export --output report.md

Exported to report.md
  Session:      a3f9c12d-98e0-4a40-8150-690985da46d4
  Interactions: 38
  Model:        claude-opus-4-5-20251101

The generated report.md opens with a summary table:

| Metric             | Value              |
|--------------------|--------------------|
| Context window     | 200,000 tokens
| Final usage        | 124,800 (62.4%)
| Total input tokens | 812,340
| Total output tokens| 793,218
| Session cost       | $51.7475
| Lines changed      | +1,123 / -887
| Final MI score     | 0.572 (Dump zone)

Level 3 — Multi-week report

context-stats report --since-days 30 aggregates across every session and project into a Markdown analytics report: an executive summary, per-model cost breakdown, and the top cost drivers. Here's a sample over 30 days:

# Token Usage Analytics Report
Generated with: context-stats report --since-days 30

| Metric             | Value     |
| Total Spend        | $1,842.35
| Total Sessions     | 312
| Projects Analyzed  | 18
| Cache Hit Ratio    | 41.2%
| Avg Session Cost   | $5.90
| Avg Session Duration | 3h 22m

## Model Usage Breakdown
| Model  | Sessions | Tokens      | Cost      | %     |
| opus   | 241      | 38,204,512  | $1512.30  | 82.1% |
| sonnet | 42       |  5,918,340  | $ 218.75  | 11.9% |
| haiku  | 29       |  5,102,876  | $ 111.30  |  6.0% |

### Top Cost Driver
a3f9c12d… · project-alpha · $87.40 · cache 5% · 2h 14m

Project names and session IDs are anonymized in the sample. See the full example report.

The five context zones

As your context fills, context-stats classifies the session into one of five zones — each with a single, clear action.

Zone names map to the internal keys Plan, Code, Dump, ExDump, and Dead.

Model Intelligence (MI)

MI is a single 0–1 score estimating how well the model can still reason given how full the context is. It's calibrated against the MRCR v2 8-needle benchmark, using the formula MI = max(0, 1 − u^β) where u is context utilization and β is a model-specific degradation curve (higher β = quality retained longer).

• ≥ 0.90 — green: full reasoning quality.
• 0.80 < MI < 0.90 — yellow: still solid; watch long chains.
• ≤ 0.80 — degrading; compaction below 0.60 is flagged lossy.

Cache keep-warm

Claude's prompt cache has a 5-minute TTL. Any pause longer than that silently evicts the cache — and your next prompt pays full price to rebuild it.

$ context-stats cache-warm on 30m

Cache-warm activated for session a3f9c12d….
Heartbeat every 4 minutes, auto-stops in 30m.

Compaction detection

When Claude Code compacts its context — a >50% drop in token count between interactions — context-stats detects it automatically and marks the point with a ▼ symbol. If MI was below 0.6 at that moment, the event is flagged as potentially lossy: key details may have been dropped from the summary, and you should verify anything important survived.

Configuration

Create ~/.claude/statusline.conf with simple key=value pairs. Customize 18 named colors (or hex codes), toggle MI display, token detail, delta tracking, session ID, motion effects, tok/s, and more.

# Display toggles
show_mi=true
show_delta=true
show_tps=true
show_session_id=false

# Colors (named or #hex)
color_zone_code=yellow
color_mi_high=#10B981

See the full reference in the configuration docs.

FAQ

Deeper reference

For internals and contribution, see the source-controlled docs: