context-stats — Real-Time Context Monitoring for Claude Code

The Problem

Claude Code doesn't tell you
when you're in trouble.

By the time you notice output quality dropping, you've already wasted tokens — and money.

🪫

Invisible context drain

Each tool call, each file read quietly consumes context. You only find out when Claude starts looping or forgetting what it just wrote.

💸

Surprise API bills

A single runaway session can burn thousands of tokens before you realize the model is operating at 20% intelligence. No warning, no way to see trends.

📉

Silent model degradation

As context fills, Claude's effective intelligence drops along a measurable curve. Running at 30% context free isn't the same as running at 80% free.

🌀

No session history

After a session ends, you can't audit what happened — which interactions consumed the most tokens or why a particular task ballooned the context.

⏱️

Silent cache expiry

Claude's prompt cache has a 5-minute TTL. Every pause — a review, a coffee, a long think — silently evicts it. Your next request pays full token price again, with no warning and no way to tell.

🗜️

Lossy compaction, no warning

When Claude compacts its context at low model intelligence, the summary is lossy — key details get lost. You have no idea when it happened or how degraded the model was at the time.

What's New

v1.20.0 — Session discovery
& smarter defaults.

Stop hunting for session IDs. Three improvements that make the CLI feel instant, shipped April 2026.

📋

New `sessions` command

Run context-stats sessions to list recent sessions with project, model, token count, and last-activity time. Use --minutes N to widen the window.

⚡

Session ID is now optional

Every command — graph, report, export, cache-warm — auto-detects the most recent session when you omit the ID. Just run context-stats and go.

🛡

Stricter `sessions` validation

Missing, zero, or negative --minutes values now fail fast with a clear error instead of silently falling back to the default. Stray positionals are rejected too.

🧹

Modernized internals

Swapped legacy .replace("statusline.", "") and slice-based prefix stripping for Python 3.9+ removeprefix() across the CLI and state modules.

Full changelog on GitHub

The Solution

Three levels of analytics,
one lightweight tool.

From real-time awareness to multi-week cost reports — context-stats gives you complete visibility without ever leaving your terminal.

Level 1 — Live

Real-Time Statusline

Persistent status line in your Claude Code session — always on, zero friction.

Context zone with color-coded action signal + recommendation
Model Intelligence (MI) score per interaction
Token delta since last refresh
Git branch + project name
Live ASCII graph dashboard (context-stats graph)
Compaction event detection — ▼ markers show when & where Claude compacted
MI quality flag at compaction — warns if summary was created at low intelligence
Session listing — context-stats sessions shows recent sessions with metadata
Auto-detect latest session — no session ID needed for any command

Level 2 — Session

Per-Session Deep Dive

Export a detailed Markdown report for any completed session.

Executive snapshot with model, duration, interactions
Interaction timeline with per-step context + MI
Cache activity analysis (creation vs. read ratio)
Mermaid visual charts (context growth, zones, cache)
Cache keep-warm — heartbeat every 4 min to prevent costly cache misses details ↓

Level 3 — Report

Multi-Week Analytics

Understand cost trends, model mix, and efficiency across all your projects.

Cost breakdown by model family (Opus/Sonnet/Haiku)
Daily activity heatmaps
Cross-project efficiency metrics
41%+ cache hit ratio analysis
Cost optimization opportunities

Cache Optimization

Never let your prompt cache
expire mid-session.

Claude's prompt cache has a strict 5-minute TTL. One idle gap — a review pause, a coffee, a long think — silently evicts it. Your next request pays full token price, no warning.

✗ Without cache-warm

request ──── 5+ min idle ──── cache expired ── cache miss 💸

All context tokens re-processed at full price. No warning. No way to know it happened.

✓ With cache-warm on

request ── 4 min ── ♥ heartbeat ── 4 min ── ♥ heartbeat ── cache hit ✓

Cache stays alive. Next request reads cached tokens at ~10% the cost of uncached.

4 min heartbeat interval — always under the 5-min TTL

30 min default duration — configure with 1h, 90m, 3600s

background detached process — zero impact on your Claude session

63.4%

cache hit rate in a typical session
visible in every context-stats export report

cache-warm — keep the 5-min TTL alive

# Activate keep-warm for the latest session (no ID needed)

$ context-stats cache-warm on

Cache keep-warm started

