cc-context-stats 1.15.1

Monitor your Claude Code session context in real-time - track token usage and never run out of context

See the current context zone and act fast

Status line zones for Claude Code, with the next task to do in each state.
Know when to keep coding, finish up, export the session, or restart fresh.

Current zone	Do this now
Planning	Keep planning and coding
Code-only	Finish the current task
Dump zone	Export the session and wrap up
ExDump	Start a new session now
Dead zone	Stop and restart fresh

claude-howto · asm · custats.info

Get Started →

---

What It Gives You

Need	What cc-context-stats shows
Statusline with context zone	Planning, Code-only, Dump, ExDump, and Dead at a glance
Export report with deep analysis	Snapshot, takeaways, charts, and timeline in Markdown
Live context monitoring	Current usage, MI, delta, cumulative growth, and cache activity

How It Works

graph LR
    A["Claude Code session"] --> B["Status line"]
    B --> C["Context zone + MI"]
    B --> D["Local session data"]
    D --> E["Live dashboard"]
    D --> F["Export report"]
    E --> G["Charts and timeline"]
    F --> H["Executive snapshot and deep analysis"]

1. Claude Code emits session state on every refresh.
2. The status line turns it into a zone, context, and MI signal.
3. The CLI reads local session data for live charts and exportable reports.
4. Everything stays local on disk.

Status Line

The status line is the fastest way to see whether a session is still healthy.

Zone	Meaning	What to do
Planning	Plenty of room left	Keep planning and coding
Code-only	Context is getting tighter	Finish the current task
Dump zone	Quality is slipping	Wrap up soon
ExDump	Near the hard limit	Start a new session
Dead zone	No useful headroom left	Stop and restart

Plan zone

Code zone

Dump zone

Live Monitoring

The CLI gives you the full session picture when the status line is not enough.

Chart	What it answers
Context trend	How fast the session is filling up
Model Intelligence	How quickly quality is degrading as context grows
Zone distribution	Where the session spent most of its time
Final context composition	How much of the final request was cache, reads, or new input
Cache activity trend	When cache creation and cache reads changed over time

Status bar view	Context growth	Cumulative graph

MI view	Status bar warning state

Each image shows a different slice of the same session:

• statusline-green.png shows the compact status line when the model is still sharp.
• 1.10-delta.png shows growth at each interaction.
• 1.10-cumulative.png shows overall context usage over time.
• 1.10.0-model-intelligence.png shows the MI view as context pressure rises.
• 1.10-statusline.png shows the warning state when the session is getting tight.

Export Report

Export a session when you want the timeline, charts, and summary in one Markdown file.

context-stats export <session_id> --output report.md

The report starts with the command that produced it, then folds the headline facts into an executive snapshot.

Section	What it contains
Generate	Copyable export command
Executive Snapshot	Session, project, model, duration, interactions, final usage, final zone, cache activity
Summary	Window size, final usage, token totals, cost, and final MI
Key Takeaways	The short read of what changed in the session
Visual Summary	Mermaid charts for context, zones, cache, and composition
Interaction Timeline	Per-interaction context, MI, and zone history

Example output:

# Context Stats Report

## Generate

    context-stats export 8bb55603-45b8-4bdf-aa04-d51366610b1a --output report.md

## Executive Snapshot
| Signal | Value | Why it matters |
|--------|-------|----------------|
| **Session** | `8bb55603-45b8-4bdf-aa04-d51366610b1a` | Link back to the source session |
| **Project** | **claude-howto** | Identify where the report came from |
| **Model** | **claude-sonnet-4-6** | See which model produced the session |
| **Duration** | **59m 32s** | Relate context growth to session length |
| **Interactions** | **135** | Show how active the session was |
| **Final usage** | **129,755** (64.9%) | See how close the session got to the limit |
| **Final zone** | **Dump zone** | See whether the session stayed in a safe range |

## Visual Summary
### Cache Activity Trend
Shows how cache creation and cache reads evolved over time so you can see when the session started reusing previous work versus building new cache.

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

Customization

Control what appears in the status line and how it looks.

# ~/.claude/statusline.conf
show_delta=true
show_session=true
show_mi=true
token_detail=true
color_project_name=cyan
color_branch_name=green
color_context_length=bold_white
color_mi_score=yellow
color_separator=dim

You can also change the order, switch colors, or copy one of the ready-made examples in examples/statusline.conf.

Installation and Configuration

Shell script

curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash

npm

npm install -g cc-context-stats

Python

pip install cc-context-stats

Or with uv:

uv pip install cc-context-stats

Claude Code setup

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

Optional full config

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

Restart Claude Code after installation. The status line and dashboard both read the same local session data.

Learn More

If you want to go deeper, these references are the next stop:

Resource	Best for
claude-howto	Learning Claude Code in depth
asm	Using a universal skill manager for AI agents
custats.info	Monitoring Claude Code usage limits on Mac Pro/Max plans

FAQ

Is it free? Yes. MIT licensed and zero dependencies.

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

What runtimes does it support? Shell, Python, and Node.js statusline implementations are included.

Get Started

curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash

Read the docs · View the export report example · MIT License

Documentation

• Installation Guide - Platform-specific setup (shell, pip, npm)
• Context Stats Guide - Detailed CLI usage guide
• Configuration Options - All settings explained
• Available Scripts - Script variants and features
• Model Intelligence - MI formula, per-model profiles, benchmark data
• Architecture - System design and components
• CSV Format - State file field specification
• Development - Dev setup, testing, and debugging
• Deployment - Publishing and release process
• Troubleshooting - Common issues and solutions
• Changelog - Version history

Contributing

Contributions are welcome. Read CONTRIBUTING.md for development setup, branching, and PR process.

This project follows the Contributor Covenant Code of Conduct.

How It Works (Architecture)

Context Stats hooks into Claude Code's status line feature to track token usage across your sessions. The Python and Node.js statusline scripts write state data to local CSV files, which the context-stats CLI reads to render live graphs. Data is stored locally in ~/.claude/statusline/ and never sent anywhere.

The statusline is implemented in three languages (Bash, Python, Node.js) so you can choose whichever runtime you have available. Claude Code invokes the statusline script via stdin JSON pipe — any implementation that reads JSON from stdin and writes formatted text to stdout works.

Migration from cc-statusline

If you were using the previous cc-statusline package:

pip uninstall cc-statusline

pip install cc-context-stats

The claude-statusline command still works. The main change is token-graph is now context-stats.

License

MIT