claude-token-saver 2.8.4 → 2.8.6

package/README.en.md

@@ -13,18 +13,21 @@ A CLI to **diagnose and save tokens on Claude Code**. Cache hit rate, TTL countd
 ## Install
 
 ```bash
-# 1. (existing users) remove the old package
+# (existing users) remove the old package
 npm uninstall -g claude-cache-monitor
 
-# 2. install
+# install — the postinstall hook auto-registers the Skill and statusline
 npm i -g claude-token-saver
-
-# 3. wire into Claude Code (Skill + statusline guidance)
-claude-token-saver install
 ```
 
 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
+```
+
 ## What you see after install
 
 **(A) One-shot report** — `claude-token-saver`:
@@ -67,7 +70,7 @@ Risk chips lead when something's wrong: `🚨 5H 94%`, `⚠ 1M ON`, `⚠ Cache m
 | `claude-token-saver` | Last 30 days diagnostic report |
 | `claude-token-saver --days 7` | Change window |
 | `claude-token-saver --statusline --icon` | One-line statusline output |
-| `claude-token-saver install` | Register Claude Code Skill (auto-activates on chip wording) |
+| `claude-token-saver install` | Manually register the Claude Code Skill (fallback when postinstall is skipped) |
 | `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 --install-hook` | Auto-log cache stats on every tool call |
