Claude Code Context Stats

Never run out of context unexpectedly - monitor your session context in real-time.

Why Context Stats?

When working with Claude Code on complex tasks, you can easily burn through your context window without realizing it. As your context fills up, Claude's performance degrades - this is what Dex Horthy calls the "dumb zone". Context Stats helps you:

• Know your zone - See if you're in the Smart Zone, Dumb Zone, or Wrap Up Zone
• Track context usage - Real-time monitoring with live-updating graphs
• Get early warnings - Color-coded status alerts you before performance degrades
• Make informed decisions - Know when to start a fresh session

Context Zones

| Zone | Context Used | Status | What It Means | | ------------------- | ------------ | -------- | --------------------------------------------- | | 🟢 Smart Zone | < 40% | Optimal | Claude is performing at its best | | 🟡 Dumb Zone | 40-80% | Degraded | Context getting full, Claude may miss details | | 🔴 Wrap Up Zone | > 80% | Critical | Better to wrap up and start a new session |

Installation

pip install cc-context-stats

Or with uv:

uv pip install cc-context-stats

Quick Start

Real-Time Monitoring

Get your session ID from the status line (the last part after the pipe |), then run:

context-stats <session_id>

For example:

context-stats abc123def-456-789

This opens a live dashboard that refreshes every 2 seconds, showing:

• Your current project and session
• Context growth per interaction graph
• Your current zone status
• Remaining context percentage

Press Ctrl+C to exit.

Status Line Integration

Add to ~/.claude/settings.json:

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

Restart Claude Code to see real-time token stats in your status bar.

Context Stats CLI

context-stats                    # Live monitoring (default)
context-stats -w 5               # Custom refresh interval (5 seconds)
context-stats --no-watch         # Show once and exit
context-stats --type cumulative  # Show cumulative context usage
context-stats --type both        # Show both graphs
context-stats --type all         # Show all graphs including I/O
context-stats <session_id>       # View specific session

Output Example

Context Stats (my-project • abc123def)

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

Session Summary
----------------------------------------------------------------------------
  Context Remaining:   43,038/200,000 (21%)
  >>> DUMB ZONE <<< (You are in the dumb zone - Dex Horthy says so)

  Last Growth:         +2,500
  Input Tokens:        1,234
  Output Tokens:       567
  Lines Changed:       +45 / -12
  Total Cost:          $0.1234
  Model:               claude-sonnet-4-20250514
  Session Duration:    2h 29m

Status Line

The status line shows at-a-glance metrics in your Claude Code interface:

| Component | Description | | --------- | ----------------------------------------- | | Model | Current Claude model | | Context | Tokens used / remaining with color coding | | Delta | Token change since last update | | Git | Branch name and uncommitted changes | | Session | Session ID for correlation |

Configuration

Create ~/.claude/statusline.conf:

token_detail=true   # Show exact token counts (vs abbreviated like "12.5k")
show_delta=true     # Show token delta in status line
show_session=true   # Show session ID
autocompact=true    # Show autocompact buffer indicator

Shell Script Installation

For users who prefer shell scripts:

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

How It Works

Context Stats hooks into Claude Code's state files to track token usage across your sessions. Data is stored locally in ~/.claude/statusline/ and never sent anywhere.

Documentation

• Context Stats Guide - Detailed usage guide
• Configuration Options - All settings explained
• Installation Guide - Platform-specific setup
• Troubleshooting - Common issues
• Changelog - Version history

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.

Related

• Claude Code Documentation
• Dex Horthy on Context Windows - The "dumb zone" concept
• Blog: Building this project

License

MIT