Metadata-Version: 2.4
Name: cc-context-stats
Version: 1.5.1
Summary: Monitor your Claude Code session context in real-time - track token usage and never run out of context
Project-URL: Homepage, https://github.com/luongnv89/cc-context-stats
Project-URL: Documentation, https://github.com/luongnv89/cc-context-stats#readme
Project-URL: Repository, https://github.com/luongnv89/cc-context-stats
Project-URL: Issues, https://github.com/luongnv89/cc-context-stats/issues
Author-email: Nguyen Luong <luongnv89@gmail.com>
License: MIT
Keywords: claude,claude-code,cli,context,dashboard,monitoring,statusline,terminal,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo/logo-full.svg" alt="cc-context-stats" width="320"/>

  <h3>Know your zone. Ship with confidence.</h3>

  <p>Real-time context monitoring for Claude Code — so you always know when you're sharp and when to wrap up.</p>

[![PyPI version](https://badge.fury.io/py/cc-context-stats.svg)](https://pypi.org/project/cc-context-stats/)
[![npm version](https://badge.fury.io/js/cc-context-stats.svg)](https://www.npmjs.com/package/cc-context-stats)
[![PyPI Downloads](https://img.shields.io/pypi/dm/cc-context-stats)](https://pypi.org/project/cc-context-stats/)
[![npm Downloads](https://img.shields.io/npm/dm/cc-context-stats)](https://www.npmjs.com/package/cc-context-stats)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

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

![Context Stats](images/context-status-dumbzone.png)

## 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

### Shell Script

For the quickest setup:

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

### NPM

```bash
npm install -g cc-context-stats
```

Or with yarn:

```bash
yarn global add cc-context-stats
```

### Python

```bash
pip install cc-context-stats
```

Or with uv:

```bash
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:

```bash
context-stats <session_id>
```

For example:

```bash
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`:

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

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

## Context Stats CLI

```bash
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

![Status Line](images/statusline-detail.png)

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`:

```bash
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
```

## 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](docs/context-stats.md) - Detailed usage guide
- [Configuration Options](docs/configuration.md) - All settings explained
- [Installation Guide](docs/installation.md) - Platform-specific setup
- [Troubleshooting](docs/troubleshooting.md) - Common issues
- [Changelog](CHANGELOG.md) - Version history

## Migration from cc-statusline

If you were using the previous `cc-statusline` package:

```bash
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](https://docs.anthropic.com/en/docs/claude-code)
- [Blog: Building this project](https://medium.com/@luongnv89/closing-the-gap-between-mvp-and-production-with-feature-dev-an-official-plugin-from-anthropic-444e2f00a0ad)

## License

MIT