@@ -143,6 +146,10 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 - [HN discussion](https://news.ycombinator.com/item?id=47736476) — 168 points, 142 comments
 - [HNPulse KR](https://www.youtube.com/@HNPulseKR) — Korean HN tech deep-dives
 
+## Known environment quirks
+
+**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.
+
 ## License
 
 MIT

package/README.md

@@ -2,7 +2,7 @@
 
 # claude-token-saver
 
-> v2.0에서 `claude-cache-monitor` → `claude-token-saver`로 이름이 바뀌었습니다. 기존 사용자는 [마이그레이션](#마이그레이션-claude-cache-monitor에서) 참고.
+> v2.0에서 `claude-cache-monitor` → `claude-token-saver`로 이름이 바뀌었습니다. 기존 사용자는 아래 [마이그레이션](#마이그레이션-claude-cache-monitor에서) 항목을 참고하세요.
 
 Claude Code의 **토큰 사용량을 진단·절약**하는 CLI. 캐시 히트율, TTL 카운트다운, 1M 컨텍스트 감지, 5h/7d 한도 경고를 statusline 한 줄로 보여줍니다.
 
@@ -13,18 +13,21 @@ Claude Code의 **토큰 사용량을 진단·절약**하는 CLI. 캐시 히트
 ## 설치
 
 ```bash
-# 1. (기존 사용자) 구 패키지 제거
+# (기존 사용자) 구 패키지 제거
 npm uninstall -g claude-cache-monitor
 
-# 2. 설치
+# 설치 — postinstall 훅이 Skill과 statusline을 자동 등록합니다
 npm i -g claude-token-saver
-
-# 3. Claude Code 통합 (Skill + statusline 안내)
-claude-token-saver install
 ```
 
 설치 없이 한 번만 실행하려면 `npx claude-token-saver`.
 
+`--ignore-scripts`나 sudo 등으로 postinstall이 실행되지 않은 환경에서는 다음 명령으로 수동 등록할 수 있습니다.
+
+```bash
+claude-token-saver install
+```
+
 ## 설치 후 보이는 것
 
 **(A) 단발 리포트** — `claude-token-saver` 실행 시:
@@ -44,7 +47,7 @@ TTL Breakdown / Cost Impact / Daily Trend ...
 🧠 97.5% · ⏳ 1h 42:15 · 💰 $4.8K · 🤖 Opus 4.7 · ✦ 5H 47% · 📅 7D 9%
 ```
 
-위험 상황에서는 칩이 앞으로 튀어나옵니다 — `🚨 5H 94%`, `⚠ 1M ON`, `⚠ Cache miss`, `⚠ 5m TTL` 등.
+위험 상황에서는 경고 칩이 맨 앞에 표시됩니다 — `🚨 5H 94%`, `⚠ 1M ON`, `⚠ Cache miss`, `⚠ 5m TTL` 등.
 
 ## statusline 등록
 
@@ -58,7 +61,7 @@ TTL Breakdown / Cost Impact / Daily Trend ...
 }
 ```
 
-`refreshInterval: 5`는 TTL 카운트다운이 idle 상태에서도 5초마다 갱신되게 합니다 (1초도 가능하지만 상시 I/O 부담을 피하려고 5초를 기본값으로 권장). Windows(PowerShell)는 `examples/statusline-command.ps1` 참고.
+`refreshInterval: 5`는 idle 상태에서도 TTL 카운트다운을 5초마다 갱신합니다 (1초도 가능하지만 상시 I/O 부담을 줄이기 위해 5초를 기본값으로 권장합니다). Windows(PowerShell) 환경은 `examples/statusline-command.ps1`을 참고하세요.
 
 ## 주요 명령
 
@@ -66,22 +69,22 @@ TTL Breakdown / Cost Impact / Daily Trend ...
 |---|---|
 | `claude-token-saver` | 최근 30일 진단 리포트 |
 | `claude-token-saver --days 7` | 기간 변경 |
-| `claude-token-saver --statusline --icon` | statusline용 한 줄 |
-| `claude-token-saver install` | Claude Code Skill 자동 등록 (칩 단어 언급 시 자동 활성) |
+| `claude-token-saver --statusline --icon` | statusline용 한 줄 출력 |
+| `claude-token-saver install` | Claude Code Skill 수동 등록 (postinstall이 막힌 환경 대비) |
 | `claude-token-saver history` | 최근 7일간 칩 전이 로그 (1M ON, Cache miss, cap 등) |
 | `claude-token-saver handoff` | 현재 작업을 `HANDOFF-YYYY-MM-DD-HHMM.md`로 백업 (cap 임박 시) |
 | `claude-token-saver --install-hook` | 매 도구 호출마다 캐시 통계 자동 로깅 |
 
 전체 옵션은 `--help` 또는 [영문 README](./README.en.md#options).
 
-## 진단되는 급증 원인
+## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
 |---|---|
 | `LARGE_INPUT_PER_REQUEST` | 단일 요청 250k+ → 1M 컨텍스트 의심 |
-| `LOW_HIT_RATE` | 캐시 히트율 < 50% |
-| `BUCKET_5M_DOMINANT` | 캐시 쓰기의 70%+가 5분 버킷 (Pro 플랜 또는 Max 다운그레이드) |
-| `HIGH_OUTPUT_RATIO` | 출력/입력 > 0.15 (출력은 입력의 5배 가격) |
+| `LOW_HIT_RATE` | 캐시 히트율 50% 미만 |
+| `BUCKET_5M_DOMINANT` | 캐시 쓰기의 70% 이상이 5분 버킷에 집중 (Pro 플랜 또는 Max 다운그레이드) |
+| `HIGH_OUTPUT_RATIO` | 출력/입력 비율 0.15 초과 (출력 단가가 입력의 5배) |
 | `FREQUENT_CACHE_REBUILD` | 캐시 재작성이 읽기보다 많음 |
 
 각 코드마다 OS별 해결 명령(`~/.zshrc` / `setx`)이 함께 출력됩니다.
@@ -93,16 +96,20 @@ npm uninstall -g claude-cache-monitor
 npm i -g claude-token-saver
 ```
 
-`~/.claude/settings.json`의 `statusLine.command`를 `claude-cache-monitor …` → `claude-token-saver …`로 교체하세요. v2.0 이전의 `claude-cache-monitor` 바이너리 별칭은 npm 충돌(EEXIST) 때문에 제거됐습니다.
+`~/.claude/settings.json`의 `statusLine.command`를 `claude-cache-monitor …` → `claude-token-saver …`로 교체하세요. v2.0에 잠시 제공됐던 `claude-cache-monitor` 바이너리 별칭은 글로벌 설치 시 npm 충돌(EEXIST)을 일으켜 이후 버전에서 제거됐습니다.
 
 ## 동작 원리
 
-Claude Code는 모든 API 응답을 `~/.claude/projects/<dir>/<session>.jsonl`에 기록합니다. 이 도구는 `cache_read_input_tokens`, `cache_creation.ephemeral_5m/1h_input_tokens` 등을 `requestId`로 중복 제거 후 일·세션 단위로 집계합니다.
+Claude Code는 모든 API 응답을 `~/.claude/projects/<dir>/<session>.jsonl`에 기록합니다. 이 도구는 `cache_read_input_tokens`, `cache_creation.ephemeral_5m/1h_input_tokens` 같은 필드를 `requestId` 기준으로 중복 제거한 뒤 일·세션 단위로 집계합니다.
 
 ## 환경
 
 Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
+## 알려진 환경 이슈
+
+**IntelliJ Claude Code plugin** — statusline 위젯이 이전 프레임과 새 프레임을 글자 단위로 잘못 합쳐 `Cache expires 59:548` 같은 잔재 문자열이 보이는 버그가 있습니다 (이모지가 포함된 출력에서만 재현). v2.8.5+는 `TERMINAL_EMULATOR=JetBrains-JediTerm`을 감지하면 자동으로 text 모드로 폴백해 이모지 없이 출력합니다 (`--icon` 플래그도 IntelliJ에서는 무시됩니다). 다른 터미널(iTerm, Terminal, WSL 등)에는 영향 없습니다.
+
 ## 라이선스
 
 MIT

package/bin/cli.js

@@ -700,10 +700,21 @@ async function main() {
     const { statuslineDefaults } = await import('../src/config.js');
     const cfg = statuslineDefaults();
 
+    // IntelliJ's Claude Code plugin renders the statusline through a custom
+    // widget that fuses prior frames with the new one when emoji are present,
+    // producing garbage like "59:548" that no ANSI escape can clean up
+    // (verified: emitting the same output directly into JediTerm renders
+    // cleanly, so the bug is in the plugin's render path, not the terminal).
+    // Force text mode unconditionally inside IntelliJ — even past an explicit
+    // `--icon` flag, since wrappers commonly hardcode `--icon` and the user
+    // can't easily edit them; icon mode is just broken there.
+    const isIntelliJ = process.env.TERMINAL_EMULATOR === 'JetBrains-JediTerm';
     // CLI flags take precedence; otherwise fall back to persisted config.
-    const isIcon = hasFlag('--icon')
-      ? true
-      : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+    const isIcon = isIntelliJ
+      ? false
+      : (hasFlag('--icon')
+          ? true
+          : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon));
     const isVerbose = hasFlag('--verbose')
       ? true
       : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "claude-token-saver",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
     "claude-token-saver": "bin/cli.js"
   },
+  "scripts": {
+    "postinstall": "node bin/cli.js install || true"
+  },
   "files": [
     "bin/",
     "src/",

package/src/formatters/statusline.js

@@ -103,7 +103,7 @@ function formatTimer(remainingSec) {
   // Defensive: non-finite/NaN inputs (e.g. clock skew, stringified Date) used
   // to slip through and render as "NaN:NaN" or stretched seconds. Treat any
   // weird input as expired rather than rendering garbage in the statusline.
-  if (!Number.isFinite(remainingSec) || remainingSec <= 0) return padTimer('EXPIRED');
+  if (!Number.isFinite(remainingSec) || remainingSec <= 0) return 'EXPIRED';
   const totalSec = Math.max(0, Math.floor(remainingSec));
   const h = Math.floor(totalSec / 3600);
   const mRaw = Math.floor((totalSec % 3600) / 60);
@@ -112,22 +112,8 @@ function formatTimer(remainingSec) {
   // truncation) can never produce m:sss like "4:547".
   const m = Math.min(59, Math.max(0, mRaw));
   const s = Math.min(59, Math.max(0, sRaw));
-  if (h > 0) return padTimer(`${h}:${String(m).padStart(2, '0')}`);
-  return padTimer(`${m}:${String(s).padStart(2, '0')}`);
-}
-
-// Pad timer text to a fixed width so transitions never shrink the visible
-// length. Otherwise `42:38` (5 chars) → `1:00` (4 chars) on activity reset
-// leaves the trailing `8` on screen → fused garbage like `1:008`. Some
-// terminals (JetBrains JediTerm, certain Claude Code render paths) don't
-// fully clear the statusline region between frames, so column-stable output
-// is the only reliable defense — `\x1b[K` and trailing-space padding only
-// help if the cursor lands at the right spot to begin with.
-//   "EXPIRED" → "EXPIRED" (7 — already widest, used as the target width)
-//   "59:59"   → " 59:59 " no — left-pad only so the digits stay right-aligned
-const TIMER_WIDTH = 7;
-function padTimer(s) {
-  return s.padStart(TIMER_WIDTH, ' ');
+  if (h > 0) return `${h}:${String(m).padStart(2, '0')}`;
+  return `${m}:${String(s).padStart(2, '0')}`;
 }
 
 /**
@@ -409,19 +395,8 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (want('saved')) segs.push(saveSeg);
   if (want('period')) segs.push(periodSeg);
   // Trailing erase-to-end-of-line so any leftover characters from a previous
-  // (longer) statusline render don't bleed into ours. Some terminals + the
-  // Claude Code statusline integration don't fully clear the line on rewrite,
-  // which surfaced as "Cache expires 4:574" or "Cache expires 43550" — old
-  // digits from a prior frame leaking past the new shorter timer text.
-  // \x1b[K is the standard "erase from cursor to EOL" CSI; safe on any
-  // ANSI-compatible terminal and a no-op when stdout isn't a TTY.
-  // Defensive overwrite — terminals that miscount emoji width (JetBrains JediTerm
-  // is the known case, but others surface periodically) leave the cursor at the
-  // wrong column, which makes trailing `\x1b[K` erase the wrong region and
-  // leftover bytes from the previous frame fuse with the new one ("4:54" + "8"
-  // → "4:548"). Appending a run of spaces overwrites those leftover bytes
-  // positionally without any clear-then-redraw step (so no flicker), and is
-  // invisible on terminals that already redraw cleanly. `\x1b[K` still mops up
-  // anything beyond the padding.
-  return segs.join(' · ') + ' '.repeat(40) + '\x1b[K';
+  // (longer) statusline render don't bleed into ours. \x1b[K is the standard
+  // "erase from cursor to EOL" CSI; safe on any ANSI-compatible terminal and
+  // a no-op when stdout isn't a TTY.
+  return segs.join(' · ') + '\x1b[K';
 }