Session: abc-1234

Interval: every 4 min

Duration: 30 min (expires 14:02)

PID: 12845

# Use a custom duration

$ context-stats cache-warm on 1h

Cache keep-warm started (1h)

# Stop the heartbeat early

$ context-stats cache-warm off

Cache keep-warm stopped

# Verify savings in your session report

$ context-stats export abc-1234

Cache read tokens: 49,120 (63.4% hit rate)

Cache savings: ~$0.087 (vs. uncached)

Real Output

What you actually see
in the terminal.

Four commands — each level of analytics, shown in full.

$ context-stats graph --type all

Context Stats (my-project • abc-1234)

Context usage — last 14 interactions

▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 88,000 free (44.0%)

╔══ Session: abc-1234 ═════════════════════╗

║ Model: Claude Opus 4.6 ║

║ Zone: ◆ Code-only ║

║ MI: 0.712 (context pressure) ║

║ Delta: +3,140 tokens this step ║

║ Cost: $0.2847 ║

╚══════════════════════════════════════════╝

Context Growth Per Interaction

Max: 8,420 Min: 0 Points: 14

8,420 │ ●

│ ● ▒

│ ● ● ▒ ░

│ ● ▒ ▒ ░ ● ░

2,810 │ ● ▒ ● ░ ░ ░ ▒ ░ ●

0 │●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

└──────────────────────────────────────────

10:12 11:08 12:30

Model Intelligence (MI) Over Time

Calibrated against MRCR v2 8-needle benchmark

1.00 │●●

0.90 │ ●●●

0.80 │ ●●●

0.70 │ ●●●

0.61 │ ●▼ compact (⚠ lossy)

1.00 │ ●●

0.80 │ ●●●

0.70 │ ●●

└──────────────────────────────────────────

step 1 ▼ compact step 14

Cache Activity

Creation ░ Read ▓

3│ ░░░░░░░░▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

2│ ░░░░░░░░░░░░▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

1│ ░░░░░░░░░░░░░░░░▓▓▓▓▓▓▓▓▓▓▓▓

$ context-stats sessions

Recent Sessions (last 5 min)

43b5ed93-e7a3-44d9-9d58-bd35911f17e9

my-project · claude-opus-4-6[1m] · 59K tokens · 1m 55s ago

66c00dcb-ebf6-4ed0-872e-23a60d715d60

api-server · claude-opus-4-6[1m] · 83K tokens · 4m 52s ago

Tip: context-stats 43b5ed93-e7a3-44d9-9d58-bd35911f17e9 graph

$ context-stats sessions --minutes 30

Recent Sessions (last 30 min)

43b5ed93-e7a3-44d9-9d58-bd35911f17e9

my-project · claude-opus-4-6[1m] · 59K tokens · 1m 55s ago

66c00dcb-ebf6-4ed0-872e-23a60d715d60

api-server · claude-opus-4-6[1m] · 83K tokens · 4m 52s ago

a1b2c3d4-e5f6-7890-abcd-ef1234567890

docs-site · claude-sonnet-4-6 · 142K tokens · 18m ago

Tip: context-stats 43b5ed93-e7a3-44d9-9d58-bd35911f17e9 graph

$ context-stats export abc-1234

Exported → session-abc-1234-2026-04-07.md

# Session Export — abc-1234

Generated: 2026-04-07 12:30:15 | context-stats v1.20.0

## Executive Summary

| Metric | Value |

|---------------------|------------------------|

| Model | Claude Opus 4.6 |

| Duration | 2h 18m 03s |

| Interactions | 14 |

| Peak Context Used | 112,000 / 200,000 (56%) |

| Final MI Score | 0.712 |

| Total Cost | $0.2847 |

| Cache Hit Ratio | 63.4% |

| Git Branch | feat/landing-page |

| Lines Changed | +284 / -41 |

## Interaction Timeline

|------|-------|--------------|---------|-------|---------|-------------|

| 1 | 10:12 | 18,240 | 181,760 | 0.982 | +18,240 | Planning |

| 2 | 10:24 | 24,610 | 175,390 | 0.971 | +6,370 | Planning |

| 5 | 10:58 | 61,340 | 138,660 | 0.894 | +8,100 | Planning |

| 8 | 11:22 | 84,920 | 115,080 | 0.812 | +5,280 | Code-only |

