claude-token-saver 2.13.2 → 2.14.0

package/README.en.md

@@ -13,11 +13,11 @@ A CLI to **diagnose and save tokens on Claude Code**. Cache hit rate, TTL countd
 
 📺 [Launch Short (60s)](https://www.youtube.com/shorts/RaD8qMsPTnA)
 
-## Real-world impact — harness 5/5 + ratchet adoption
+## Cost-savings report — harness + ratchet adoption
 
-![claude-token-saver before/after](./docs/harness-impact.png)
+![claude-token-saver — harness + ratchet adoption impact](./docs/harness-impact.png)
 
-Author's own Claude Code logs, normalized **per user message**, before/after adopting harness rules on 2026-05-02 (Opus 4.7 pricing):
+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) | Δ |
 |---|---:|---:|---:|
@@ -26,7 +26,17 @@ Author's own Claude Code logs, normalized **per user message**, before/after ado
 | assistant turns / user message | 9.73 | 8.83 | −9.2% |
 | tool calls / user message | 5.72 | 5.25 | −8.2% |
 
-> ⚠️ **Sample caveats** — POST window is only 2 days (157 msgs); statistical confidence is low. The work topic mix differs week to week (PRE week was video-script production with long pasted text, POST week was package release with short directives), so the tool/harness effect is not cleanly isolated. Refresh planned around **2026-05-09** once 5 more days of POST data are in.
+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**.
+
+### 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.
+
+> ⚠️ **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.
 
 ---
 
@@ -254,6 +264,12 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## Release notes
 
+### 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.
+
+### v2.13.2 (2026-05-04)
+- YouTube channel handle corrected to `@DeepPulseKR` (package.json + both READMEs).
+
 ### 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.

package/README.md

