npm - claude-token-saver - Versions diffs - 2.15.0 → 2.17.0 - Mend

claude-token-saver 2.15.0 → 2.17.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.

Files changed (8) hide show

package/README.en.md +126 -193
package/README.md +117 -185
package/bin/cli.js +24 -5
package/package.json +1 -1
package/src/cost.js +16 -1
package/src/formatters/statusline.js +90 -57
package/src/harness-analyzer.cjs +35 -26
package/src/harness.js +18 -5

package/README.en.md CHANGED Viewed

@@ -7,168 +7,92 @@
 # claude-token-saver
-> Renamed from `claude-cache-monitor` in v2.0. Existing users — see [Migration](#migration-from-claude-cache-monitor).
+**Diagnose and save Claude Code tokens from a single statusline.** Zero dependencies, one-line install.
-A CLI to **diagnose and save tokens on Claude Code**. Cache hit rate, TTL countdown, 1M-context detection, 5h/7d cap warnings — all in one statusline chip.
+```bash
+npm i -g claude-token-saver   # postinstall auto-registers the statusline + Skill
+```
 ![statusline example](./docs/statusline.png)
-📺 [Launch Short (60s)](https://www.youtube.com/shorts/RaD8qMsPTnA)
-## Cost-savings report — harness + ratchet adoption
-![claude-token-saver — harness + ratchet adoption impact](./docs/harness-impact.png)
-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):
-| metric | before (7d / 739 msgs) | after (2d / 157 msgs) | Δ |
-|---|---:|---:|---:|
-| cost / user message | $2.345 | $1.910 | **−18.6%** |
-| output tokens / user message | 7,391 | 6,052 | −18.1% |
-| assistant turns / user message | 9.73 | 8.83 | −9.2% |
-| tool calls / user message | 5.72 | 5.25 | −8.2% |
-Same request resolved in fewer round-trips → first-try success rate up. Looks like the effect of PEV + Structured Task forcing one-shot delivery.
-### Why cache hit rate isn't in this measurement — Max vs Pro
-**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**.
+## ⚡ Why — the 30-second pitch
-### Handoff-before-expiry workflow
-Watching the TTL countdown in the statusline, the habit is now: just before expiry, run `claude-token-saver handoff` to dump current work state into a markdown brief, then start a fresh cache cycle. Same flow handles the 1M-context warning and 5H/7D cap chips.
+| | |
+|---|---|
+| 💸 **−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)) |
+| 🚨 **No surprise rate limits** | Instant warning when the 5H/7D window hits 90% + `handoff` to back up your work |
+| 🧠 **Cache waste detection** | Hit rate, TTL countdown, 1M-context detection — token spikes diagnosed with issue codes |
+| 🅷 **Stop repeating mistakes** | Recurring errors get promoted to ratchet rules — auto-applied from the next session |
+| 💰 **Savings made visible** | See what prompt caching saved you, live (`💰 Cache saved $2.1K`) |
-> ⚠️ **Sample caveats** — POST window is only 2 days (157 msgs); statistical confidence is low. The work topic mix differs week to week (PRE was video-script production with long pasted text, POST was package release with short directives), so the tool/harness effect isn't cleanly isolated. **Once 5 more days of POST data are in (around 2026-05-09)**, the same analysis will be re-run to check whether the trend stabilises, and an update will be posted.
+📺 [Launch Short (60s)](https://www.youtube.com/shorts/RaD8qMsPTnA)
 ---
-## Install
-### Prerequisite — Node.js (≥ 18)
+## Getting started
-`npm` ships with Node.js. Check whether it's installed:
+**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)
 ```bash
-node -v   # v18.0.0 or later is fine
-```
-If not, install it:
-- **macOS** — `brew install node` (Homebrew) or the installer at [nodejs.org](https://nodejs.org/)
-- **Windows** — [nodejs.org](https://nodejs.org/) LTS installer, or `winget install OpenJS.NodeJS.LTS`
-- **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)
-> 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.
-### Install claude-token-saver
-```bash
-# (existing users) remove the old package
-npm uninstall -g claude-cache-monitor
-# install — the postinstall hook auto-registers the Skill and statusline
+npm uninstall -g claude-cache-monitor   # (previous-package users only)
 npm i -g claude-token-saver
 ```
-Or run once with no install: `npx claude-token-saver`.
-If postinstall was skipped (e.g. `--ignore-scripts`, sudo, or sandboxed installs), register manually:
-```bash
-claude-token-saver install
-```
-## Claude Code statusline
+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`.
-After install, Claude Code's bottom statusline updates every 5 seconds with cache state (postinstall registers it in `~/.claude/settings.json` automatically).
+> ⚠️ 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`.
-```
-🤖 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
-```
-Segments — `🤖 model` · `🧠 cache hit rate` · `⏳ TTL countdown` · `✦ current` (5-hour window) · `📅 weekly` (7-day window) · `📦 context` · `💰 cumulative savings` · `last <window>`.
+## Reading the statusline
-When excessive token usage is detected, a warning chip is prepended at the front of the statusline:
-```
-🚨 5H 94% (resets in 12m) · 🤖 Opus 4.7 · 🧠 Cache hit 72.1% · ⚠ Cache miss · ✦ current ██████ 94% · 📦 Ctx 200k · last 1d
 ```
-Risk chips: `🚨 5H/7D NN%`, `⚠ 1M ON`, `⚠ Input spike`, `⚠ Cache miss`, `⚠ 5m TTL`, `⚠ Rebuild churn`, `⚠ Output heavy`, `⚠ Call surge`.
-**What to do** — run the `/claude-token-saver` Skill in Claude. It calls `claude-token-saver last` and surfaces the root cause + step-by-step fix. Saying the chip wording out loud (e.g. "5H cap is up", "cache miss") also auto-activates the same Skill. See the [Skill workflow](#when-a-warning-chip-appears--skill-workflow) section below for the full flow.
-If postinstall was skipped (you already use a different statusline, etc.), wire it manually:
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "claude-token-saver --statusline --icon",
-    "refreshInterval": 5
-  }
-}
+🤖 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
 ```
-`refreshInterval: 5` keeps the TTL countdown ticking while idle. For Windows PowerShell see `examples/statusline-command.ps1`.
-## When a warning chip appears — Skill workflow
-The Claude Code Skill registered at install time bridges "warning chip → remediation":
-1. **A risk chip appears in the statusline** — e.g. `🚨 5H 94%`, `⚠ Cache miss`, `⚠ 1M ON`.
-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.
-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.
-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.
-> 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.
-## One-shot report
+| Segment | Meaning |
+|---|---|
+| `🤖` | Active model |
+| `🅷 5/5` | Harness principle score ([Harness mode](#-harness-mode)) |
+| `🧠` | Cache hit rate (green at 85%+) |
+| `⏳` | Cache TTL countdown — send a message before expiry to keep the cache warm |
+| `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
+| `📦` | Context window (1M shows red — a major cost driver) |
+| `💰` | Cumulative savings from prompt caching |
-Run `claude-token-saver` for the last-day diagnostic table:
+When something is wrong, a **warning chip leads the line**:
 ```
-  Claude Token Saver — Last 1 day
-  (claude-token-saver v2.9.0)
-  ══════════════════════════════════════════════════
-  Context window: 200k  ✓ 200k context (standard)
-  Sessions: 11  |  API calls: 578  |  Cache hit rate: 98.0%
-  TTL Breakdown / Cost Impact / Daily Trend …
+🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▓░░░░░ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d
 ```