| 11 | 11:51 | 99,480 | 100,520 | 0.764 | +4,100 | Code-only |

| 14 | 12:30 | 112,000 | 88,000 | 0.712 | +3,140 | Code-only |

## Cache Analysis

Cache creation tokens: 28,400

Cache read tokens: 49,120 (63.4% hit rate)

Cache savings: ~$0.087 (vs. uncached)

```mermaid

pie title Cache Efficiency

"Cache Hit" : 63.4

"Fresh tokens" : 36.6

```

$ context-stats report --since-days 30

Analyzing 312 sessions across 18 projects...

# Token Usage Analytics Report

Generated: 2026-04-07 12:00:00 | context-stats v1.20.0

## Executive Summary (last 30 days)

| 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 14s |

| Most Expensive Session | a3f9c12d… ($87.40, 4.7%) |

| Most Expensive Project | project-alpha ($412.80, 22.4%) |

## Model Usage

|--------|----------|------------|---------|

| opus | 241 | $1,512.30 | 82.1% |

| sonnet | 42 | $218.75 | 11.9% |

| haiku | 29 | $111.30 | 6.0% |

## Weekly Spend Trend

W10 ███████████ $284.50 (48 sessions)

W11 ████████████████ $412.80 (74 sessions)

W12 █████████████ $348.20 (68 sessions)

W13 ████████████████████ $489.60 (82 sessions) ← peak

W14 ████████ $218.75 (31 sessions)

W15 ███ $88.50 (9 sessions)

## Top Projects by Cost

|---|-----------------|----------|-----------|----------|----------|

| 1 | project-alpha | 28 | $412.80 | 12.0% | opus |

| 2 | project-beta | 41 | $318.44 | 44.1% | opus |

| 3 | project-gamma | 35 | $264.17 | 38.4% | opus |

| 4 | project-delta | 27 | $198.53 | 49.2% | opus |

| 5 | project-epsilon | 22 | $187.62 | 31.0% | opus |

## Activity by Day of Week

Mon ############........ 52 sessions

Tue ##################... 68 sessions

Wed #################### 71 sessions ← busiest

Thu ############........ 48 sessions

Fri ###############..... 55 sessions

Sat ######.............. 22 sessions

Sun #######............. 26 sessions

Statusline Preview

What you see at every context zone.

The statusline updates live after each prompt. Here's exactly what it shows across all five zones.

Plan used < 50,000 · < 25% used

→ Plenty of room. Keep planning and coding freely.

Code 50,000 ≤ used < 80,000 · 25–40% used

→ Context tightening. Finish current task, skip exploration.

Dump 80,000 ≤ used < 140,000 · 40–70% used

→ Quality declining. Wrap up now, prepare to export context.

ExDump 140,000 ≤ used < 150,000 · 70–75% used

→ Near hard limit. Start a new session immediately.

Dead used ≥ 150,000 · ≥ 75% used

→ Context exhausted. Stop — nothing productive remains.

Get Started

Up and running in 60 seconds.

No config files. No sign-up. No data leaving your machine.

Install the package

One pip command, zero dependencies.

pip install context-stats

↓

Configure Claude Code

Add the status line to ~/.claude/settings.json.

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

↓

Start a session

Your status line is live. Context zone, MI score, token delta — all visible.

claude # or open Claude Code

↓

Explore & analyze

Use any of these commands any time — no session ID needed.

# Live ASCII dashboard — context, MI, cache, delta
context-stats graph

# List recent sessions (last 5 min by default)
context-stats sessions
context-stats sessions --minutes 30

# Keep the prompt cache alive during idle gaps
context-stats cache-warm on

# Export full session report to Markdown
context-stats export

# Multi-project analytics (last 30 days)
context-stats report --since-days 30

# Explain raw JSON from Claude Code stdin
context-stats explain

FAQ

Common questions

Does context-stats send any data to the cloud?

No. All session data stays local in ~/.claude/statusline/. There are no network requests, no telemetry, no external API calls of any kind. Your token usage and session data never leave your machine.

Will it slow down my Claude Code sessions?

No. The statusline script is a lightweight Python process that runs synchronously on each prompt. It reads from local CSV files and writes a single line to stdout. Typical execution is under 10ms. Git operations have a 5-second timeout to prevent hangs.

Does it work on Windows?

