claude-token-saver 2.16.0 → 2.18.0
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.en.md +131 -193
- package/README.md +123 -186
- package/bin/cli.js +21 -1
- package/package.json +1 -1
- package/src/advice.js +49 -34
- package/src/cost.js +16 -1
- package/src/demo.js +11 -4
- package/src/formatters/statusline.js +29 -8
- package/src/formatters/table.js +2 -2
- package/src/history.js +5 -1
package/README.en.md
CHANGED
|
@@ -7,168 +7,92 @@
|
|
|
7
7
|
|
|
8
8
|
# claude-token-saver
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
**Diagnose and save Claude Code tokens from a single statusline.** Zero dependencies, one-line install.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
```bash
|
|
13
|
+
npm i -g claude-token-saver # postinstall auto-registers the statusline + Skill
|
|
14
|
+
```
|
|
13
15
|
|
|
14
16
|
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
## Cost-savings report — harness + ratchet adoption
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
The recently added **harness 5/5 + ratchet** features applied to the author's own Claude Code work, normalized **per user message** (cutoff 2026-05-02, Opus 4.7 pricing):
|
|
23
|
-
|
|
24
|
-
| metric | before (7d / 739 msgs) | after (2d / 157 msgs) | Δ |
|
|
25
|
-
|---|---:|---:|---:|
|
|
26
|
-
| cost / user message | $2.345 | $1.910 | **−18.6%** |
|
|
27
|
-
| output tokens / user message | 7,391 | 6,052 | −18.1% |
|
|
28
|
-
| assistant turns / user message | 9.73 | 8.83 | −9.2% |
|
|
29
|
-
| tool calls / user message | 5.72 | 5.25 | −8.2% |
|
|
30
|
-
|
|
31
|
-
Same request resolved in fewer round-trips → first-try success rate up. Looks like the effect of PEV + Structured Task forcing one-shot delivery.
|
|
32
|
-
|
|
33
|
-
### Why cache hit rate isn't in this measurement — Max vs Pro
|
|
34
|
-
|
|
35
|
-
**Cache hit rate improvement isn't included** in this comparison. The author is on the Max plan with a 1-hour cache TTL and stays inside the same context for the full hour, so the hit rate had already converged near ~98% with little headroom left. **Pro-plan users (5-minute TTL)** see caches expire frequently, so the harness "one-shot" pattern + a "handoff right before TTL expiry" workflow likely **lifts hit rate itself**.
|
|
18
|
+
## ⚡ Why — the 30-second pitch
|
|
36
19
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
20
|
+
| | |
|
|
21
|
+
|---|---|
|
|
22
|
+
| 💸 **−18.6% measured cost** | Cost per user message $2.35 → $1.91 after adopting harness+ratchet (author's logs, [details](#real-world-impact--beforeafter-report)) |
|
|
23
|
+
| 🚨 **No surprise rate limits** | Instant warning when the 5H/7D window hits 90% + `handoff` to back up your work |
|
|
24
|
+
| 🧠 **Cache waste detection** | Hit rate, TTL countdown, 1M-context detection — token spikes diagnosed with issue codes |
|
|
25
|
+
| 🅷 **Stop repeating mistakes** | Recurring errors get promoted to ratchet rules — auto-applied from the next session |
|
|
26
|
+
| 💰 **Savings made visible** | See what prompt caching saved you, live (`💰 Cache saved $2.1K`) |
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
📺 [Launch Short (60s)](https://www.youtube.com/shorts/RaD8qMsPTnA)
|
|
42
29
|
|
|
43
30
|
---
|
|
44
31
|
|
|
45
|
-
##
|
|
46
|
-
|
|
47
|
-
### Prerequisite — Node.js (≥ 18)
|
|
32
|
+
## Getting started
|
|
48
33
|
|
|
49
|
-
`
|
|
34
|
+
**Prerequisite:** Node.js ≥ 18 (`node -v` · macOS `brew install node` · Windows `winget install OpenJS.NodeJS.LTS` · Linux/WSL: [nvm](https://github.com/nvm-sh/nvm) recommended)
|
|
50
35
|
|
|
51
36
|
```bash
|
|
52
|
-
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
If not, install it:
|
|
56
|
-
|
|
57
|
-
- **macOS** — `brew install node` (Homebrew) or the installer at [nodejs.org](https://nodejs.org/)
|
|
58
|
-
- **Windows** — [nodejs.org](https://nodejs.org/) LTS installer, or `winget install OpenJS.NodeJS.LTS`
|
|
59
|
-
- **Linux / WSL** — your distro's package manager (`apt install nodejs npm`, etc.) or — recommended — [nvm](https://github.com/nvm-sh/nvm) for a user-scoped install (no sudo)
|
|
60
|
-
|
|
61
|
-
> Avoid installing globally with `sudo`. The postinstall hook writes the Skill into root's `~/.claude` instead of yours, and auto-registration silently misses. Use nvm/fnm/Volta, or set `npm config set prefix ~/.npm-global` first.
|
|
62
|
-
|
|
63
|
-
### Install claude-token-saver
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
# (existing users) remove the old package
|
|
67
|
-
npm uninstall -g claude-cache-monitor
|
|
68
|
-
|
|
69
|
-
# install — the postinstall hook auto-registers the Skill and statusline
|
|
37
|
+
npm uninstall -g claude-cache-monitor # (previous-package users only)
|
|
70
38
|
npm i -g claude-token-saver
|
|
71
39
|
```
|
|
72
40
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
If postinstall was skipped (e.g. `--ignore-scripts`, sudo, or sandboxed installs), register manually:
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
claude-token-saver install
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## Claude Code statusline
|
|
41
|
+
The statusline appears at the bottom of Claude Code right away. If auto-registration was skipped (`--ignore-scripts`, sudo, sandboxed installs), run `claude-token-saver install`.
|
|
82
42
|
|
|
83
|
-
|
|
43
|
+
> ⚠️ Avoid `sudo` global installs — the Skill lands in root's `~/.claude` instead of yours. Use nvm/fnm/Volta or `npm config set prefix ~/.npm-global`.
|
|
84
44
|
|
|
85
|
-
|
|
86
|
-
🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
Segments — `🤖 model` · `🧠 cache hit rate` · `⏳ TTL countdown` · `✦ current` (5-hour window) · `📅 weekly` (7-day window) · `📦 context` · `💰 cumulative savings` · `last <window>`.
|
|
90
|
-
|
|
91
|
-
When excessive token usage is detected, a warning chip is prepended at the front of the statusline:
|
|
45
|
+
## Reading the statusline
|
|
92
46
|
|
|
93
47
|
```
|
|
94
|
-
|
|
48
|
+
🤖 Opus 4.8 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
|
|
95
49
|
```
|
|
96
50
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
"type": "command",
|
|
107
|
-
"command": "claude-token-saver --statusline --icon",
|
|
108
|
-
"refreshInterval": 5
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
`refreshInterval: 5` keeps the TTL countdown ticking while idle. For Windows PowerShell see `examples/statusline-command.ps1`.
|
|
114
|
-
|
|
115
|
-
## When a warning chip appears — Skill workflow
|
|
116
|
-
|
|
117
|
-
The Claude Code Skill registered at install time bridges "warning chip → remediation":
|
|
118
|
-
|
|
119
|
-
1. **A risk chip appears in the statusline** — e.g. `🚨 5H 94%`, `⚠ Cache miss`, `⚠ 1M ON`.
|
|
120
|
-
2. **Run `/claude-token-saver`** — invoking the Skill via slash is the simplest path. Mentioning the chip wording to Claude ("5H cap is up", "cache miss showing", "why is 1M context on?") auto-activates the same Skill.
|
|
121
|
-
3. **The Skill fetches the remediation.** Internally it runs `claude-token-saver last` to surface the most recent warning + root-cause code + step-by-step fix, and recommends `claude-token-saver handoff` when a cap is imminent.
|
|
122
|
-
4. **Run manually any time.** `claude-token-saver last` (latest event), `claude-token-saver history` (last 7 days of transitions), `claude-token-saver handoff` (back up before a cap blocks you) — same information, on demand.
|
|
123
|
-
|
|
124
|
-
> v2.6.0 folded the legacy `/token-monitor` slash command into this Skill. On older installs, run `claude-token-saver install` once and the legacy file is cleaned up automatically.
|
|
125
|
-
|
|
126
|
-
## One-shot report
|
|
51
|
+
| Segment | Meaning |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `🤖` | Active model |
|
|
54
|
+
| `🅷 5/5` | Harness principle score ([Harness mode](#-harness-mode)) |
|
|
55
|
+
| `🧠` | Cache hit rate (green at 85%+) |
|
|
56
|
+
| `⏳` | Cache TTL countdown — send a message before expiry to keep the cache warm |
|
|
57
|
+
| `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
|
|
58
|
+
| `📦` | Context usage (e.g. `Ctx 68% of 1M`) — colored by fill. Current models default to 1M with no premium, but token volume itself drives per-turn cost and 5H/7D burn |
|
|
59
|
+
| `💰` | Cumulative savings from prompt caching |
|
|
127
60
|
|
|
128
|
-
|
|
61
|
+
When something is wrong, a **warning chip leads the line**:
|
|
129
62
|
|
|
130
63
|
```
|
|
131
|
-
|
|
132
|
-
(claude-token-saver v2.9.0)
|
|
133
|
-
══════════════════════════════════════════════════
|
|
134
|
-
|
|
135
|
-
Context window: 200k ✓ 200k context (standard)
|
|
136
|
-
Sessions: 11 | API calls: 578 | Cache hit rate: 98.0%
|
|
137
|
-
TTL Breakdown / Cost Impact / Daily Trend …
|
|
64
|
+
🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▓░░░░░ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d
|
|
138
65
|
```
|
|
139
66
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
## Output language
|
|
67
|
+
Chips — `🚨 5H/7D NN%` (cap imminent) · `⚠ Ctx 200k+` (a single request actually exceeded 200k) · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. When both windows cross 90% at once, the sooner-resetting one is promoted to 🚨 and the other stays visible as a red segment (v2.16.0+).
|
|
143
68
|
|
|
144
|
-
|
|
69
|
+
### When a chip appears
|
|
145
70
|
|
|
146
|
-
|
|
147
|
-
claude-token-saver mode ko # or: claude-token-saver mode lang=ko
|
|
148
|
-
claude-token-saver mode en # back to English
|
|
149
|
-
claude-token-saver mode # show current settings
|
|
150
|
-
```
|
|
71
|
+
Run the `/claude-token-saver` Skill inside Claude — or just say the chip wording ("5H cap is up", "cache miss") and it auto-activates. The Skill surfaces the **root-cause code + step-by-step fix**. When a cap is imminent, run `claude-token-saver handoff` to back up your work state to markdown and continue in a fresh session.
|
|
151
72
|
|
|
152
73
|
## Commands
|
|
153
74
|
|
|
154
|
-
|
|
75
|
+
Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is the only entry point):
|
|
155
76
|
|
|
156
77
|
| Command | What it does |
|
|
157
78
|
|---|---|
|
|
158
|
-
| `claude-token-saver` | Last-1-day diagnostic report (`--days N`
|
|
159
|
-
| `claude-token-saver last` | Most recent warning + remediation
|
|
160
|
-
| `claude-token-saver history` | Last 7 days of
|
|
161
|
-
| `claude-token-saver handoff` | Back
|
|
162
|
-
| `claude-token-saver mode [keywords...]` |
|
|
163
|
-
| `claude-token-saver
|
|
164
|
-
| `claude-token-saver install` | Manually register Skill + statusline
|
|
165
|
-
| `claude-token-saver --install-hook` | Optionally auto-log cache stats on every tool call |
|
|
79
|
+
| `claude-token-saver` | Last-1-day diagnostic report (`--days N` / `--hours N`) |
|
|
80
|
+
| `claude-token-saver last` | Most recent warning + remediation |
|
|
81
|
+
| `claude-token-saver history` | Last 7 days of warning transitions |
|
|
82
|
+
| `claude-token-saver handoff` | Back work up to `HANDOFF-*.md` before a cap blocks you |
|
|
83
|
+
| `claude-token-saver mode [keywords...]` | Output config (`icon`/`text`, `en`/`ko`, `1h`–`30d` window, …) |
|
|
84
|
+
| `claude-token-saver harness ...` | 🅷 Harness management (below) |
|
|
85
|
+
| `claude-token-saver install` | Manually register Skill + statusline |
|
|
166
86
|
|
|
167
|
-
|
|
87
|
+
Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
|
|
88
|
+
|
|
89
|
+
<details>
|
|
90
|
+
<summary>All CLI options</summary>
|
|
168
91
|
|
|
169
92
|
| Flag | Description | Default |
|
|
170
93
|
|------|-------------|---------|
|
|
171
94
|
| `--days, -d` | Analysis period in days | 30 |
|
|
95
|
+
| `--hours` | Analysis window in hours (overrides `--days`) | – |
|
|
172
96
|
| `--format, -f` | `table` / `json` / `csv` | table |
|
|
173
97
|
| `--project, -p` | Filter by project directory | all |
|
|
174
98
|
| `--threshold` | Hit-rate alert threshold (0.0–1.0) | 0.7 |
|
|
@@ -179,37 +103,41 @@ All of the commands below run in your **shell (terminal)**. Inside a Claude Code
|
|
|
179
103
|
| `--no-color` | Strip ANSI codes | – |
|
|
180
104
|
| `--segments=…` | Limit statusline segments (e.g. `model,five_hour,seven_day,saved`) | all |
|
|
181
105
|
| `--install-hook` / `--uninstall-hook` | Manage the PostToolUse hook | – |
|
|
106
|
+
</details>
|
|
182
107
|
|
|
183
108
|
## 🅷 Harness mode
|
|
184
109
|
|
|
185
|
-
Bootstrap five engineering principles (Ratchet
|
|
110
|
+
Bootstrap five engineering principles (Ratchet · Evidence · PEV · Structured Task · Default Safe Path) into `CLAUDE.md` with one command; the statusline scores it as `🅷 5/5`. When the same error keeps recurring, a `🅷⚠ ratchet?` nudge appears so you can promote it to a rule.
|
|
186
111
|
|
|
187
112
|
```bash
|
|
188
|
-
claude-token-saver harness init #
|
|
189
|
-
claude-token-saver harness
|
|
190
|
-
claude-token-saver harness
|
|
191
|
-
claude-token-saver harness
|
|
192
|
-
claude-token-saver harness rm <N>
|
|
193
|
-
claude-token-saver harness uninit # remove the harness block (other CLAUDE.md content preserved)
|
|
113
|
+
claude-token-saver harness init # this project
|
|
114
|
+
claude-token-saver harness init --global # ~/.claude/CLAUDE.md — every project
|
|
115
|
+
claude-token-saver harness check # current score (global fallback honored)
|
|
116
|
+
claude-token-saver harness promote <N> --project|--global # warning #N → ratchet rule (scope required)
|
|
117
|
+
claude-token-saver harness list / rm <N> # view / delete rules (auto .bak)
|
|
194
118
|
claude-token-saver harness off | on # toggle the 🅷 chip
|
|
195
119
|
```
|
|
196
120
|
|
|
197
|
-
|
|
121
|
+
- `promote` **requires** `--project`/`--global` in non-TTY contexts (scripts, LLM calls) — a scope choice is never silently made for the caller.
|
|
122
|
+
- 🅷⚠ runtime warnings (`ratchet?` `no-evidence` `PEV-skip`) expire after 30 minutes, subdirectory sessions match their project correctly, and PEV-skip counts only mutating tools (Edit/Write/Bash) so read-only research sessions don't trip it (v2.16.0+).
|
|
123
|
+
|
|
124
|
+
<details>
|
|
125
|
+
<summary>⚠️ <code>harness rm</code> — checklist before deleting</summary>
|
|
198
126
|
|
|
199
|
-
The whole point of the ratchet is **one-direction accumulation**. Deleting rules casually means the same mistakes
|
|
127
|
+
The whole point of the ratchet is **one-direction accumulation**. Deleting rules casually means the same mistakes return.
|
|
200
128
|
|
|
201
|
-
- **
|
|
202
|
-
|
|
203
|
-
- **
|
|
204
|
-
- **Genuinely wrong rule?** → ✅ delete then
|
|
129
|
+
- **Rule too broad, blocking valid cases?** → ❌ delete ✅ narrow the condition (e.g. `"no hardcoded values"` → `"no hardcoded values outside tests"`)
|
|
130
|
+
- **Rule too narrow, almost never fires?** → ❌ delete ✅ leave it (zero cost)
|
|
131
|
+
- **Genuinely wrong?** → ✅ delete then
|
|
205
132
|
|
|
206
|
-
|
|
133
|
+
An auto `.bak` is kept, but **the session context that earned the rule its place is not recoverable.**
|
|
134
|
+
</details>
|
|
207
135
|
|
|
208
136
|
## Spike issue codes
|
|
209
137
|
|
|
210
138
|
| Code | Meaning |
|
|
211
139
|
|---|---|
|
|
212
|
-
| `LARGE_INPUT_PER_REQUEST` | single request >
|
|
140
|
+
| `LARGE_INPUT_PER_REQUEST` | single request > 200k input tokens — per-turn re-billing and cap burn spike |
|
|
213
141
|
| `LOW_HIT_RATE` | cache hit rate < 50% |
|
|
214
142
|
| `BUCKET_5M_DOMINANT` | > 70% of cache writes hit the 5m bucket |
|
|
215
143
|
| `HIGH_OUTPUT_RATIO` | output/input > 0.15 (output is 5× input price) |
|
|
@@ -218,31 +146,44 @@ Most "over-ratcheting" complaints turn out to be **rules that weren't phrased ti
|
|
|
218
146
|
|
|
219
147
|
Remediation commands are OS-aware (`~/.zshrc` for macOS/Linux/WSL, `setx` for Windows).
|
|
220
148
|
|
|
221
|
-
##
|
|
149
|
+
## Real-world impact — before/after report
|
|
222
150
|
|
|
223
|
-
|
|
224
|
-
npm uninstall -g claude-cache-monitor
|
|
225
|
-
npm i -g claude-token-saver
|
|
226
|
-
```
|
|
151
|
+
|
|
227
152
|
|
|
228
|
-
|
|
153
|
+
harness 5/5 + ratchet applied to the author's own Claude Code work, normalized **per user message** (cutoff 2026-05-02, Opus 4.7 pricing):
|
|
229
154
|
|
|
230
|
-
|
|
155
|
+
| metric | before (7d / 739 msgs) | after (2d / 157 msgs) | Δ |
|
|
156
|
+
|---|---:|---:|---:|
|
|
157
|
+
| cost / user message | $2.345 | $1.910 | **−18.6%** |
|
|
158
|
+
| output tokens / message | 7,391 | 6,052 | −18.1% |
|
|
159
|
+
| assistant turns / message | 9.73 | 8.83 | −9.2% |
|
|
160
|
+
| tool calls / message | 5.72 | 5.25 | −8.2% |
|
|
231
161
|
|
|
232
|
-
|
|
162
|
+
Same request resolved in fewer round-trips → first-try success rate up — the effect of PEV + Structured Task forcing one-shot delivery.
|
|
233
163
|
|
|
234
|
-
|
|
164
|
+
<details>
|
|
165
|
+
<summary>Measurement notes — why cache hit rate isn't included · sample caveats</summary>
|
|
166
|
+
|
|
167
|
+
- The author is on the Max plan (1-hour cache TTL) with hit rate already converged near ~98%, so little headroom there. **Pro-plan users (5-minute TTL)** likely see hit rate itself rise with the handoff-before-expiry workflow.
|
|
168
|
+
- Handoff-before-expiry: watch the TTL countdown, run `claude-token-saver handoff` just before expiry to dump work state into a markdown brief, start a fresh cache cycle. Same flow handles the 1M warning and cap chips.
|
|
169
|
+
- ⚠️ POST window is only 2 days (157 msgs); statistical confidence is low, and week-to-week topic mix differs, so the tool effect isn't cleanly isolated.
|
|
170
|
+
</details>
|
|
171
|
+
|
|
172
|
+
## Pricing (Jul 2026)
|
|
173
|
+
|
|
174
|
+
Per million tokens (USD), as used by the cost estimator:
|
|
235
175
|
|
|
236
176
|
| Tier | Models | Input | 5m Write | 1h Write | Read | Output |
|
|
237
177
|
|---|---|---|---|---|---|---|
|
|
238
|
-
| `claude-
|
|
178
|
+
| `claude-fable-5` | Fable 5 / Mythos 5 | $10 | $12.50 | $20 | $1 | $50 |
|
|
179
|
+
| `claude-opus-new` | Opus 4.5 / 4.6 / 4.7 / 4.8 | $5 | $6.25 | $10 | $0.50 | $25 |
|
|
239
180
|
| `claude-opus-legacy` | Opus 4 / 4.1 / 3 | $15 | $18.75 | $30 | $1.50 | $75 |
|
|
240
|
-
| `claude-sonnet` | Sonnet 3.7 / 4 / 4.5 / 4.6 | $3 | $3.75 | $6 | $0.30 | $15 |
|
|
181
|
+
| `claude-sonnet` | Sonnet 3.7 / 4 / 4.5 / 4.6 / 5 | $3 | $3.75 | $6 | $0.30 | $15 |
|
|
241
182
|
| `claude-haiku-4-5` | Haiku 4.5 | $1 | $1.25 | $2 | $0.10 | $5 |
|
|
242
183
|
|
|
243
|
-
Source: [Anthropic pricing docs](https://
|
|
184
|
+
Source: [Anthropic pricing docs](https://platform.claude.com/docs/en/about-claude/pricing). Sonnet 5 has an introductory $2/$10 rate through 2026-08-31; the estimator uses the standard sticker. Versions ≤ 2.16.x priced Fable 5 at the Sonnet tier (~3× under-estimate) — upgrade to 2.17.0+.
|
|
244
185
|
|
|
245
|
-
|
|
186
|
+
### Cache TTL by plan
|
|
246
187
|
|
|
247
188
|
| Plan | TTL | Controlled by |
|
|
248
189
|
|---|---|---|
|
|
@@ -250,69 +191,66 @@ Source: [Anthropic pricing docs](https://docs.claude.com/en/docs/about-claude/pr
|
|
|
250
191
|
| Pro ($20/mo) | **5m fixed** | not configurable |
|
|
251
192
|
| API key | 5m default (1h via beta header) | `cache_control.ttl` |
|
|
252
193
|
|
|
253
|
-
## Environment
|
|
254
|
-
|
|
255
|
-
Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
|
|
194
|
+
## How it works · Environment
|
|
256
195
|
|
|
257
|
-
|
|
196
|
+
Claude Code logs every API call to `~/.claude/projects/<dir>/<session>.jsonl`. This tool dedupes streaming chunks by `requestId` and aggregates `cache_read_input_tokens` / `cache_creation.ephemeral_5m/1h_input_tokens` by day and session.
|
|
258
197
|
|
|
259
|
-
|
|
260
|
-
- [HN discussion](https://news.ycombinator.com/item?id=47736476) — 168 points, 142 comments
|
|
261
|
-
- [DeepPulse KR](https://www.youtube.com/@DeepPulseKR) — Korean HN tech deep-dives
|
|
262
|
-
- [DeepPulse EN](https://www.youtube.com/@DeepPulseEN) — English HN tech deep-dives
|
|
263
|
-
- [Homepage](https://rootstudioyaml.github.io/) — project site
|
|
198
|
+
Node.js ≥ 18 · macOS / Linux / Windows / WSL · **zero dependencies**.
|
|
264
199
|
|
|
265
|
-
|
|
200
|
+
<details>
|
|
201
|
+
<summary>Known quirks · Migration · Background</summary>
|
|
266
202
|
|
|
267
|
-
**IntelliJ Claude Code plugin** — the statusline widget fuses
|
|
203
|
+
**IntelliJ Claude Code plugin** — the statusline widget fuses frames at the character level when emoji are present (`59:548` artifacts). v2.8.5+ detects `TERMINAL_EMULATOR=JetBrains-JediTerm` and falls back to text mode automatically.
|
|
268
204
|
|
|
269
|
-
|
|
205
|
+
**Migration from claude-cache-monitor:**
|
|
206
|
+
```bash
|
|
207
|
+
npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
|
|
208
|
+
```
|
|
209
|
+
Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-saver …`.
|
|
270
210
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
- `harness check` now treats global as a **fallback** — a project with no local block but a global harness installed reports `🅷 5/5 (covered by global)`, matching how Claude Code loads the global `CLAUDE.md` for every project. Use `--project`/`--global` to inspect a single scope.
|
|
274
|
-
- npm package homepage changed to `https://rootstudioyaml.github.io/`; README adds the **@DeepPulseEN** channel and a homepage badge.
|
|
211
|
+
**Background:** [GitHub Issue #46829](https://github.com/anthropics/claude-code/issues/46829) (cache TTL regression) · [HN discussion](https://news.ycombinator.com/item?id=47736476) · [DeepPulse KR](https://www.youtube.com/@DeepPulseKR) / [EN](https://www.youtube.com/@DeepPulseEN) · [Homepage](https://rootstudioyaml.github.io/)
|
|
212
|
+
</details>
|
|
275
213
|
|
|
276
|
-
|
|
277
|
-
- "Real-world impact" section restructured as a **harness + ratchet adoption cost-savings report**. Added Max(1h)/Pro(5m) cache TTL distinction (different hit-rate headroom), the handoff-before-expiry workflow, and the 2026-05-09 refresh promise. Chart title updated to match.
|
|
214
|
+
## Release notes
|
|
278
215
|
|
|
279
|
-
### v2.
|
|
280
|
-
-
|
|
216
|
+
### v2.18.0 (2026-07-02)
|
|
217
|
+
- **1M-context warning re-scoped** — current models (Fable 5, Opus 4.6–4.8, Sonnet 5) all default to a 1M window with no long-context premium since Opus 4.7, so the "1M mode ON = expensive" framing is retired. The warning is now a **usage signal**: `⚠ 1M ON` → `⚠ Ctx 200k+` (a single request actually exceeded 200k), and remediation is reordered to lead with `/compact`/`/clear` + `/effort` instead of "disable 1M". The incorrect "long-context pricing kicks in past 200k" copy is fixed.
|
|
218
|
+
- **📦 segment shows live usage** — reads `context_window.used_percentage` from Claude Code's stdin and renders `📦 Ctx 68% of 1M`, colored by fill (green <70 / yellow 70–89 / red 90+). Falls back to transcript-inferred size when stdin is absent (1M now yellow, not red).
|
|
219
|
+
- Back-compat: the legacy `⚠ 1M ON` chip and old detail strings in existing history files still resolve.
|
|
281
220
|
|
|
282
|
-
### v2.
|
|
283
|
-
-
|
|
284
|
-
-
|
|
221
|
+
### v2.17.0 (2026-07-02)
|
|
222
|
+
- **Fable 5 pricing tier** — `claude-fable-5`/`claude-mythos-5` previously fell through to the Sonnet tier ($3/$15), under-estimating costs ~3×. Now priced at the real rates ($10 input / $50 output / $12.50 5m-write / $20 1h-write / $1 read).
|
|
223
|
+
- README overhaul — top-level impact summary, segment table, harness scope-flag docs, pricing table brought current.
|
|
285
224
|
|
|
286
|
-
### v2.
|
|
287
|
-
-
|
|
225
|
+
### v2.16.0 (2026-07-02)
|
|
226
|
+
- **Statusline fixes** — when two rate-limit windows are ≥90% at once, only the cap-warn-promoted window is suppressed (the other stayed hidden before); `--no-color` output is truly ANSI-free; the no-session fallback line keeps cap-warn / 🅷 / model chips.
|
|
227
|
+
- **Harness warning accuracy** — 🅷⚠ warnings expire after 30 minutes (previously lingered indefinitely); session cwd normalized to the project root (subdirectory launches match); no-cwd states no longer leak into every project.
|
|
228
|
+
- **Fewer PEV-skip false positives** — only mutating tools count; windows sliced by assistant turns.
|
|
288
229
|
|
|
289
|
-
|
|
290
|
-
|
|
230
|
+
<details>
|
|
231
|
+
<summary>Older versions (v2.8.5 – v2.15.0)</summary>
|
|
291
232
|
|
|
292
|
-
### v2.
|
|
293
|
-
-
|
|
294
|
-
-
|
|
233
|
+
### v2.15.0 (2026-06-13)
|
|
234
|
+
- **Global harness init** — `harness init --global` installs the 5 sections into `~/.claude/CLAUDE.md` (+ `~/.claude/ratchet.md`), applying to every project. `harness check` honors global as a fallback (`🅷 5/5 (covered by global)`).
|
|
235
|
+
- npm homepage change; @DeepPulseEN + homepage badges.
|
|
295
236
|
|
|
296
|
-
### v2.
|
|
297
|
-
-
|
|
237
|
+
### v2.13.x (2026-05-04)
|
|
238
|
+
- "Real-world impact" restructured as the harness+ratchet before/after report; statusline screenshot + impact chart; npm metadata cleanup; YouTube handle fix.
|
|
298
239
|
|
|
299
|
-
### v2.
|
|
300
|
-
-
|
|
301
|
-
- Add a 4-step "When a warning chip appears" Skill workflow — spot the chip → mention its wording to Claude → Skill runs `last` → apply remediation.
|
|
302
|
-
- Move `language` from `cfg.statusline.language` to top-level `cfg.language` (it doesn't belong with statusline toggles). The legacy location is still read as a fallback so existing configs migrate transparently. `mode` output also splits the statusline section from the output-language section.
|
|
240
|
+
### v2.11.0 (2026-05-02)
|
|
241
|
+
- `harness list` / `harness rm <N>` (auto `.bak`, "narrow the condition first" guidance).
|
|
303
242
|
|
|
304
|
-
### v2.9.
|
|
305
|
-
-
|
|
306
|
-
- History files stay bilingual on disk; the language toggle is applied at display time.
|
|
243
|
+
### v2.9.x (2026-04-27)
|
|
244
|
+
- Output language toggle (`mode ko`/`en`) for `last`/`history`/advice; Skill responds in the configured language; Node.js prerequisite block; Skill workflow guide; `language` config location cleanup.
|
|
307
245
|
|
|
308
246
|
### v2.8.6 (2026-04-27)
|
|
309
|
-
- **Skill auto-registers on install
|
|
310
|
-
- README polish in both languages; corrected the `claude-cache-monitor` alias-removal note (timing was reversed).
|
|
247
|
+
- **Skill auto-registers on install** via postinstall hook.
|
|
311
248
|
|
|
312
249
|
### v2.8.5
|
|
313
|
-
- IntelliJ
|
|
250
|
+
- IntelliJ plugin frame-fusion workaround — auto text mode under JediTerm.
|
|
314
251
|
|
|
315
252
|
Older versions: see `git log`.
|
|
253
|
+
</details>
|
|
316
254
|
|
|
317
255
|
## License
|
|
318
256
|
|