-If a session spiked, a `⚠ Spike detected` block leads the report with the root-cause code (table below) and an OS-aware remediation command.
-## Output language
+Chips — `🚨 5H/7D NN%` (cap imminent) · `⚠ 1M ON` · `⚠ 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+).
-`last` / `history` / advice messages render in one language at a time (statusline chips stay symbolic). English is the default — switch via:
+### When a chip appears
-```bash
-claude-token-saver mode ko    # or: claude-token-saver mode lang=ko
-claude-token-saver mode en    # back to English
-claude-token-saver mode       # show current settings
-```
+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.
 ## Commands
-All of the commands below run in your **shell (terminal)**. Inside a Claude Code session, the only entry point is the `/claude-token-saver` Skill, which calls these commands for you. The `--statusline` form is invoked automatically by Claude Code on each statusline refresh — you never type it yourself.
+Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is the only entry point):
 | Command | What it does |
 |---|---|
-| `claude-token-saver` | Last-1-day diagnostic report (`--days N` to change window) |
-| `claude-token-saver last` | Most recent warning + remediation (the command the Skill invokes) |
-| `claude-token-saver history` | Last 7 days of chip transitions (1M ON, Cache miss, cap, …) |
-| `claude-token-saver handoff` | Back current work up to `HANDOFF-YYYY-MM-DD-HHMM.md` before a cap blocks you |
-| `claude-token-saver mode [keywords...]` | Configure output (`icon`/`text`, `en`/`ko`, `verbose`, `1d`/`7d`, …) |
-| `claude-token-saver --statusline --icon` | One-line statusline output (called by Claude Code) |
-| `claude-token-saver install` | Manually register Skill + statusline (postinstall fallback) |
-| `claude-token-saver --install-hook` | Optionally auto-log cache stats on every tool call |
+| `claude-token-saver` | Last-1-day diagnostic report (`--days N` / `--hours N`) |
+| `claude-token-saver last` | Most recent warning + remediation |
+| `claude-token-saver history` | Last 7 days of warning transitions |
+| `claude-token-saver handoff` | Back work up to `HANDOFF-*.md` before a cap blocks you |
+| `claude-token-saver mode [keywords...]` | Output config (`icon`/`text`, `en`/`ko`, `1h`–`30d` window, …) |
+| `claude-token-saver harness ...` | 🅷 Harness management (below) |
+| `claude-token-saver install` | Manually register Skill + statusline |
-## Options
+Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
+<details>
+<summary>All CLI options</summary>
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--days, -d` | Analysis period in days | 30 |
+| `--hours` | Analysis window in hours (overrides `--days`) | – |
 | `--format, -f` | `table` / `json` / `csv` | table |
 | `--project, -p` | Filter by project directory | all |
 | `--threshold` | Hit-rate alert threshold (0.0–1.0) | 0.7 |
