claude-token-saver 2.14.1 → 2.15.0

package/README.en.md

@@ -1,6 +1,8 @@
 [한국어](./README.md) · **English**
 
 [![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@DeepPulseKR-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseKR)
+[![DeepPulseEN YouTube](https://img.shields.io/badge/YouTube-@DeepPulseEN-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseEN)
+[![Homepage](https://img.shields.io/badge/Homepage-rootstudioyaml.github.io-2ea44f)](https://rootstudioyaml.github.io/)
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
 # claude-token-saver
@@ -256,7 +258,9 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 - [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
-- [HNPulse KR](https://www.youtube.com/@DeepPulseKR) — Korean HN tech deep-dives
+- [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
 
 ## Known environment quirks
 
@@ -264,6 +268,11 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## 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.
+
 ### 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.
 

package/README.md

@@ -1,6 +1,8 @@
 **한국어** · [English](./README.en.md)
 
 [![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@DeepPulseKR-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseKR)
+[![DeepPulseEN YouTube](https://img.shields.io/badge/YouTube-@DeepPulseEN-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseEN)
+[![Homepage](https://img.shields.io/badge/Homepage-rootstudioyaml.github.io-2ea44f)](https://rootstudioyaml.github.io/)
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
 # claude-token-saver
@@ -224,6 +226,11 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.15.0 (2026-06-13)
+- **글로벌 harness init** — `harness init`/`uninit`/`check`에 ratchet과 동일한 스코프 개념 도입. `harness init --global`이 `~/.claude/CLAUDE.md`(+ `~/.claude/ratchet.md`)에 5개 섹션을 한 번에 깔아 **모든 프로젝트에 적용**됩니다. 무플래그 기본값은 종전대로 `project`(하위호환).
+- `harness check`는 이제 글로벌을 **fallback**으로 인정 — 로컬 블록이 없어도 글로벌 harness가 깔려 있으면 `🅷 5/5 (covered by global)`로 표시(Claude Code가 전역 `CLAUDE.md`를 모든 프로젝트에 로드하는 실제 동작과 일치). `--project`/`--global`로 특정 스코프만 조회 가능.
+- npm 패키지 homepage를 `https://rootstudioyaml.github.io/`로 변경, README에 **@DeepPulseEN** 채널·홈페이지 배지 추가.
+
 ### v2.13.3 (2026-05-04)
 - "실제 효과" 섹션을 **harness + ratchet 도입 전후 비용 절감 리포트** 형태로 재구성. Max(1h)/Pro(5m) 캐시 TTL 차이에 따른 히트율 개선 여지 차이 설명, 만료 직전 handoff 워크플로 안내, 7일치 누적 시점(2026-05-09) 갱신 예고 추가. 차트 제목도 동일하게 갱신.
 

package/bin/cli.js

@@ -24,7 +24,7 @@
 
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 
 /**
  * Read the JSON blob Claude Code feeds the statusline command on stdin.
@@ -452,24 +452,44 @@ async function main() {
   //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
+    // Scope flags for init/uninit/check (same convention as promote/list/rm):
+    //   --global | --project | --scope=global|project | --scope global|project
+    const parseHarnessScope = (argv, dflt) => {
+      for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--global') return 'global';
+        if (a === '--project') return 'project';
+        if (a === '--scope' && (argv[i + 1] === 'global' || argv[i + 1] === 'project')) return argv[i + 1];
+        if (a.startsWith('--scope=')) {
+          const v = a.slice('--scope='.length);
+          if (v === 'global' || v === 'project') return v;
+        }
+      }
+      return dflt;
+    };
     const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessListRules, harnessRmRule, findProjectRoot } =
       await import('../src/harness.js');
     const { HARNESS_SECTIONS } = await import('../src/harness-templates.js');
     const { loadConfig, saveConfig } = await import('../src/config.js');
 
     if (!sub || sub === 'check') {
+      const scope = parseHarnessScope(args.slice(2), 'auto'); // auto = project, else global fallback
       const root = findProjectRoot();
-      const s = harnessStatus(root);
-      console.log(`🅷 ${s.configured}/${s.total} — ${root}`);
+      const s = harnessStatus(root, { scope });
+      // Only call out "covered by global" when we *fell back* to it (auto), not
+      // when the user explicitly asked for the global scope.
+      const via = (scope === 'auto' && s.source === 'global') ? ' (covered by global ~/.claude/CLAUDE.md)' : '';
+      console.log(`🅷 ${s.configured}/${s.total} — ${s.file}${via}`);
       console.log(`CLAUDE.md: ${s.hasFile ? 'present' : 'missing'}` +
-        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : ''));
+        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : '') + ` [${s.source}]`);
       if (s.missing.length) {
         console.log('Missing sections:');
         for (const id of s.missing) {
           const sec = HARNESS_SECTIONS.find((x) => x.id === id);
           console.log(`  - ${id}: ${sec ? sec.heading.replace(/^#+\s*/, '') : ''}`);
         }
-        console.log('\nRun: claude-token-saver harness init');
+        console.log('\nRun: claude-token-saver harness init        (this project)');
+        console.log('  or: claude-token-saver harness init --global  (all projects, ~/.claude/CLAUDE.md)');
       } else {
         console.log('All 5 harness sections present. ✅');
       }
@@ -477,9 +497,10 @@ async function main() {
     }
 
     if (sub === 'init') {
+      const scope = parseHarnessScope(args.slice(2), 'project'); // default project (back-compat)
       const force = hasFlag('--force');
-      const r = harnessInit({ force });
-      console.log(`Project root: ${r.root}`);
+      const r = harnessInit({ force, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md — applies to all projects)' : `  (${r.root})`}`);
       for (const p of r.backedUp) console.log(`Backed up: ${p}`);
       for (const p of r.wrote) console.log(`Wrote:     ${p}`);
       for (const p of r.skipped) console.log(`Skipped:   ${p}`);
@@ -609,9 +630,10 @@ async function main() {
     }
 
     if (sub === 'uninit' || sub === 'remove') {
+      const scope = parseHarnessScope(args.slice(2), 'project');
       const purgeRatchet = args.includes('--purge-ratchet');
-      const r = harnessUninit({ purgeRatchet });
-      console.log(`Project root: ${r.root}`);
+      const r = harnessUninit({ purgeRatchet, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md)' : `  (${r.root})`}`);
       r.removed.forEach((f) => console.log(`  removed: ${f}`));
       r.backedUp.forEach((f) => console.log(`  backup:  ${f}`));
       r.skipped.forEach((f) => console.log(`  skip:    ${f}`));
@@ -804,12 +826,16 @@ async function main() {
     process.stderr.write('Scanning session files...\n');
   }
 
-  // Exclude the current Claude Code session when computing lastActivity —
-  // otherwise the agent's own tool calls reset the countdown every few seconds.
+  // The current Claude Code session is only excluded from the lastActivity
+  // timer (so the agent's own tool calls don't reset the countdown). It MUST
+  // still feed ttlBreakdown — otherwise when the user's only recent traffic
+  // lives in the current session, the bucket signal collapses to empty and
+  // the statusline falsely flips to the 5m default. (See issue: Max users
+  // seeing "Cache expires 5:00" on idle even though their plan is 1h.)
   const excludeSessionPath =
     getArg('--exclude-session') || process.env.CACHE_MONITOR_EXCLUDE_SESSION || undefined;
 
-  const sessions = await parseAllSessions({ days, projectFilter, excludeSessionPath });
+  const sessions = await parseAllSessions({ days, projectFilter });
 
   if (sessions.length === 0) {
     // Statusline must always emit a single line (no multi-line help spam every 300ms)
@@ -913,10 +939,16 @@ async function main() {
   }
 
   // Last API activity feeds the statusline TTL countdown.
-  // For every session that wasn't excluded, take the full endTime (any API call
-  // keeps the prefix cache warm — it doesn't matter whether it's user- or
-  // agent-driven because the cache is shared across sessions by prefix content).
+  // For every session OTHER than the excluded (current) one, take the full
+  // endTime (any API call keeps the prefix cache warm — it doesn't matter
+  // whether it's user- or agent-driven because the cache is shared across
+  // sessions by prefix content). The current session is filtered here rather
+  // than at the parser, so its writes still inform ttlBreakdown above.
+  const excludeAbs = excludeSessionPath
+    ? (isAbsolute(excludeSessionPath) ? excludeSessionPath : join(process.cwd(), excludeSessionPath))
+    : null;
   const otherLastActivity = sessions
+    .filter((s) => !excludeAbs || s.filePath !== excludeAbs)
     .map((s) => (s.endTime ? s.endTime.getTime() : 0))
     .reduce((a, b) => Math.max(a, b), 0);
   // For the excluded (current) session, only the user's prompts count — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "type": "git",
     "url": "git+https://github.com/rootstudioyaml/claude-token-saver.git"
   },
-  "homepage": "https://www.youtube.com/@DeepPulseKR",
+  "homepage": "https://rootstudioyaml.github.io/",
   "bugs": {
     "url": "https://github.com/rootstudioyaml/claude-token-saver/issues"
   },

package/src/formatters/statusline.js

@@ -158,9 +158,14 @@ export function formatReport(data, { color = true, verbose = false, timer = true
 
   // TTL dominance → color signal (1h = good, 5m = warning).
   // The subscription plan fixes this, so the bucket rarely changes — it's the countdown that matters.
-  const is1h = ttl.pct1h >= 0.5;
-  const bucketLabel = is1h ? '1h' : '5m';
-  const bucketColor = is1h ? GREEN : YELLOW;
+  // When ttl.total === 0 (no cache writes observed in the window), we cannot
+  // infer the bucket. Default to 1h-sized countdown rather than 5m so Max
+  // users on idle don't see a misleading "Cache expires 5:00". The bucket
+  // label is shown as "?" so the uncertainty is visible.
+  const hasTtlData = ttl.total > 0;
+  const is1h = hasTtlData ? ttl.pct1h >= 0.5 : true;
+  const bucketLabel = hasTtlData ? (is1h ? '1h' : '5m') : '?';
+  const bucketColor = hasTtlData ? (is1h ? GREEN : YELLOW) : GRAY;
   const ttlSeconds = is1h ? 3600 : 300;
 
   const savings = cost?.savings ?? 0;

package/src/harness.js

@@ -67,28 +67,41 @@ function resolveRatchetPath(scope, root) {
   return scope === 'global' ? globalRatchetMdPath() : ratchetMdPath(root);
 }
 
+// Global harness lives in ~/.claude/CLAUDE.md — Claude Code loads this for every
+// project, so a global init makes the 5 harness sections apply everywhere
+// (mirrors the project/global split that ratchet.md already has).
+function globalClaudeMdPath() {
+  return join(homedir(), '.claude', 'CLAUDE.md');
+}
+
+function resolveClaudeMdPath(scope, root) {
+  return scope === 'global' ? globalClaudeMdPath() : claudeMdPath(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
  * statusline — single file read + regex.
  */
-export function harnessStatus(root = findProjectRoot()) {
-  const path = claudeMdPath(root);
-  if (!existsSync(path)) {
+// Count harness sections in a single CLAUDE.md file. Shared by both scopes.
+function statusForFile(filePath) {
+  if (!existsSync(filePath)) {
     return {
       configured: 0,
       total: HARNESS_SECTIONS.length,
       missing: HARNESS_SECTIONS.map((s) => s.id),
       hasBlock: false,
       hasFile: false,
-      root,
+      optOut: false,
+      custom: false,
+      file: filePath,
     };
   }
   let content = '';
   try {
-    content = readFileSync(path, 'utf8');
+    content = readFileSync(filePath, 'utf8');
   } catch {
-    return { configured: 0, total: HARNESS_SECTIONS.length, missing: [], hasBlock: false, hasFile: true, root };
+    return { configured: 0, total: HARNESS_SECTIONS.length, missing: [], hasBlock: false, hasFile: true, optOut: false, custom: false, file: filePath };
   }
   const hasBlock = content.includes(HARNESS_BLOCK_BEGIN);
   // Opt-out marker — when the user intentionally customizes the harness block
@@ -114,10 +127,30 @@ export function harnessStatus(root = findProjectRoot()) {
     hasFile: true,
     optOut,
     custom,
-    root,
+    file: filePath,
   };
 }
 
+/**
+ * Harness status for a project, with scope control:
+ *   scope 'project' — count only <root>/CLAUDE.md
+ *   scope 'global'  — count only ~/.claude/CLAUDE.md
+ *   scope 'auto' (default) — use the project file if it carries the harness
+ *     block, otherwise fall back to the global file. This makes a project that
+ *     relies on a globally-installed harness report 🅷 5/5 (covered by global),
+ *     matching reality: Claude Code loads ~/.claude/CLAUDE.md for every project.
+ * The returned `source` ('project'|'global') tells callers which file was used.
+ */
+export function harnessStatus(root = findProjectRoot(), { scope = 'auto' } = {}) {
+  if (scope === 'project') return { ...statusForFile(claudeMdPath(root)), root, source: 'project' };
+  if (scope === 'global') return { ...statusForFile(globalClaudeMdPath()), root, source: 'global' };
+  const project = statusForFile(claudeMdPath(root));
+  if (project.hasBlock) return { ...project, root, source: 'project' };
+  const global = statusForFile(globalClaudeMdPath());
+  if (global.hasBlock) return { ...global, root, source: 'global' };
+  return { ...project, root, source: 'project' };
+}
+
 /**
  * harness init — write CLAUDE.md (single file, 5 sections) + .claude/ratchet.md.
  * If CLAUDE.md exists, back it up to CLAUDE.md.bak-YYYYMMDD-HHMMSS first
@@ -125,10 +158,10 @@ export function harnessStatus(root = findProjectRoot()) {
  *
  * Returns { wrote: [], backedUp: [], skipped: [] } so the CLI can report.
  */
-export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
-  const cmPath = claudeMdPath(root);
-  const rmPath = ratchetMdPath(root);
-  const result = { wrote: [], backedUp: [], skipped: [], root };
+export function harnessInit({ root = findProjectRoot(), force = false, scope = 'project' } = {}) {
+  const cmPath = resolveClaudeMdPath(scope, root); // global → ~/.claude/CLAUDE.md
+  const rmPath = resolveRatchetPath(scope, root);  // global → ~/.claude/ratchet.md
+  const result = { wrote: [], backedUp: [], skipped: [], root, scope };
 
   // CLAUDE.md
   const block = harnessClaudeMdBlock();
@@ -158,11 +191,12 @@ export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
       result.wrote.push(cmPath + ' (harness block appended)');
     }
   } else {
+    mkdirSync(dirname(cmPath), { recursive: true }); // global: ensure ~/.claude exists
     writeFileSync(cmPath, block);
     result.wrote.push(cmPath);
   }
 
-  // .claude/ratchet.md (only if missing — don't clobber user-grown rules)
+  // ratchet.md (only if missing — don't clobber user-grown rules)
   if (!existsSync(rmPath)) {
     mkdirSync(dirname(rmPath), { recursive: true });
     writeFileSync(rmPath, harnessRatchetMdInitial());
@@ -181,10 +215,10 @@ export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
  *
  * Returns { removed: [], backedUp: [], skipped: [] }.
  */
-export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false } = {}) {
-  const cmPath = claudeMdPath(root);
-  const rmPath = ratchetMdPath(root);
-  const result = { removed: [], backedUp: [], skipped: [], root };
+export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false, scope = 'project' } = {}) {
+  const cmPath = resolveClaudeMdPath(scope, root);
+  const rmPath = resolveRatchetPath(scope, root);
+  const result = { removed: [], backedUp: [], skipped: [], root, scope };
 
   if (existsSync(cmPath)) {
     const existing = readFileSync(cmPath, 'utf8');