cc-context-stats 1.14.0 → 1.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +163 -330
- package/package.json +1 -1
- package/scripts/context-stats.sh +61 -1
- package/scripts/statusline.js +1 -1
package/README.md
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<img src="assets/logo/logo-full.svg" alt="cc-context-stats" width="320"/>
|
|
3
3
|
|
|
4
|
-
<h1>
|
|
5
|
-
|
|
6
|
-
<p><strong>Real-time model intelligence monitoring for Claude Code.</strong><br/>Know exactly when your model is at peak quality — and when it's time for a fresh session.</p>
|
|
4
|
+
<h1>See the current context zone and act fast</h1>
|
|
7
5
|
|
|
8
6
|
[](https://pypi.org/project/cc-context-stats/)
|
|
9
7
|
[](https://www.npmjs.com/package/cc-context-stats)
|
|
@@ -12,275 +10,192 @@
|
|
|
12
10
|
[](https://github.com/luongnv89/cc-context-stats)
|
|
13
11
|
[](https://opensource.org/licenses/MIT)
|
|
14
12
|
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
<p><strong>Status line zones for Claude Code, with the next task to do in each state.</strong><br/>Know when to keep coding, finish up, export the session, or restart fresh.</p>
|
|
14
|
+
|
|
15
|
+
<table>
|
|
16
|
+
<tr>
|
|
17
|
+
<th>Current zone</th>
|
|
18
|
+
<th>Do this now</th>
|
|
19
|
+
</tr>
|
|
20
|
+
<tr>
|
|
21
|
+
<td>Planning</td>
|
|
22
|
+
<td>Keep planning and coding</td>
|
|
23
|
+
</tr>
|
|
24
|
+
<tr>
|
|
25
|
+
<td>Code-only</td>
|
|
26
|
+
<td>Finish the current task</td>
|
|
27
|
+
</tr>
|
|
28
|
+
<tr>
|
|
29
|
+
<td>Dump zone</td>
|
|
30
|
+
<td>Export the session and wrap up</td>
|
|
31
|
+
</tr>
|
|
32
|
+
<tr>
|
|
33
|
+
<td>ExDump</td>
|
|
34
|
+
<td>Start a new session now</td>
|
|
35
|
+
</tr>
|
|
36
|
+
<tr>
|
|
37
|
+
<td>Dead zone</td>
|
|
38
|
+
<td>Stop and restart fresh</td>
|
|
39
|
+
</tr>
|
|
40
|
+
</table>
|
|
41
|
+
|
|
42
|
+
<p>
|
|
43
|
+
<a href="https://github.com/luongnv89/claude-howto">claude-howto</a> ·
|
|
44
|
+
<a href="https://github.com/luongnv89/asm">asm</a> ·
|
|
45
|
+
<a href="https://custats.info">custats.info</a>
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
[**Get Started →**](#installation-and-configuration)
|
|
17
49
|
</div>
|
|
18
50
|
|
|
19
51
|
---
|
|
20
52
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
## The Problem
|
|
53
|
+
## What It Gives You
|
|
24
54
|
|
|
25
|
-
|
|
55
|
+
| Need | What cc-context-stats shows |
|
|
56
|
+
|---|---|
|
|
57
|
+
| Statusline with context zone | Planning, Code-only, Dump, ExDump, and Dead at a glance |
|
|
58
|
+
| Export report with deep analysis | Snapshot, takeaways, charts, and timeline in Markdown |
|
|
59
|
+
| Live context monitoring | Current usage, MI, delta, cumulative growth, and cache activity |
|
|
26
60
|
|
|
27
|
-
|
|
28
|
-
- **You don't know when to start fresh.** Is 50% context usage safe? 70%? It depends on the model. Opus holds quality longer than Sonnet, which degrades faster than Haiku. Without data, you're guessing.
|
|
29
|
-
- **Wasted sessions cost real money.** Pushing through a degraded context means more back-and-forth, more corrections, more tokens burned on worse output. You pay more for less.
|
|
61
|
+
## How It Works
|
|
30
62
|
|
|
31
|
-
|
|
63
|
+
```mermaid
|
|
64
|
+
graph LR
|
|
65
|
+
A["Claude Code session"] --> B["Status line"]
|
|
66
|
+
B --> C["Context zone + MI"]
|
|
67
|
+
B --> D["Local session data"]
|
|
68
|
+
D --> E["Live dashboard"]
|
|
69
|
+
D --> F["Export report"]
|
|
70
|
+
E --> G["Charts and timeline"]
|
|
71
|
+
F --> H["Executive snapshot and deep analysis"]
|
|
72
|
+
```
|
|
32
73
|
|
|
33
|
-
|
|
74
|
+
1. Claude Code emits session state on every refresh.
|
|
75
|
+
2. The status line turns it into a zone, context, and MI signal.
|
|
76
|
+
3. The CLI reads local session data for live charts and exportable reports.
|
|
77
|
+
4. Everything stays local on disk.
|
|
34
78
|
|
|
35
|
-
|
|
79
|
+
## Status Line
|
|
36
80
|
|
|
37
|
-
|
|
38
|
-
- **Per-model awareness** — Opus (beta=1.8) retains quality longest. Sonnet (beta=1.5) is moderate. Haiku (beta=1.2) degrades earliest. MI reflects your actual model automatically.
|
|
39
|
-
- **Live dashboard** — ASCII graphs track context growth, MI degradation, and token I/O over time. Watch quality erode in real-time so you can make informed decisions.
|
|
40
|
-
- **Fully customizable** — Control the color of every element, toggle each component on/off, and use named colors or hex codes to match your terminal theme.
|
|
41
|
-
- **Context zones** — Five-state indicators tell you where you stand:
|
|
81
|
+
The status line is the fastest way to see whether a session is still healthy.
|
|
42
82
|
|
|
43
|
-
| Zone |
|
|
44
|
-
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
83
|
+
| Zone | Meaning | What to do |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| Planning | Plenty of room left | Keep planning and coding |
|
|
86
|
+
| Code-only | Context is getting tighter | Finish the current task |
|
|
87
|
+
| Dump zone | Quality is slipping | Wrap up soon |
|
|
88
|
+
| ExDump | Near the hard limit | Start a new session |
|
|
89
|
+
| Dead zone | No useful headroom left | Stop and restart |
|
|
50
90
|
|
|
51
|
-
**Plan zone**
|
|
91
|
+
**Plan zone**
|
|
52
92
|
|
|
53
93
|
|
|
54
94
|
|
|
55
|
-
**Code zone**
|
|
95
|
+
**Code zone**
|
|
56
96
|
|
|
57
97
|
|
|
58
98
|
|
|
59
|
-
**Dump zone**
|
|
99
|
+
**Dump zone**
|
|
60
100
|
|
|
61
101
|
|
|
62
102
|
|
|
63
|
-
|
|
103
|
+
## Live Monitoring
|
|
64
104
|
|
|
65
|
-
|
|
105
|
+
The CLI gives you the full session picture when the status line is not enough.
|
|
66
106
|
|
|
67
|
-
|
|
107
|
+
| Chart | What it answers |
|
|
108
|
+
|---|---|
|
|
109
|
+
| Context trend | How fast the session is filling up |
|
|
110
|
+
| Model Intelligence | How quickly quality is degrading as context grows |
|
|
111
|
+
| Zone distribution | Where the session spent most of its time |
|
|
112
|
+
| Final context composition | How much of the final request was cache, reads, or new input |
|
|
113
|
+
| Cache activity trend | When cache creation and cache reads changed over time |
|
|
68
114
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
B --> C["Status Bar Output<br/>colored, fitted to terminal width"]
|
|
73
|
-
B --> D["CSV State File<br/>~/.claude/statusline/"]
|
|
74
|
-
D --> E["context-stats CLI<br/>live ASCII dashboard"]
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
1. **Install** — One command: `pip install cc-context-stats` or `npm install -g cc-context-stats`
|
|
78
|
-
2. **Configure** — Add the statusline command to `~/.claude/settings.json` (two lines of JSON)
|
|
79
|
-
3. **Restart Claude Code** — MI score and context stats appear in your status bar immediately
|
|
80
|
-
4. **Monitor** — Run `context-stats <session_id>` for a live dashboard with graphs, zone status, and session summary
|
|
115
|
+
| Status bar view | Context growth | Cumulative graph |
|
|
116
|
+
|:---:|:---:|:---:|
|
|
117
|
+
|  |  |  |
|
|
81
118
|
|
|
82
|
-
|
|
|
119
|
+
| MI view | Status bar warning state |
|
|
83
120
|
|:---:|:---:|
|
|
84
|
-
|  |  |
|
|
89
|
-
|
|
90
|
-
[**See Full CLI Options →**](#context-stats-cli)
|
|
91
|
-
|
|
92
|
-
## Customization
|
|
93
|
-
|
|
94
|
-
Every element in the status line can be individually colored and toggled. Configuration lives in `~/.claude/statusline.conf` (created automatically on first run). See [`examples/statusline.conf`](examples/statusline.conf) for the canonical reference with all parameters documented.
|
|
95
|
-
|
|
96
|
-
### Status Line Anatomy
|
|
121
|
+
|  |  |
|
|
97
122
|
|
|
98
|
-
|
|
123
|
+
Each image shows a different slice of the same session:
|
|
99
124
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
(cyan) (green) (bold_white) (auto) (yellow) (dim) (dim) (dim)
|
|
106
|
-
```
|
|
125
|
+
- `statusline-green.png` shows the compact status line when the model is still sharp.
|
|
126
|
+
- `1.10-delta.png` shows growth at each interaction.
|
|
127
|
+
- `1.10-cumulative.png` shows overall context usage over time.
|
|
128
|
+
- `1.10.0-model-intelligence.png` shows the MI view as context pressure rises.
|
|
129
|
+
- `1.10-statusline.png` shows the warning state when the session is getting tight.
|
|
107
130
|
|
|
108
|
-
|
|
109
|
-
|:---:|---|---|---|---|
|
|
110
|
-
| 1 | Project directory | `color_project_name` | cyan | Current working directory |
|
|
111
|
-
| 2 | Git branch + changes | `color_branch_name` | green | Branch name and `[N]` uncommitted changes |
|
|
112
|
-
| 3 | Context remaining | `color_context_length` | bold_white | Tokens free + usage percentage |
|
|
113
|
-
| 4 | Zone indicator | `color_zone` | auto (zone color) | Plan / Code / Dump / ExDump / Dead |
|
|
114
|
-
| 5 | MI score | `color_mi_score` | yellow | Model Intelligence: `MI:0.918` |
|
|
115
|
-
| 6 | Token delta | `color_separator` | dim | Change since last refresh: `+2,500` |
|
|
116
|
-
| 7 | Model name | `color_separator` | dim | `Opus 4.6 (1M context)` |
|
|
117
|
-
| 8 | Session ID | `color_separator` | dim | Session identifier |
|
|
131
|
+
## Export Report
|
|
118
132
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
### Per-Element Color Control
|
|
122
|
-
|
|
123
|
-
Override any element's color independently. Per-property keys take precedence over base color slots.
|
|
133
|
+
Export a session when you want the timeline, charts, and summary in one Markdown file.
|
|
124
134
|
|
|
125
135
|
```bash
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
# Each element has its own color key
|
|
129
|
-
color_context_length=bold_white # The most critical info — tokens remaining
|
|
130
|
-
color_project_name=cyan # Which project you're working in
|
|
131
|
-
color_branch_name=green # Git branch at a glance
|
|
132
|
-
color_mi_score=yellow # Model Intelligence score
|
|
133
|
-
color_zone=default # Zone indicator (uses zone's own color by default)
|
|
134
|
-
color_separator=dim # Model name, delta, session ID
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### Base Color Slots (MI-Aware)
|
|
138
|
-
|
|
139
|
-
These control the automatic MI-based coloring of context tokens and act as fallbacks for per-property keys:
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
# Base MI color thresholds
|
|
143
|
-
color_green=#7dcfff # Used when MI > 0.70 (model is sharp)
|
|
144
|
-
color_yellow=bright_yellow # Used when MI 0.40–0.70 (quality degrading)
|
|
145
|
-
color_red=#f7768e # Used when MI < 0.40 (start a new session)
|
|
146
|
-
|
|
147
|
-
# Legacy element fallbacks (used if per-property key is not set)
|
|
148
|
-
color_blue=bright_blue # Fallback for color_project_name
|
|
149
|
-
color_magenta=#bb9af7 # Fallback for color_branch_name
|
|
150
|
-
color_cyan=bright_cyan # Git change count [N]
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
### Color Resolution Order
|
|
154
|
-
|
|
155
|
-
When rendering each element, the system checks colors in this order:
|
|
156
|
-
|
|
157
|
-
```mermaid
|
|
158
|
-
graph TD
|
|
159
|
-
A["Per-property key set?<br/>(e.g. color_project_name)"] -->|Yes| B["Use per-property color"]
|
|
160
|
-
A -->|No| C["Base color key set?<br/>(e.g. color_blue)"]
|
|
161
|
-
C -->|Yes| D["Use base color"]
|
|
162
|
-
C -->|No| E["Use built-in default"]
|
|
136
|
+
context-stats export <session_id> --output report.md
|
|
163
137
|
```
|
|
164
138
|
|
|
165
|
-
|
|
139
|
+
The report starts with the command that produced it, then folds the headline facts into an executive snapshot.
|
|
166
140
|
|
|
167
|
-
|
|
141
|
+
| Section | What it contains |
|
|
142
|
+
|---|---|
|
|
143
|
+
| Generate | Copyable export command |
|
|
144
|
+
| Executive Snapshot | Session, project, model, duration, interactions, final usage, final zone, cache activity |
|
|
145
|
+
| Summary | Window size, final usage, token totals, cost, and final MI |
|
|
146
|
+
| Key Takeaways | The short read of what changed in the session |
|
|
147
|
+
| Visual Summary | Mermaid charts for context, zones, cache, and composition |
|
|
148
|
+
| Interaction Timeline | Per-interaction context, MI, and zone history |
|
|
168
149
|
|
|
169
|
-
|
|
170
|
-
|---|---|---|
|
|
171
|
-
| Named colors | `red`, `green`, `cyan`, `white` | Standard 16-color terminal palette |
|
|
172
|
-
| Bright variants | `bright_red`, `bright_green`, `bright_cyan` | High-intensity versions |
|
|
173
|
-
| Special | `bold_white`, `dim` | Weight/opacity modifiers |
|
|
174
|
-
| Hex codes | `#7dcfff`, `#f7768e`, `#bb9af7` | 24-bit truecolor (requires terminal support) |
|
|
150
|
+
Example output:
|
|
175
151
|
|
|
176
|
-
|
|
152
|
+
```markdown
|
|
153
|
+
# Context Stats Report
|
|
177
154
|
|
|
178
|
-
|
|
155
|
+
## Generate
|
|
179
156
|
|
|
180
|
-
|
|
157
|
+
context-stats export 8bb55603-45b8-4bdf-aa04-d51366610b1a --output report.md
|
|
181
158
|
|
|
182
|
-
|
|
159
|
+
## Executive Snapshot
|
|
160
|
+
| Signal | Value | Why it matters |
|
|
161
|
+
|--------|-------|----------------|
|
|
162
|
+
| **Session** | `8bb55603-45b8-4bdf-aa04-d51366610b1a` | Link back to the source session |
|
|
163
|
+
| **Project** | **claude-howto** | Identify where the report came from |
|
|
164
|
+
| **Model** | **claude-sonnet-4-6** | See which model produced the session |
|
|
165
|
+
| **Duration** | **59m 32s** | Relate context growth to session length |
|
|
166
|
+
| **Interactions** | **135** | Show how active the session was |
|
|
167
|
+
| **Final usage** | **129,755** (64.9%) | See how close the session got to the limit |
|
|
168
|
+
| **Final zone** | **Dump zone** | See whether the session stayed in a safe range |
|
|
183
169
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
show_delta=true # Show token delta [+2,500] (default: true)
|
|
188
|
-
show_session=true # Show session ID (default: true)
|
|
189
|
-
show_mi=false # Show MI score (default: false — enable it!)
|
|
190
|
-
token_detail=true # Exact counts "64,000" vs abbreviated "64.0k" (default: true)
|
|
191
|
-
autocompact=true # Factor in autocompact buffer (default: true)
|
|
192
|
-
reduced_motion=false # Disable text animations (default: false)
|
|
170
|
+
## Visual Summary
|
|
171
|
+
### Cache Activity Trend
|
|
172
|
+
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.
|
|
193
173
|
```
|
|
194
174
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
**Tokyo Night theme** — dark purple/blue palette:
|
|
175
|
+
See the full example in [`context-stats-export-output.md`](context-stats-export-output.md).
|
|
198
176
|
|
|
199
|
-
|
|
200
|
-
# ~/.claude/statusline.conf
|
|
201
|
-
color_green=#7dcfff
|
|
202
|
-
color_yellow=#e0af68
|
|
203
|
-
color_red=#f7768e
|
|
204
|
-
color_project_name=#7aa2f7
|
|
205
|
-
color_branch_name=#bb9af7
|
|
206
|
-
color_context_length=bold_white
|
|
207
|
-
color_mi_score=#e0af68
|
|
208
|
-
color_separator=dim
|
|
209
|
-
show_mi=true
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
**High contrast** — maximum readability:
|
|
213
|
-
|
|
214
|
-
```bash
|
|
215
|
-
# ~/.claude/statusline.conf
|
|
216
|
-
color_project_name=bright_white
|
|
217
|
-
color_branch_name=bright_green
|
|
218
|
-
color_context_length=bold_white
|
|
219
|
-
color_mi_score=bright_yellow
|
|
220
|
-
color_separator=bright_black
|
|
221
|
-
color_green=bright_green
|
|
222
|
-
color_yellow=bright_yellow
|
|
223
|
-
color_red=bright_red
|
|
224
|
-
show_mi=true
|
|
225
|
-
```
|
|
177
|
+
## Customization
|
|
226
178
|
|
|
227
|
-
|
|
179
|
+
Control what appears in the status line and how it looks.
|
|
228
180
|
|
|
229
181
|
```bash
|
|
230
182
|
# ~/.claude/statusline.conf
|
|
231
|
-
show_delta=
|
|
232
|
-
show_session=
|
|
183
|
+
show_delta=true
|
|
184
|
+
show_session=true
|
|
233
185
|
show_mi=true
|
|
234
|
-
|
|
235
|
-
|
|
186
|
+
token_detail=true
|
|
187
|
+
color_project_name=cyan
|
|
188
|
+
color_branch_name=green
|
|
236
189
|
color_context_length=bold_white
|
|
237
190
|
color_mi_score=yellow
|
|
238
191
|
color_separator=dim
|
|
239
192
|
```
|
|
240
193
|
|
|
241
|
-
|
|
194
|
+
You can also change the order, switch colors, or copy one of the ready-made examples in `examples/statusline.conf`.
|
|
242
195
|
|
|
243
|
-
|
|
244
|
-
# ~/.claude/statusline.conf
|
|
245
|
-
color_project_name=white
|
|
246
|
-
color_branch_name=white
|
|
247
|
-
color_context_length=bold_white
|
|
248
|
-
color_mi_score=white
|
|
249
|
-
color_separator=dim
|
|
250
|
-
color_green=white
|
|
251
|
-
color_yellow=white
|
|
252
|
-
color_red=white
|
|
253
|
-
```
|
|
196
|
+
## Installation and Configuration
|
|
254
197
|
|
|
255
|
-
###
|
|
256
|
-
|
|
257
|
-
The MI degradation curve is model-specific by default. Override it for all models with `mi_curve_beta`:
|
|
258
|
-
|
|
259
|
-
```bash
|
|
260
|
-
# ~/.claude/statusline.conf
|
|
261
|
-
mi_curve_beta=0 # Auto-detect (default): Opus=1.8, Sonnet=1.5, Haiku=1.2
|
|
262
|
-
mi_curve_beta=1.5 # Force Sonnet-like curve for all models
|
|
263
|
-
mi_curve_beta=2.0 # More optimistic — quality retained longer
|
|
264
|
-
mi_curve_beta=1.0 # More pessimistic — warns earlier
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
Higher beta = the model retains quality longer before degrading. Lower beta = earlier warnings.
|
|
268
|
-
|
|
269
|
-
## Model Intelligence — The Science
|
|
270
|
-
|
|
271
|
-
MI is derived from `MI(u) = max(0, 1 - u^beta)` where `u` is context utilization and `beta` is a model-specific degradation rate calibrated against Anthropic's MRCR v2 8-needle long-context retrieval benchmark.
|
|
272
|
-
|
|
273
|
-
| Model | Beta | MI at 50% Context | MI at 75% Context | When to Worry |
|
|
274
|
-
|-------|------|-----------|-----------|---------------|
|
|
275
|
-
| Opus | 1.8 | 0.713 | 0.404 | ~60% used |
|
|
276
|
-
| Sonnet| 1.5 | 0.646 | 0.350 | ~50% used |
|
|
277
|
-
| Haiku | 1.2 | 0.565 | 0.292 | ~45% used |
|
|
278
|
-
|
|
279
|
-
The model is auto-detected from your session. See [Model Intelligence docs](docs/MODEL_INTELLIGENCE.md) for the full formula and benchmark data.
|
|
280
|
-
|
|
281
|
-
## Installation
|
|
282
|
-
|
|
283
|
-
### Shell Script (quickest)
|
|
198
|
+
### Shell script
|
|
284
199
|
|
|
285
200
|
```bash
|
|
286
201
|
curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
|
|
@@ -304,17 +219,8 @@ Or with uv:
|
|
|
304
219
|
uv pip install cc-context-stats
|
|
305
220
|
```
|
|
306
221
|
|
|
307
|
-
###
|
|
308
|
-
|
|
309
|
-
```bash
|
|
310
|
-
curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/scripts/check-install.sh | bash
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### Quick Start
|
|
314
|
-
|
|
315
|
-
Add to `~/.claude/settings.json`:
|
|
222
|
+
### Claude Code setup
|
|
316
223
|
|
|
317
|
-
**pip or npm install:**
|
|
318
224
|
```json
|
|
319
225
|
{
|
|
320
226
|
"statusLine": {
|
|
@@ -324,127 +230,42 @@ Add to `~/.claude/settings.json`:
|
|
|
324
230
|
}
|
|
325
231
|
```
|
|
326
232
|
|
|
327
|
-
|
|
328
|
-
```json
|
|
329
|
-
{
|
|
330
|
-
"statusLine": {
|
|
331
|
-
"type": "command",
|
|
332
|
-
"command": "~/.claude/statusline.sh"
|
|
333
|
-
}
|
|
334
|
-
}
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
**(Optional) Copy the example config for full customization:**
|
|
338
|
-
|
|
339
|
-
A default config is created automatically on first run. To start from the fully-documented example instead, copy it before launching:
|
|
233
|
+
### Optional full config
|
|
340
234
|
|
|
341
235
|
```bash
|
|
342
236
|
cp examples/statusline.conf ~/.claude/statusline.conf
|
|
343
237
|
```
|
|
344
238
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
Restart Claude Code. MI score and context stats appear in your status bar immediately.
|
|
348
|
-
|
|
349
|
-
### Real-Time Dashboard
|
|
239
|
+
Restart Claude Code after installation. The status line and dashboard both read the same local session data.
|
|
350
240
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
```bash
|
|
354
|
-
context-stats <session_id>
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
```
|
|
358
|
-
Context Stats (my-project • abc123def)
|
|
359
|
-
|
|
360
|
-
Context Growth Per Interaction
|
|
361
|
-
Max: 4,787 Min: 0 Points: 254
|
|
362
|
-
...graph...
|
|
363
|
-
|
|
364
|
-
Session Summary
|
|
365
|
-
----------------------------------------------------------------------------
|
|
366
|
-
Context Remaining: 43,038/200,000 (21%)
|
|
367
|
-
>>> DUMB ZONE <<< (You are in the dumb zone - Dex Horthy says so)
|
|
368
|
-
Model Intelligence: 0.646 (Context pressure building, consider wrapping up)
|
|
369
|
-
Context: 79% used
|
|
370
|
-
|
|
371
|
-
Last Growth: +2,500
|
|
372
|
-
Input Tokens: 1,234
|
|
373
|
-
Output Tokens: 567
|
|
374
|
-
Lines Changed: +45 / -12
|
|
375
|
-
Total Cost: $0.1234
|
|
376
|
-
Model: claude-sonnet-4-6
|
|
377
|
-
Session Duration: 2h 29m
|
|
378
|
-
```
|
|
241
|
+
## Learn More
|
|
379
242
|
|
|
380
|
-
|
|
243
|
+
If you want to go deeper, these references are the next stop:
|
|
381
244
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
context-stats --no-watch # Show once and exit
|
|
388
|
-
context-stats export # Export session stats as Markdown
|
|
389
|
-
context-stats export abc123def --output report.md
|
|
390
|
-
context-stats --type cumulative # Show cumulative context usage
|
|
391
|
-
context-stats --type both # Show both graphs
|
|
392
|
-
context-stats --type mi # Model Intelligence over time
|
|
393
|
-
context-stats --type all # Show all graphs including I/O and MI
|
|
394
|
-
context-stats <session_id> # View specific session
|
|
395
|
-
context-stats explain # Diagnostic dump (pipe JSON to stdin)
|
|
396
|
-
context-stats --version # Show version
|
|
397
|
-
```
|
|
245
|
+
| Resource | Best for |
|
|
246
|
+
|---|---|
|
|
247
|
+
| [claude-howto](https://github.com/luongnv89/claude-howto) | Learning Claude Code in depth |
|
|
248
|
+
| [asm](https://github.com/luongnv89/asm) | Using a universal skill manager for AI agents |
|
|
249
|
+
| [custats.info](https://custats.info) | Monitoring Claude Code usage limits on Mac Pro/Max plans |
|
|
398
250
|
|
|
399
251
|
## FAQ
|
|
400
252
|
|
|
401
253
|
**Is it free?**
|
|
402
|
-
Yes. MIT licensed
|
|
254
|
+
Yes. MIT licensed and zero dependencies.
|
|
403
255
|
|
|
404
256
|
**Does it send my data anywhere?**
|
|
405
|
-
No.
|
|
406
|
-
|
|
407
|
-
**Is it actively maintained?**
|
|
408
|
-
Very. 11 releases since January 2025, with MI per-model profiles, configurable colors, state rotation, and cross-implementation parity tests all shipped in the last few months.
|
|
409
|
-
|
|
410
|
-
**How does it compare to just watching the context counter?**
|
|
411
|
-
The raw context counter tells you how full the window is. MI tells you how much quality you've lost — which depends on the model. 50% context on Opus (MI: 0.713) is fine. 50% on Haiku (MI: 0.565) means you should start wrapping up. cc-context-stats gives you the nuance.
|
|
412
|
-
|
|
413
|
-
**Can I use it with Opus, Sonnet, and Haiku?**
|
|
414
|
-
Yes. MI auto-detects your model and applies the correct degradation curve. Each model has a calibrated beta value from benchmark data.
|
|
257
|
+
No. Session data stays local in `~/.claude/statusline/`.
|
|
415
258
|
|
|
416
259
|
**What runtimes does it support?**
|
|
417
|
-
Python
|
|
418
|
-
|
|
419
|
-
**How do I customize colors?**
|
|
420
|
-
Create `~/.claude/statusline.conf` with named colors or hex codes. See the [Customization section](#customization) above or the [full configuration docs](docs/configuration.md).
|
|
421
|
-
|
|
422
|
-
## Start Shipping with Confidence
|
|
260
|
+
Shell, Python, and Node.js statusline implementations are included.
|
|
423
261
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
cc-context-stats is MIT licensed, has zero dependencies, installs in one command, and works with any Claude Code setup. If you don't like it, `pip uninstall cc-context-stats` and it's gone.
|
|
427
|
-
|
|
428
|
-
[**Install cc-context-stats Now →**](#installation)
|
|
429
|
-
|
|
430
|
-
---
|
|
431
|
-
|
|
432
|
-
<details>
|
|
433
|
-
<summary><strong>Migration from cc-statusline</strong></summary>
|
|
434
|
-
|
|
435
|
-
If you were using the previous `cc-statusline` package:
|
|
262
|
+
## Get Started
|
|
436
263
|
|
|
437
264
|
```bash
|
|
438
|
-
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
```bash
|
|
442
|
-
pip install cc-context-stats
|
|
265
|
+
curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
|
|
443
266
|
```
|
|
444
267
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
</details>
|
|
268
|
+
[Read the docs](docs/installation.md) · [View the export report example](context-stats-export-output.md) · [MIT License](LICENSE)
|
|
448
269
|
|
|
449
270
|
<details>
|
|
450
271
|
<summary><strong>Documentation</strong></summary>
|
|
@@ -466,7 +287,7 @@ The `claude-statusline` command still works. The main change is `token-graph` is
|
|
|
466
287
|
<details>
|
|
467
288
|
<summary><strong>Contributing</strong></summary>
|
|
468
289
|
|
|
469
|
-
Contributions are welcome
|
|
290
|
+
Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branching, and PR process.
|
|
470
291
|
|
|
471
292
|
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
|
|
472
293
|
|
|
@@ -481,10 +302,22 @@ The statusline is implemented in three languages (Bash, Python, Node.js) so you
|
|
|
481
302
|
|
|
482
303
|
</details>
|
|
483
304
|
|
|
484
|
-
|
|
305
|
+
<details>
|
|
306
|
+
<summary><strong>Migration from cc-statusline</strong></summary>
|
|
307
|
+
|
|
308
|
+
If you were using the previous `cc-statusline` package:
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
pip uninstall cc-statusline
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
pip install cc-context-stats
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
The `claude-statusline` command still works. The main change is `token-graph` is now `context-stats`.
|
|
485
319
|
|
|
486
|
-
|
|
487
|
-
- [Blog: Building this project](https://medium.com/@luongnv89/closing-the-gap-between-mvp-and-production-with-feature-dev-an-official-plugin-from-anthropic-444e2f00a0ad)
|
|
320
|
+
</details>
|
|
488
321
|
|
|
489
322
|
## License
|
|
490
323
|
|
package/package.json
CHANGED
package/scripts/context-stats.sh
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
#
|
|
5
5
|
# Usage:
|
|
6
6
|
# context-stats.sh [session_id] [options]
|
|
7
|
+
# context-stats.sh export [session_id] [--output FILE]
|
|
8
|
+
# context-stats.sh explain
|
|
7
9
|
#
|
|
8
10
|
# Options:
|
|
9
11
|
# --type <cumulative|delta|both> Graph type to display (default: both)
|
|
@@ -17,12 +19,14 @@
|
|
|
17
19
|
# context-stats.sh --type delta # Only delta graph
|
|
18
20
|
# context-stats.sh --watch # Real-time mode (2s refresh)
|
|
19
21
|
# context-stats.sh -w 5 # Real-time mode (5s refresh)
|
|
22
|
+
# context-stats.sh export abc123 --output report.md
|
|
23
|
+
# echo '{...}' | context-stats.sh explain # Diagnostic JSON dump
|
|
20
24
|
|
|
21
25
|
# Note: This script is compatible with bash 3.2+ (macOS default)
|
|
22
26
|
|
|
23
27
|
# === CONFIGURATION ===
|
|
24
28
|
# shellcheck disable=SC2034
|
|
25
|
-
VERSION="1.
|
|
29
|
+
VERSION="1.15.1"
|
|
26
30
|
COMMIT_HASH="dev" # Will be replaced during installation
|
|
27
31
|
STATE_DIR=~/.claude/statusline
|
|
28
32
|
CONFIG_FILE=~/.claude/statusline.conf
|
|
@@ -72,6 +76,10 @@ USAGE:
|
|
|
72
76
|
ARGUMENTS:
|
|
73
77
|
session_id Optional session ID. If not provided, uses the latest session.
|
|
74
78
|
|
|
79
|
+
COMMANDS:
|
|
80
|
+
explain Diagnostic dump of Claude Code's JSON context (pipe JSON to stdin)
|
|
81
|
+
export Export session stats as a markdown report
|
|
82
|
+
|
|
75
83
|
OPTIONS:
|
|
76
84
|
--type <type> Graph type to display:
|
|
77
85
|
- delta: Context growth per interaction (default)
|
|
@@ -111,6 +119,13 @@ EXAMPLES:
|
|
|
111
119
|
# Output to file (no colors, single run)
|
|
112
120
|
context-stats.sh --no-watch --no-color > output.txt
|
|
113
121
|
|
|
122
|
+
# Diagnostic dump (pipe Claude Code JSON context)
|
|
123
|
+
echo '{"model":{"display_name":"Opus"},...}' | context-stats.sh explain
|
|
124
|
+
|
|
125
|
+
# Export session stats as markdown
|
|
126
|
+
context-stats.sh export
|
|
127
|
+
context-stats.sh export abc123def --output report.md
|
|
128
|
+
|
|
114
129
|
DATA SOURCE:
|
|
115
130
|
Reads token history from ~/.claude/statusline/statusline.<session_id>.state
|
|
116
131
|
|
|
@@ -969,6 +984,41 @@ load_config() {
|
|
|
969
984
|
fi
|
|
970
985
|
}
|
|
971
986
|
|
|
987
|
+
dispatch_python_subcommand() {
|
|
988
|
+
local subcommand=$1
|
|
989
|
+
shift
|
|
990
|
+
|
|
991
|
+
local py_cmd=""
|
|
992
|
+
if command -v python3 >/dev/null 2>&1; then
|
|
993
|
+
py_cmd="python3"
|
|
994
|
+
elif command -v python >/dev/null 2>&1; then
|
|
995
|
+
py_cmd="python"
|
|
996
|
+
else
|
|
997
|
+
error_exit "Python 3 is required for '$subcommand'."
|
|
998
|
+
fi
|
|
999
|
+
|
|
1000
|
+
# Check installed package is available and version matches this script
|
|
1001
|
+
local installed_version
|
|
1002
|
+
installed_version=$($py_cmd -c "import claude_statusline; print(claude_statusline.__version__)" 2>/dev/null || echo "")
|
|
1003
|
+
|
|
1004
|
+
if [ -z "$installed_version" ]; then
|
|
1005
|
+
echo -e "${RED}✗${RESET} Python package 'cc-context-stats' is not installed." >&2
|
|
1006
|
+
echo " Install it with: pip3 install cc-context-stats==$VERSION" >&2
|
|
1007
|
+
return 1
|
|
1008
|
+
fi
|
|
1009
|
+
|
|
1010
|
+
if [ "$installed_version" != "$VERSION" ]; then
|
|
1011
|
+
echo -e "${RED}✗${RESET} Python package version mismatch:" >&2
|
|
1012
|
+
echo " Script version: $VERSION" >&2
|
|
1013
|
+
echo " Package version: $installed_version" >&2
|
|
1014
|
+
echo " Run: pip3 install --upgrade cc-context-stats" >&2
|
|
1015
|
+
return 1
|
|
1016
|
+
fi
|
|
1017
|
+
|
|
1018
|
+
$py_cmd -m claude_statusline.cli.context_stats "$subcommand" "$@"
|
|
1019
|
+
return $?
|
|
1020
|
+
}
|
|
1021
|
+
|
|
972
1022
|
# Render graphs once
|
|
973
1023
|
render_once() {
|
|
974
1024
|
local state_file=$1
|
|
@@ -1104,6 +1154,16 @@ run_watch_mode() {
|
|
|
1104
1154
|
}
|
|
1105
1155
|
|
|
1106
1156
|
main() {
|
|
1157
|
+
# Delegate non-graph subcommands to the Python CLI implementation.
|
|
1158
|
+
case "${1:-}" in
|
|
1159
|
+
explain|export)
|
|
1160
|
+
local subcommand=$1
|
|
1161
|
+
shift
|
|
1162
|
+
dispatch_python_subcommand "$subcommand" "$@"
|
|
1163
|
+
return $?
|
|
1164
|
+
;;
|
|
1165
|
+
esac
|
|
1166
|
+
|
|
1107
1167
|
parse_args "$@"
|
|
1108
1168
|
init_colors
|
|
1109
1169
|
get_terminal_dimensions
|