@@ -179,31 +103,35 @@ All of the commands below run in your **shell (terminal)**. Inside a Claude Code
 | `--no-color` | Strip ANSI codes | – |
 | `--segments=…` | Limit statusline segments (e.g. `model,five_hour,seven_day,saved`) | all |
 | `--install-hook` / `--uninstall-hook` | Manage the PostToolUse hook | – |
+</details>
 ## 🅷 Harness mode
-Bootstrap five engineering principles (Ratchet, Evidence, PEV, Structured Task, Default Safe Path) into your project's `CLAUDE.md` with one command, then watch the statusline track your score (`🅷 5/5`). When the same error keeps recurring, a `🅷⚠ ratchet?` nudge appears.
+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.
 ```bash
-claude-token-saver harness init                # writes CLAUDE.md (5 sections) + .claude/ratchet.md
-claude-token-saver harness check               # current score
-claude-token-saver harness promote <N>         # turn statusline warning #N into a one-line ratchet rule
-claude-token-saver harness list                # list registered ratchet rules with numbers
-claude-token-saver harness rm <N>              # delete rule N (auto .bak backup)
-claude-token-saver harness uninit              # remove the harness block (other CLAUDE.md content preserved)
+claude-token-saver harness init                # this project
+claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — every project
+claude-token-saver harness check               # current score (global fallback honored)
+claude-token-saver harness promote <N> --project|--global   # warning #N → ratchet rule (scope required)
+claude-token-saver harness list / rm <N>       # view / delete rules (auto .bak)
 claude-token-saver harness off | on            # toggle the 🅷 chip
 ```
