Understand how you use Claude Code — and spend less doing it.

Three levels of analytics — live session awareness, per-session deep dives, and multi-week cost reports — so you can use Claude Code at its best and know exactly where your tokens go.

Get Started →

Three Levels of Stats

graph TD
    A["Claude Code session"] --> B["statusline script"]
    B --> D["Live status line · context zone · MI"]
    B --> C["Local CSV state"]

    C --> E["context-stats graph"]
    C --> F["context-stats export"]
    C --> G["context-stats report"]
    C --> H["context-stats sessions"]

    subgraph L1["Level 1 — Live"]
        D
        E
        H
    end

    subgraph L2["Level 2 — Session"]
        F
    end

    subgraph L3["Level 3 — Report"]
        G
    end

Level 1: Live Stats

Status Line

A single line in your Claude Code terminal updated on every refresh:

my-project | main [3] | 64,000 free (32.0%) | Code | MI:0.918 | +2,500 | Opus 4.6 | abc-123

When the terminal is narrow, lower-priority elements drop off in order — the project name is always shown.

Green status	Warning state

Context Zones

Five zones tell you exactly what to do next:

Thresholds are model-size-aware: 1M context models use absolute token counts; standard models use utilization ratios. Both are configurable.

Plan zone	Code zone	Dump zone

Model Intelligence (MI)

MI estimates how well Claude performs at the current fill level, calibrated from the MRCR v2 8-needle benchmark:

MI(u) = max(0, 1 - u^β)

Color-coded: green (>0.70), yellow (0.40–0.70), red (<0.40 — start a new session). Override with mi_curve_beta=1.5 in config.

Session Listing

Find and switch between active sessions:

context-stats sessions                  # Sessions from the last 5 minutes
context-stats sessions --minutes 30     # Widen the search window

Each session shows the project name, model, token count, and how recently it was active.

Live Graph Dashboard

context-stats graph                     # Context growth for the latest session
context-stats graph --type all          # All graphs
context-stats <session_id> graph        # Specific session

Auto-refreshes every 2 seconds. Pass -w 5 to slow down or --no-watch to show once.

Context growth	Cumulative graph	Cache activity

MI over time

Level 2: Session Report

Export a full deep-dive when you need to understand what happened in a specific session:

context-stats export --output report.md              # Latest session
context-stats <session_id> export --output report.md  # Specific session

Example output:

## Executive Snapshot
| Signal | Value | Why it matters |
|--------|-------|----------------|
| Model | claude-sonnet-4-6 | Which model produced the session |
| Duration | 59m 32s | Relate context growth to session length |
| Interactions | 135 | How active the session was |
| Final usage | 129,755 (64.9%) | How close the session got to the limit |
| Final zone | Dump zone | Whether the session stayed in a safe range |

See the full example in context-stats-export-output.md.

Cache Keep-Warm

Claude's prompt cache has a ~5 minute TTL. Keep it alive during pauses to avoid expensive cache misses:

context-stats cache-warm on 30m              # Latest session
context-stats <session_id> cache-warm on 30m  # Specific session

context-stats cache-warm off

Heartbeats fire every 4 minutes. Runs as a detached background process.

Level 3: Usage Report

Aggregate token usage and cost across all Claude Code projects and sessions:

context-stats report                     # All time
context-stats report --since-days 30     # Last 30 days
context-stats report --output report.md  # Write to file

The report is a Markdown file with these sections:

Example executive summary:

| Metric | Value |
|--------|-------|
| Report Period | 2026-03-08 → 2026-04-07 |
| Total Spend | \$6,413.24 |
| Total Sessions | 764 |
| Projects Analyzed | 58 |
| Cache Hit Ratio | 46.9% |
| Avg Session Cost | \$8.39 |
| Avg Session Duration | 2h 1m 8s |
| Most Expensive Project | agent-skill-manager (\$1,204.58, 18.8% of total) |

Cache reads cost ~10x less than input tokens. Sessions with low cache hit ratios are flagged in the optimization section so you know exactly where to cut costs.

Installation

pip install context-stats

uv pip install context-stats

Add to Claude Code settings:

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

Restart Claude Code. The status line, graph dashboard, session export, and report all read the same local state files.

Customization

# ~/.claude/statusline.conf
color_project_name=bright_cyan
color_branch_name=bright_magenta
color_mi_score=#ff9e64
show_mi=true
show_delta=true
token_detail=true

Full palette: 18 named colors + any #rrggbb hex.

cp examples/statusline.conf ~/.claude/statusline.conf

FAQ

Is it free? Yes. MIT licensed, zero external dependencies.

Does it send my data anywhere? No. Session data stays local in ~/.claude/statusline/. Analytics read from ~/.claude/projects/.

What runtimes does it support? Python 3.9+. Install via pip install context-stats.

Get Started

pip install context-stats

Read the docs · View export example · MIT Licensed

pip uninstall cc-statusline

pip install context-stats

License

MIT

claude-howto · asm · custats.info