Yes. context-stats is pure Python 3.9+ with zero external dependencies and runs on macOS, Linux, and Windows. The statusline script and CLI both work across all platforms.

What Python version do I need?

Python 3.9 or higher. No external packages are required — context-stats uses only the Python standard library.

Can I customize the colors and display?

Yes. Create ~/.claude/statusline.conf with key=value pairs. You can customize 18 named colors or use hex codes, toggle MI display, token detail, delta tracking, session ID, motion effects, and more. Full configuration reference in the docs.

How accurate are the token counts?

context-stats reads the token data directly from Claude Code's status line JSON. It does not estimate — it reports the exact values that Claude Code provides. The MI score is calibrated against the MRCR v2 8-needle benchmark.

What's the difference between the statusline and the graph dashboard?

The statusline (claude-statusline) is the persistent one-line display shown by Claude Code at each prompt — it's always on. The graph dashboard (context-stats graph) is an on-demand ASCII chart view you run manually to see usage history, MI trends, cache activity, and delta per interaction over the session.

What is cache keep-warm and why do I need it?

Claude's prompt cache has a 5-minute TTL. Any pause longer than 5 minutes — a code review, a coffee break, a long think before replying — silently evicts the cache. Your next request then pays full token price instead of the cached rate (roughly 10× cheaper for large contexts). cache-warm solves this by running a lightweight background heartbeat every 4 minutes, keeping the cache alive for up to 30 minutes (or a custom duration you specify). Start it with context-stats <session_id> cache-warm on from a separate terminal, and stop it with cache-warm off. The savings show up automatically in your context-stats export report.

What is compaction detection and what does the ▼ marker mean?

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 in your graphs. This tells you exactly when and where compaction occurred during a session. More importantly, it also captures the MI (Model Intelligence) score at that moment — if MI was below 0.6 when compaction happened, it flags the event as potentially lossy. A lossy compaction means Claude was already degraded when it summarized, so the summary may have dropped important details. You'll see this as ▼ compact (MI 0.61 ⚠ lossy) in the graph output.

What are zone recommendations?

Each context zone (Planning, Code, Dump, ExDump, Dead) now comes with a brief actionable recommendation so you always know what to do next — no need to look anything up. For example, in the Dump zone you'll see "Wrap up task, export session, prepare new context". These appear inline in the statusline output and in graph annotations.

Know your context.
Act before Claude degrades.

Claude Code doesn't tell you
when you're in trouble.

Invisible context drain

Surprise API bills

Silent model degradation

No session history

Silent cache expiry

Lossy compaction, no warning

v1.20.0 — Session discovery
& smarter defaults.

New `sessions` command

Session ID is now optional

Stricter `sessions` validation

Modernized internals

Three levels of analytics,
one lightweight tool.

Real-Time Statusline

Per-Session Deep Dive

Multi-Week Analytics

Never let your prompt cache
expire mid-session.

What you actually see
in the terminal.

Every context state, visualized.

Five zones. One clear action each.

What you see at every context zone.

Up and running in 60 seconds.

Install the package

Configure Claude Code

Start a session

Explore & analyze

Common questions

Stop flying blind.
Start every session with a map.

Know your context. Act before Claude degrades.

Claude Code doesn't tell youwhen you're in trouble.

Invisible context drain

Surprise API bills

Silent model degradation

No session history

Silent cache expiry

Lossy compaction, no warning

v1.20.0 — Session discovery& smarter defaults.

New sessions command

Session ID is now optional

Stricter sessions validation

Modernized internals

Three levels of analytics,one lightweight tool.

Real-Time Statusline

Per-Session Deep Dive

Multi-Week Analytics

Never let your prompt cacheexpire mid-session.

What you actually seein the terminal.

Every context state, visualized.

Five zones. One clear action each.

What you see at every context zone.

Up and running in 60 seconds.

Install the package

Configure Claude Code

Start a session

Explore & analyze

Common questions

Stop flying blind.Start every session with a map.

Know your context.
Act before Claude degrades.

Claude Code doesn't tell you
when you're in trouble.

v1.20.0 — Session discovery
& smarter defaults.

New `sessions` command

Stricter `sessions` validation

Three levels of analytics,
one lightweight tool.

Never let your prompt cache
expire mid-session.

What you actually see
in the terminal.

Stop flying blind.
Start every session with a map.