-### ⚠️ `harness rm` — handle with care
+- `promote` **requires** `--project`/`--global` in non-TTY contexts (scripts, LLM calls) — a scope choice is never silently made for the caller.
+- 🅷⚠ 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+).
+<details>
+<summary>⚠️ <code>harness rm</code> — checklist before deleting</summary>
-The whole point of the ratchet is **one-direction accumulation**. Deleting rules casually means the same mistakes start re-occurring. **Before deleting, ask**:
+The whole point of the ratchet is **one-direction accumulation**. Deleting rules casually means the same mistakes return.
-- **Is the rule too broad and blocking valid cases?** → ❌ delete ✅ **narrow the condition instead**
-  - e.g. `"no hardcoded values"` → `"no hardcoded values outside tests"`
-- **Is the rule too narrow and almost never firing?** → ❌ delete ✅ **leave it** (zero cost)
-- **Genuinely wrong rule?** → ✅ delete then
+- **Rule too broad, blocking valid cases?** → ❌ delete ✅ narrow the condition (e.g. `"no hardcoded values"` → `"no hardcoded values outside tests"`)
+- **Rule too narrow, almost never fires?** → ❌ delete ✅ leave it (zero cost)
+- **Genuinely wrong?** → ✅ delete then
-Most "over-ratcheting" complaints turn out to be **rules that weren't phrased tightly enough**. Open `.claude/ratchet.md` and refine the condition first; deletion is the last resort. An auto `.bak` is left behind, but **the session context that made the rule earn its place is not recoverable**.
+An auto `.bak` is kept, but **the session context that earned the rule its place is not recoverable.**
+</details>
 ## Spike issue codes
@@ -218,31 +146,44 @@ Most "over-ratcheting" complaints turn out to be **rules that weren't phrased ti
 Remediation commands are OS-aware (`~/.zshrc` for macOS/Linux/WSL, `setx` for Windows).
