Metadata-Version: 2.4
Name: cc-context-stats
Version: 1.17.0
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
License-File: LICENSE
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"/>

  <h1>Know your context zone. Act before Claude degrades.</h1>

[![PyPI version](https://img.shields.io/pypi/v/cc-context-stats)](https://pypi.org/project/cc-context-stats/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/cc-context-stats)](https://pypi.org/project/cc-context-stats/)
[![GitHub stars](https://img.shields.io/github/stars/luongnv89/cc-context-stats)](https://github.com/luongnv89/cc-context-stats)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Real-time context window monitoring for Claude Code. Five zones tell you exactly what to do next — keep coding, finish up, export your session, or restart.

[**Get Started →**](#installation)
</div>

---

## How It Works

```mermaid
graph LR
    A["Claude Code session"] --> B["Python statusline script"]
    B --> C["Context zone + MI score"]
    B --> D["Local CSV state file"]
    D --> E["Live graph dashboard"]
    D --> F["Session export report"]
    D --> G["Cross-project analytics"]
    E --> H["Delta · Cumulative · Cache · MI · I/O"]
    F --> I["Snapshot · Takeaways · Timeline · Charts"]
    G --> J["Cost · Tokens · Patterns · Sessions"]
```

1. Claude Code pipes session JSON to the Python statusline script on every refresh.
2. The script computes zone, Model Intelligence (MI) score, and displays a compact status line.
3. The CLI reads local state files for live charts, session reports, and cross-project analytics.
4. Everything stays local — `~/.claude/statusline/` for session state, `~/.claude/projects/` for analytics.

---

## Context Zones

Five zones with a clear action for each:

| Zone | Color | Meaning | Do this now |
|---|:---:|---|---|
| Planning | Green | Plenty of room | Keep planning and coding |
| Code-only | Yellow | Context tightening | Finish the current task, no new plans |
| Dump | Orange | Quality declining | Wrap up and prepare to export |
| ExDump | Dark red | Near hard limit | Start a new session |
| Dead | Gray | Exhausted | Stop — nothing productive left |

Thresholds are **model-size-aware**: 1M context models use absolute token counts (70k/100k/250k/275k); standard models use utilization ratios (40%/70%/75%). Both are configurable.

| Plan zone | Code zone | Dump zone |
|:---:|:---:|:---:|
| ![Plan zone](images/1.12.0/plan-zone.png) | ![Code zone](images/1.12.0/code-zone.png) | ![Dump zone](images/1.12.0/dump-zone.png) |

---

## Status Line

A single line in your Claude Code terminal that shows everything at a glance:

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

| Element | What it tells you |
|---|---|
| `my-project` | Current directory |
| `main [3]` | Git branch + uncommitted changes |
| `64,000 free (32.0%)` | Available tokens and utilization |
| `Code` | Current context zone (color-coded) |
| `MI:0.918` | Model Intelligence score — how sharp the model still is |
| `+2,500` | Tokens consumed since last refresh |
| `Opus 4.6` | Active model |
| `abc-123` | Session ID (double-click to copy) |

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

| Green status | Warning state |
|:---:|:---:|
| ![Green statusline](images/1.10/statusline-green.png) | ![Yellow statusline](images/1.10/1.10-statusline.png) |

### Customization

Every element has its own color key. Override per-property or set hex values:

```bash
# ~/.claude/statusline.conf
color_project_name=bright_cyan
color_branch_name=bright_magenta
color_mi_score=#ff9e64
color_green=#7dcfff
color_yellow=#e0af68
color_red=#f7768e
show_mi=true
show_delta=true
token_detail=true
```

Full palette: 18 named colors + any `#rrggbb` hex. Copy the annotated example to get started:

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

---

## Model Intelligence (MI)

MI estimates how well Claude performs at the current context fill level. It is a single number from 0.000 to 1.000 calibrated from the **MRCR v2 8-needle** long-context retrieval benchmark.

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

Each model family has a measured beta:

| Model | β | MI at 50% | MI at 75% |
|---|---|---|---|
| Opus 4.6 | 1.8 | 0.713 | 0.404 |
| Sonnet 4.6 | 1.5 | 0.646 | 0.350 |
| Haiku 4.5 | 1.2 | 0.565 | 0.292 |

Color-coded: **green** (>0.70, operating well), **yellow** (0.40–0.70, pressure building), **red** (<0.40, start new session). Override the curve with `mi_curve_beta=1.5` in config.

---

## Live Graph Dashboard

```bash
context-stats <session_id> graph               # Context growth per interaction (default)
context-stats <session_id> graph --type all    # All graphs
```

| Graph | What it answers |
|---|---|
| `delta` | How many tokens each interaction consumed |
| `cumulative` | Total context used over the session |
| `cache` | Cache creation and read tokens over time, with 5-min TTL countdown |
| `mi` | How MI degraded across the session |
| `io` | Input/output token breakdown |
| `both` | Cumulative + delta side by side |

Auto-refreshes every 2 seconds (flicker-free). Pass `-w 5` to slow it down or `--no-watch` to show once.

| Context growth | Cumulative graph | Cache activity |
|:---:|:---:|:---:|
| ![Delta graph](images/1.10/1.10-delta.png) | ![Cumulative graph](images/1.10/1.10-cumulative.png) | ![Cache graph](images/1.16.0/1.16-cache.png) |

| MI over time |
|:---:|
| ![Model Intelligence view](images/1.10/1.10.0-model-intelligence.png) |

---

## Cross-Project Analytics

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

```bash
context-stats report                     # Full analytics report (all time)
context-stats report --since-days 30     # Last 30 days only
context-stats report --output report.md  # Write to specific file
```

The report breaks down every token dollar spent across projects, models, and sessions:

```markdown
## Grand Totals

- Total Tokens: 128,254,398
  - Input: 19,574,606 · Output: 46,329,340
  - Cache Creation: 1,835,113 · Cache Read: 60,515,339
- Total Cost: $6,292.64
- Total Sessions: 751 across 59 projects
```

| Section | What you learn |
|---|---|
| Grand Totals | Total spend, token breakdown (input/output/cache), session count |
| Per-project breakdown | Which projects consume the most tokens and cost the most |
| Top sessions | Heaviest sessions per project — identify costly workflows |
| Cache efficiency | Cache read vs. cache creation ratio — high read ratio means good reuse |
| Token composition | How much of your spend is output (expensive) vs. cache reads (cheap) |

Cache reads cost ~10x less than input tokens. The report makes cache efficiency visible so you can optimize session structure.

---

## Session Export

Export a full session report when you need the timeline, charts, and analysis in one Markdown file:

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

| Section | Contents |
|---|---|
| Executive Snapshot | Model, project, duration, interactions, final zone, cache activity |
| Summary | Window size, token totals, cost, final MI |
| Key Takeaways | Short read of what changed |
| Visual Summary | Mermaid charts: context, zones, cache, composition |
| Interaction Timeline | Per-interaction context, MI, and zone history |

Example output:

```markdown
## Executive Snapshot
| Signal | Value | Why it matters |
|--------|-------|----------------|
| Session | `8bb55603-...` | Link back to 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 |
```

See the full example in [`context-stats-export-output.md`](context-stats-export-output.md).

---

## Cache Keep-Warm

Claude's prompt cache has a ~5 minute TTL. A background heartbeat prevents expensive cache misses during pauses.

```bash
context-stats <session_id> cache-warm on 30m
```

```bash
context-stats <session_id> cache-warm off
```

Heartbeats fire every 4 minutes (under the 5-min TTL). Runs as a detached background process on Unix, subprocess fallback on Windows.

---

## Installation

### pip

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

### uv

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

### Claude Code setup

Add to your Claude Code settings:

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

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

---

## 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 only. Install via `pip install cc-context-stats`.

---

## Get Started

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

[Read the docs](docs/installation.md) · [View export example](context-stats-export-output.md) · MIT Licensed

---

<details>
<summary><strong>Documentation</strong></summary>

- [Installation Guide](docs/installation.md) - Platform-specific setup
- [Context Stats Guide](docs/context-stats.md) - Detailed CLI usage guide
- [Configuration Options](docs/configuration.md) - All settings explained
- [Available Scripts](docs/scripts.md) - Script variants and features
- [Model Intelligence](docs/MODEL_INTELLIGENCE.md) - MI formula, per-model profiles, benchmark data
- [Architecture](docs/ARCHITECTURE.md) - System design and components
- [CSV Format](docs/CSV_FORMAT.md) - State file field specification
- [Development](docs/DEVELOPMENT.md) - Dev setup, testing, and debugging
- [Deployment](docs/DEPLOYMENT.md) - Publishing and release process
- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
- [Changelog](CHANGELOG.md) - Version history

</details>

<details>
<summary><strong>Contributing</strong></summary>

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branching, and PR process.

This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

</details>

<details>
<summary><strong>How It Works (Architecture)</strong></summary>

Context Stats hooks into Claude Code's status line feature to track token usage across sessions. The Python statusline script writes 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.

Claude Code invokes the statusline script via stdin JSON pipe — the script reads JSON from stdin and writes formatted text to stdout. The `report` subcommand reads Claude Code's own project logs from `~/.claude/projects/` to aggregate cross-session analytics.

</details>

<details>
<summary><strong>Migration from cc-statusline</strong></summary>

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

```bash
pip uninstall cc-statusline
```

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

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

</details>

## License

MIT

<p align="center">
  <a href="https://github.com/luongnv89/claude-howto">claude-howto</a> ·
  <a href="https://github.com/luongnv89/asm">asm</a> ·
  <a href="https://custats.info">custats.info</a>
</p>