@@ -13,20 +13,30 @@ Claude Code의 **토큰 사용량을 진단·절약**하는 CLI. 캐시 히트
 
 📺 [출시 영상 (60초)](https://www.youtube.com/shorts/RaD8qMsPTnA)
 
-## 실제 효과 — harness 5/5 + ratchet 적용 전후
+## 실제 효과 — harness + ratchet 도입 전후 비용 절감 리포트
 
-![claude-token-saver 설치 전/후 효과](./docs/harness-impact.png)
+![claude-token-saver — harness + ratchet 도입 효과](./docs/harness-impact.png)
 
-저자 본인의 Claude Code 사용 로그를 **사용자 메시지 1건당**으로 정규화해 비교한 결과 (2026-05-02 적용 시점, Opus 4.7 가격 기준):
+claude-token-saver에 최근 추가된 **harness 5/5 + ratchet** 기능을 실제 적용해보고 도입 전후를 비교한 결과입니다 (저자 본인의 Claude Code 사용 로그, **사용자 메시지 1건당**으로 정규화, 2026-05-02 기준, Opus 4.7 가격):
 
-| 메트릭 | 설치 전 (7일 / 739msg) | 설치 후 (2일 / 157msg) | 변화 |
+| 메트릭 | 도입 전 (7일 / 739msg) | 도입 후 (2일 / 157msg) | 변화 |
 |---|---:|---:|---:|
 | 메시지당 비용 | $2.345 | $1.910 | **−18.6%** |
 | 메시지당 출력 토큰 | 7,391 | 6,052 | −18.1% |
 | 메시지당 assistant 왕복 | 9.73 | 8.83 | −9.2% |
 | 메시지당 도구 호출 | 5.72 | 5.25 | −8.2% |
 
-> ⚠️ **샘플 주의** — POST 데이터는 2일치(157 msgs)로 통계적 의미가 약하고, 그 주에 무슨 작업을 했냐(긴 텍스트 vs 짧은 지시)가 결과에 섞여 있습니다. 5일치가 더 쌓이는 **2026-05-09경** 같은 분석을 다시 돌려 갱신할 예정입니다.
+같은 요청을 더 적은 왕복으로 끝낸다 = 첫 시도 적중률 ↑. PEV·Structured Task가 강제로 한 번에 가게 만든 효과로 보입니다.
+
+### 캐시 히트율은 왜 이번 측정에 없는가 — Pro 플랜과의 차이
+
+이번 비교에는 **캐시 히트율 개선**이 포함되지 않았습니다. 저자는 Max 플랜이라 캐시 TTL이 1시간이고, 1시간 내내 같은 컨텍스트를 유지하며 작업해서 히트율이 이미 ~98%에 수렴해 있어 추가 개선 여지가 작습니다. **Pro 플랜 사용자(5분 TTL)는 캐시가 자주 만료되기 때문에**, harness가 만든 "한 번에 가는" 패턴 + 만료 직전 handoff 워크플로 조합으로 **히트율 자체가 올라갈 가능성이 큽니다.**
+
+### 만료 직전 handoff 워크플로
+
+statusline에 TTL이 카운트다운되는 걸 보면서, 만료 직전에 `claude-token-saver handoff`로 현재 작업 상태를 마크다운으로 백업해두고 새 캐시 사이클을 시작하는 흐름이 자리잡았습니다. 1M 컨텍스트 경고나 5H/7D cap 칩이 떠도 같은 흐름으로 처리합니다.
+
+> ⚠️ **샘플 주의** — 도입 후 데이터는 2일치(157 msgs)로 통계적 의미가 약하고, 그 주에 무슨 작업을 했냐(긴 텍스트 vs 짧은 지시)가 결과에 섞여 있어 도구 효과만 깨끗이 분리되진 않습니다. **총 7일치(추가 5일)가 쌓이는 2026-05-09경** 같은 분석을 다시 돌려 추세 안정화 여부와 함께 갱신할 예정입니다.
 
 ---
 
@@ -214,6 +224,12 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.13.3 (2026-05-04)
+- "실제 효과" 섹션을 **harness + ratchet 도입 전후 비용 절감 리포트** 형태로 재구성. Max(1h)/Pro(5m) 캐시 TTL 차이에 따른 히트율 개선 여지 차이 설명, 만료 직전 handoff 워크플로 안내, 7일치 누적 시점(2026-05-09) 갱신 예고 추가. 차트 제목도 동일하게 갱신.
+
+### v2.13.2 (2026-05-04)
+- YouTube 채널 핸들 `@DeepPulseKR`로 정정 (package.json + 두 README 일괄).
+
 ### v2.13.1 (2026-05-04)
 - README에 실제 statusline 스크린샷과 "harness 5/5 + ratchet 적용 전후 효과" 차트 추가. 자체 사용 로그 기준 메시지당 비용 −18.6%, assistant 왕복 −9.2%, 일/월/년 환산 비용 절감 임팩트 카드 포함. 샘플 주의사항·작업 토픽 변수·갱신 일정(2026-05-09) 명시.
 - npm 패키지 메타데이터(homepage / bugs / author) 정비 — DeepPulse YouTube 채널 링크 노출.

package/bin/cli.js

@@ -488,10 +488,35 @@ async function main() {
     }
 
     if (sub === 'promote') {
-      const raw = args.slice(2).join(' ').trim();
+      // Parse scope flags before stripping. Accepts: --global, --project,
+      //   --scope=global|project, --scope global|project
+      const promoteArgs = args.slice(2);
+      let scope = null;
+      const scopeFlags = new Set();
+      for (let i = 0; i < promoteArgs.length; i++) {
+        const a = promoteArgs[i];
+        if (a === '--global') { scope = 'global'; scopeFlags.add(i); }
+        else if (a === '--project') { scope = 'project'; scopeFlags.add(i); }
+        else if (a === '--scope' && promoteArgs[i + 1]) {
+          const v = promoteArgs[i + 1];
+          if (v !== 'global' && v !== 'project') {
+            console.error(`Invalid --scope value: ${v} (expected "global" or "project")`);
+            process.exit(1);
+          }
+          scope = v; scopeFlags.add(i); scopeFlags.add(i + 1); i++;
+        } else if (a.startsWith('--scope=')) {
+          const v = a.slice('--scope='.length);
+          if (v !== 'global' && v !== 'project') {
+            console.error(`Invalid --scope value: ${v} (expected "global" or "project")`);
+            process.exit(1);
+          }
+          scope = v; scopeFlags.add(i);
+        }
+      }
+      const raw = promoteArgs.filter((_, i) => !scopeFlags.has(i)).join(' ').trim();
       if (!raw) {
-        console.error('Usage: claude-token-saver harness promote <N>  # from statusline 🅷⚠ ratchet? #N');
-        console.error('   or: claude-token-saver harness promote "<rule text>"');
+        console.error('Usage: claude-token-saver harness promote [--global|--project] <N>  # from statusline 🅷⚠ ratchet? #N');
+        console.error('   or: claude-token-saver harness promote [--global|--project] "<rule text>"');
         process.exit(1);
       }
       let rule = raw;
@@ -515,8 +540,33 @@ async function main() {
         }
         rule = `반복 감지 ×${cand.count}: ${cand.pattern} — TODO: 원인·예방책 한 줄로`;
       }
-      const r = harnessPromote(rule);
-      console.log(`Appended to ${r.path}:`);
+      // Scope resolution: explicit flag wins. Otherwise prompt interactively
+      // when running on a TTY; in non-TTY (CI/scripts) require an explicit
+      // flag so the choice is never silently made for the caller.
+      if (!scope) {
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+          const readline = await import('node:readline');
+          const { homedir: hd } = await import('node:os');
+          const { findProjectRoot: fpr } = await import('../src/harness.js');
+          const projPath = `${fpr()}/.claude/ratchet.md`;
+          const globPath = `${hd()}/.claude/ratchet.md`;
+          const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+          const ask = (q) => new Promise((res) => rl.question(q, res));
+          console.log('Where should this rule live?');
+          console.log(`  [1] project  (${projPath})`);
+          console.log(`  [2] global   (${globPath})`);
+          const ans = (await ask('Choose [1/2] (default 1): ')).trim();
+          rl.close();
+          scope = (ans === '2' || ans.toLowerCase() === 'global' || ans.toLowerCase() === 'g')
+            ? 'global' : 'project';
+        } else {
+          console.error('Scope required in non-interactive mode.');
+          console.error('Pass --project or --global (or --scope=project|global).');
+          process.exit(1);
+        }
+      }
+      const r = harnessPromote(rule, { scope });
+      console.log(`Appended to ${r.path} [${r.scope}]:`);
       console.log(`  - ${rule}`);
       if (/^\d+$/.test(raw)) {
         console.log('\n👉 ratchet.md를 열어 TODO 부분을 실제 룰로 다듬어주세요.');
@@ -570,21 +620,30 @@ async function main() {
     }
 
     if (sub === 'list' || sub === 'ls') {
-      const { path, rules } = harnessListRules();
-      if (!rules.length) {
-        console.log(`No ratchet rules in ${path}`);
-        return;
-      }
-      console.log(`📋 Ratchet rules — ${path}\n`);
-      for (const r of rules) console.log(`  #${r.index}  ${r.text}`);
-      console.log('\nRemove with: claude-token-saver harness rm <N>');
+      const wantGlobal = hasFlag('--global');
+      const wantProject = hasFlag('--project') || !wantGlobal;
+      const print = (scope) => {
+        const { path, rules } = harnessListRules({ scope });
+        if (!rules.length) {
+          console.log(`No ratchet rules in ${path} [${scope}]`);
+          return;
+        }
+        console.log(`📋 Ratchet rules [${scope}] — ${path}\n`);
+        for (const r of rules) console.log(`  #${r.index}  ${r.text}`);
+        console.log('');
+      };
+      if (wantProject) print('project');
+      if (wantGlobal) print('global');
+      console.log('Remove with: claude-token-saver harness rm [--global|--project] <N>');
       return;
     }
 
     if (sub === 'rm') {
-      const raw = (args[2] || '').trim();
+      const rmScope = hasFlag('--global') ? 'global' : 'project';
+      const rmArgs = args.slice(2).filter((a) => a !== '--global' && a !== '--project');
+      const raw = (rmArgs[0] || '').trim();
       if (!/^\d+$/.test(raw)) {
-        console.error('Usage: claude-token-saver harness rm <N>   # N from `harness list`');
+        console.error('Usage: claude-token-saver harness rm [--global|--project] <N>   # N from `harness list`');
         process.exit(1);
       }
       const n = parseInt(raw, 10);
@@ -598,7 +657,7 @@ async function main() {
       console.log('   - 룰이 너무 좁아서 거의 발동 안 되나? → 그냥 두기 (비용 0)');
       console.log('   - 정말 잘못된 룰이라 확신? → 그때만 삭제');
       console.log('');
-      const r = harnessRmRule(n);
+      const r = harnessRmRule(n, { scope: rmScope });
       if (!r.ok) {
         console.error(`❌ ${r.error}`);
         if (r.rules) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.13.2",
+  "version": "2.14.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/harness.js

@@ -9,6 +9,7 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import {
   HARNESS_SECTIONS,
@@ -58,6 +59,14 @@ function ratchetMdPath(root) {
   return join(root, '.claude', 'ratchet.md');
 }
 
+function globalRatchetMdPath() {
+  return join(homedir(), '.claude', 'ratchet.md');
+}
+
+function resolveRatchetPath(scope, root) {
+  return scope === 'global' ? globalRatchetMdPath() : ratchetMdPath(root);
+}
+
 /**
  * Count how many of the 5 harness sections appear in the project's CLAUDE.md.
  * Returns { configured, total, missing, hasBlock }. Cheap enough to call from
@@ -217,8 +226,8 @@ export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false }
  * harness promote — append a one-line rule to .claude/ratchet.md.
  * Creates the file from the initial template if missing.
  */
-export function harnessPromote(ruleText, { root = findProjectRoot() } = {}) {
-  const rmPath = ratchetMdPath(root);
+export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'project' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root);
   let existing = '';
   if (existsSync(rmPath)) {
     existing = readFileSync(rmPath, 'utf8');
@@ -228,15 +237,15 @@ export function harnessPromote(ruleText, { root = findProjectRoot() } = {}) {
   }
   const next = appendRatchetRule(existing, ruleText);
   writeFileSync(rmPath, next);
-  return { path: rmPath, root };
+  return { path: rmPath, root, scope };
 }
 
 /**
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.
  */
-export function harnessListRules({ root = findProjectRoot() } = {}) {
-  const rmPath = ratchetMdPath(root);
+export function harnessListRules({ root = findProjectRoot(), scope = 'project' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root);
   if (!existsSync(rmPath)) return { path: rmPath, rules: [] };
   const lines = readFileSync(rmPath, 'utf8').split('\n');
   const rules = [];
@@ -260,8 +269,8 @@ export function harnessListRules({ root = findProjectRoot() } = {}) {
  * value is one-way accumulation; deleting should feel deliberate. The CLI
  * surfaces a "narrow the condition instead" reminder around this call.
  */
-export function harnessRmRule(n, { root = findProjectRoot() } = {}) {
-  const { path: rmPath, rules } = harnessListRules({ root });
+export function harnessRmRule(n, { root = findProjectRoot(), scope = 'project' } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope });
   if (!existsSync(rmPath)) {
     return { ok: false, error: `ratchet.md not found at ${rmPath}` };
   }