-## Migration from claude-cache-monitor
+## Real-world impact — before/after report
-```bash
-npm uninstall -g claude-cache-monitor
-npm i -g claude-token-saver
-```
+![claude-token-saver — harness + ratchet adoption impact](./docs/harness-impact.png)
-Then update `~/.claude/settings.json` — change `claude-cache-monitor …` to `claude-token-saver …`. The v2.0 alias bin was dropped because it caused `EEXIST` on global installs.
+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):
-## How it works
+| metric | before (7d / 739 msgs) | after (2d / 157 msgs) | Δ |
+|---|---:|---:|---:|
+| cost / user message | $2.345 | $1.910 | **−18.6%** |
+| output tokens / message | 7,391 | 6,052 | −18.1% |
+| assistant turns / message | 9.73 | 8.83 | −9.2% |
+| tool calls / message | 5.72 | 5.25 | −8.2% |
-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_input_tokens` / `cache_creation.ephemeral_1h_input_tokens` by day and session.
+Same request resolved in fewer round-trips → first-try success rate up — the effect of PEV + Structured Task forcing one-shot delivery.
-## Pricing (Apr 2026)
+<details>
+<summary>Measurement notes — why cache hit rate isn't included · sample caveats</summary>
+- 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.
+- 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.
+- ⚠️ 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.
+</details>
+## Pricing (Jul 2026)
+Per million tokens (USD), as used by the cost estimator:
 | Tier | Models | Input | 5m Write | 1h Write | Read | Output |
 |---|---|---|---|---|---|---|
-| `claude-opus-new` | Opus 4.5 / 4.6 / 4.7 | $5 | $6.25 | $10 | $0.50 | $25 |
+| `claude-fable-5` | Fable 5 / Mythos 5 | $10 | $12.50 | $20 | $1 | $50 |
+| `claude-opus-new` | Opus 4.5 / 4.6 / 4.7 / 4.8 | $5 | $6.25 | $10 | $0.50 | $25 |
 | `claude-opus-legacy` | Opus 4 / 4.1 / 3 | $15 | $18.75 | $30 | $1.50 | $75 |
-| `claude-sonnet` | Sonnet 3.7 / 4 / 4.5 / 4.6 | $3 | $3.75 | $6 | $0.30 | $15 |
+| `claude-sonnet` | Sonnet 3.7 / 4 / 4.5 / 4.6 / 5 | $3 | $3.75 | $6 | $0.30 | $15 |
 | `claude-haiku-4-5` | Haiku 4.5 | $1 | $1.25 | $2 | $0.10 | $5 |
-Source: [Anthropic pricing docs](https://docs.claude.com/en/docs/about-claude/pricing). Versions ≤ 1.0.x over-estimated Opus 4.5+ by ~3× — upgrade if you're below 1.1.0.
+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+.
-## Cache TTL by plan
+### Cache TTL by plan
 | Plan | TTL | Controlled by |
 |---|---|---|
@@ -250,69 +191,61 @@ Source: [Anthropic pricing docs](https://docs.claude.com/en/docs/about-claude/pr
 | Pro ($20/mo) | **5m fixed** | not configurable |
 | API key | 5m default (1h via beta header) | `cache_control.ttl` |
-## Environment
-Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
+## How it works · Environment
-## Background
+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.
-- [GitHub Issue #46829](https://github.com/anthropics/claude-code/issues/46829) — cache TTL regression
-- [HN discussion](https://news.ycombinator.com/item?id=47736476) — 168 points, 142 comments
-- [DeepPulse KR](https://www.youtube.com/@DeepPulseKR) — Korean HN tech deep-dives
-- [DeepPulse EN](https://www.youtube.com/@DeepPulseEN) — English HN tech deep-dives
-- [Homepage](https://rootstudioyaml.github.io/) — project site
+Node.js ≥ 18 · macOS / Linux / Windows / WSL · **zero dependencies**.
-## Known environment quirks
+<details>
+<summary>Known quirks · Migration · Background</summary>
-**IntelliJ Claude Code plugin** — the statusline widget fuses prior and current frames at the character level when emoji are in the output, producing artifacts like `Cache expires 59:548`. v2.8.5+ detects `TERMINAL_EMULATOR=JetBrains-JediTerm` and falls back to text mode automatically (`--icon` is also ignored under IntelliJ). Other terminals (iTerm, Terminal, WSL, etc.) are unaffected.
+**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.
-## Release notes
-### v2.15.0 (2026-06-13)
-- **Global harness init** — `harness init`/`uninit`/`check` gain the same scope concept ratchet already had. `harness init --global` installs the 5 sections into `~/.claude/CLAUDE.md` (+ `~/.claude/ratchet.md`) once, so they **apply to every project**. The no-flag default stays `project` (back-compat).
-- `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.
-- npm package homepage changed to `https://rootstudioyaml.github.io/`; README adds the **@DeepPulseEN** channel and a homepage badge.
+**Migration from claude-cache-monitor:**
+```bash
+npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
+```
+Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-saver …`.
-### v2.13.3 (2026-05-04)
-- "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.
+**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/)
+</details>
-### v2.13.2 (2026-05-04)
-- YouTube channel handle corrected to `@DeepPulseKR` (package.json + both READMEs).
+## Release notes
-### v2.13.1 (2026-05-04)
-- README now opens with the actual statusline screenshot and a "harness 5/5 + ratchet — before/after" impact chart, with daily/monthly/yearly cost-savings impact card. Author's own logs show −18.6% cost / user message, −9.2% assistant turns. Sample caveats, work-topic confound, and refresh schedule (2026-05-09) called out.
-- npm package metadata cleaned up (homepage / bugs / author) — package page now links to the DeepPulse YouTube channel.
+### v2.17.0 (2026-07-02)
+- **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).
+- README overhaul — top-level impact summary, segment table, harness scope-flag docs, pricing table brought current.
-### v2.11.0 (2026-05-02)
-- Added `harness list` / `harness rm <N>` to view registered ratchet rules with numbers and delete individually (auto `.bak` backup). The CLI prompts users to "narrow the condition first" before deleting; see [⚠️ `harness rm` — handle with care](#️-harness-rm--handle-with-care).
+### v2.16.0 (2026-07-02)
+- **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.
+- **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.
+- **Fewer PEV-skip false positives** — only mutating tools count; windows sliced by assistant turns.
-### v2.9.4 (2026-04-27)
-- README now opens with a Node.js prerequisite block (macOS / Windows / Linux). First-time visitors arriving from GitHub no longer hit `npm: command not found` with no guidance. Also flags the `sudo` global-install trap where postinstall writes the Skill under root's home instead of the user's.
+<details>
+<summary>Older versions (v2.8.5 – v2.15.0)</summary>
-### v2.9.3 (2026-04-27)
-- Skill body (`SKILL.md`) now instructs Claude to respond in the user's configured output language. Previously even when the CLI was on `mode ko`, Claude itself still narrated the answer in English ("All clear — no warnings…"), so the language toggle felt half-applied.
-- `installSkill` now auto-updates the on-disk `SKILL.md` whenever the bundled body differs, so upgrades pick up new instructions without `--force`.
+### v2.15.0 (2026-06-13)
+- **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)`).
+- npm homepage change; @DeepPulseEN + homepage badges.
-### v2.9.2 (2026-04-27)
-- `last` / `history` empty-state messages now respect the language setting too. Previously they were hard-coded English, so users on `mode ko` still saw English when there were no warnings to report.
+### v2.13.x (2026-05-04)
+- "Real-world impact" restructured as the harness+ratchet before/after report; statusline screenshot + impact chart; npm metadata cleanup; YouTube handle fix.
-### v2.9.1 (2026-04-27)
-- Fix the README statusline sample so it matches actual output (includes the `✦ current` / `📅 weekly` window segments that were missing).
-- Add a 4-step "When a warning chip appears" Skill workflow — spot the chip → mention its wording to Claude → Skill runs `last` → apply remediation.
-- 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.
+### v2.11.0 (2026-05-02)
+- `harness list` / `harness rm <N>` (auto `.bak`, "narrow the condition first" guidance).
-### v2.9.0 (2026-04-27)
-- **Output language is now configurable.** `last` / `history` / advice render in a single language at a time. English by default; switch with `claude-token-saver mode ko`. Statusline chips remain symbolic.
-- History files stay bilingual on disk; the language toggle is applied at display time.
+### v2.9.x (2026-04-27)
+- 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.
 ### v2.8.6 (2026-04-27)
-- **Skill auto-registers on install.** A `postinstall` hook wires the Claude Code Skill and statusline into `~/.claude` automatically — no second command. `claude-token-saver install` still works as a fallback for `--ignore-scripts` / sudo / sandboxed environments.
-- README polish in both languages; corrected the `claude-cache-monitor` alias-removal note (timing was reversed).
+- **Skill auto-registers on install** via postinstall hook.
 ### v2.8.5
-- IntelliJ Claude Code plugin: auto-fall back to text mode when `TERMINAL_EMULATOR=JetBrains-JediTerm` to avoid frame-fusion artefacts.
+- IntelliJ plugin frame-fusion workaround — auto text mode under JediTerm.
 Older versions: see `git log`.
+</details>
 ## License