Context Stats

September 2, 2026 · View on GitHub

Real-time context monitoring for Claude Code sessions. Know when you're in the Smart Zone, Dumb Zone, or Wrap Up Zone.

Context Zones

Context Stats tracks your context usage and warns you as performance degrades:

Zone	Context Used	Status	Message
🟢 Smart Zone	< 40%	Optimal	"You are in the smart zone"
🟡 Dumb Zone	40-80%	Degraded	"You are in the dumb zone - Dex Horthy says so"
🔴 Wrap Up Zone	> 80%	Critical	"Better to wrap up and start a new session"

Usage

The CLI uses an explicit action-based pattern: context-stats <session_id> <action> [options]

By default, context-stats runs in live monitoring mode:

# Live monitoring (default, refreshes every 2s)
context-stats <session_id> graph

# Custom refresh interval
context-stats <session_id> graph -w 5

# Show once and exit
context-stats <session_id> graph --no-watch

Graph Types

context-stats <session_id> graph --type delta       # Context growth per interaction (default)
context-stats <session_id> graph --type cumulative  # Total context usage over time
context-stats <session_id> graph --type both        # Show both graphs
context-stats <session_id> graph --type io          # Input/output token breakdown
context-stats <session_id> graph --type cache       # Cache creation/read tokens over time
context-stats <session_id> graph --type mi          # Model Intelligence over time
context-stats <session_id> graph --type all         # Show all graphs including I/O, cache, and MI

Diagnostic Dump

The explain action shows how context-stats interprets Claude Code's JSON context. Pipe any session JSON to stdin:

echo '{"model":{"display_name":"Opus"},...}' | context-stats explain

Output includes model info, workspace, context window breakdown with derived values (free tokens, autocompact buffer), cost, session metadata, vim/agent extensions, active config, and raw JSON.

Install Diagnostics

The doctor action checks the whole install without needing a live payload — useful precisely when the status line is missing, since explain requires stdin from a status line that already works.

context-stats doctor              # diagnose
context-stats doctor --fix        # also repair the settings.json wiring
context-stats doctor --fix --force  # replace a foreign statusLine

Checks performed:

Section	What it verifies
Entry points	`claude-statusline` and `context-stats` resolve on `PATH`
Statusline render	A synthetic payload renders in a sandboxed `HOME` (catches the crash-fallback line)
Claude Code settings	`~/.claude/settings.json` is valid JSON and `statusLine` points at a resolvable command
Runtime state	`~/.claude/statusline/` and the optional `statusline.conf`

--fix preserves every other settings key, backs the file up first, and is idempotent. Exit status is 0 when all checks pass, 1 otherwise.

Output

Context Stats (my-project • abc123def)

Context Growth Per Interaction
Max: 4,787  Min: 0  Points: 254

     4,787 │                                        ●
           │                                    ●   ▒
           │     ●●         ●                   ▒   ░
           │     ●                              ░   ░
     2,052 │     ░ ●    ● ●                     ░   ░ ●
           │     ░        ▒ ●  ● ●   ●  ●    ● ●░   ░ ▒   ●●
           │●●●●●●●●●●●●●●●●●●●●●●●●●●● ●●●●●●●●●●●●●●●●●●●●●●
         0 │●●●●●░▒●●●●▒▒●●▒░●●░▒▒▒▒▒●●●▒●▒●●▒●▒░●●▒●░●●▒●▒▒●▒
           └─────────────────────────────────────────────────
           10:40                11:29                12:01

Session Summary
----------------------------------------------------------------------------
  Context Remaining:   43,038/200,000 (21%)
  >>> DUMB ZONE <<< (You are in the dumb zone - Dex Horthy says so)
  Model Intelligence:  0.646  (Context pressure building, consider wrapping up)
    Context: 79% used

  Last Growth:         +2,500
  Input Tokens:        59,015
  Output Tokens:       43,429
  Cache Creation:      10,000
  Cache Read:          20,000
  Total Cost:          \$0.1234
  Model:               claude-sonnet-4-6
  Session Duration:    2h 29m

Powered by context-stats v1.25.0 - https://github.com/luongnv89/context-stats

Features

Live Monitoring: Automatic refresh every 2 seconds (configurable)
Zone Awareness: Color-coded status based on context usage
Model Intelligence (MI): Benchmark-calibrated score with per-model profiles (Opus/Sonnet/Haiku) showing how much the model has degraded
MI Over Time Graph: --type mi shows MI degradation trajectory across the session
Project Display: Shows project name and session ID
ASCII Graphs: Smooth area charts with gradient fills
Minimal Output: Clean summary with just the essential info

Graph Symbols

Symbol	Meaning
`●`	Trend line
`▒`	Medium fill (near line)
`░`	Light fill (area below)
`│`	Y-axis
`└─`	X-axis

Watch Mode

By default, context-stats runs in watch mode. Press Ctrl+C to exit.

Features:

Flicker-free updates: Uses cursor repositioning for smooth redraws
Live timestamp: Shows refresh indicator in header
Hidden cursor: Clean display without cursor blinking
Auto-adapt: Responds to terminal size changes

To disable watch mode and show graphs once:

context-stats <session_id> graph --no-watch

Data Source

Reads from ~/.claude/statusline/statusline.<session_id>.state files, automatically created by the status line script.

CLI Reference

context-stats <session_id> <action> [options]

ARGUMENTS:
    session_id    Required. The session ID to operate on.
    action        Required. The action to perform: graph, export, or explain.

ACTIONS:
    graph         Show live ASCII graphs of context usage
    export        Export session stats as a markdown report
    sessions      List recent sessions
    explain       Diagnostic dump of Claude Code's JSON context (reads from stdin)
    cache-warm    Keep the session prompt cache alive via a background heartbeat
    report        Cross-project token usage analytics
    doctor        Diagnose the install; --fix repairs the statusLine wiring

DOCTOR OPTIONS:
    --fix          Write the statusLine block into ~/.claude/settings.json
    --force        With --fix, replace a statusLine already set to something else

GRAPH OPTIONS:
    --type <type>  Graph type to display:
                   - delta: Context growth per interaction (default)
                   - cumulative: Total context usage over time
                   - io: Input/output tokens over time
                   - cache: Cache creation/read tokens over time
                            Includes a Cache TTL countdown (5m) based on last cache write
                   - mi: Model Intelligence over time
                   - both: Show cumulative and delta graphs
                   - all: Show all graphs including I/O, cache, and MI
    -w [interval]  Set refresh interval in seconds (default: 2)
    --no-watch     Show graphs once and exit (disable live monitoring)

EXPORT OPTIONS:
    --output FILE  Output file path (default: context-stats-<session>.md)

GLOBAL OPTIONS:
    --no-color     Disable color output
    --help         Show help message
    --version, -V  Show version and exit

EXAMPLES:
    context-stats abc123def graph
    context-stats abc123def graph --type cumulative
    context-stats abc123def graph -w 5
    context-stats abc123def export --output report.md
    echo '{"model":...}' | context-stats explain

The export report includes a summary table, timestamp-based Mermaid trend charts, a zone distribution pie chart, and a final context composition pie chart. Each chart includes a short explanation so the reader knows what to look for. The report begins with a copyable context-stats <session_id> export --output report.md command and an executive snapshot that folds the header metadata into one compact table so the report can be regenerated and scanned quickly. It also adds a Key Takeaways section and samples the cache activity line chart every 10 minutes when cache data is present. The charts use distinct colors and a manual legend because Mermaid xychart does not render a legend automatically.