claude-token-saver 2.8.5 → 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 |

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,11 +96,11 @@ 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` 기준으로 중복 제거한 뒤 일·세션 단위로 집계합니다.
 
 ## 환경
 
@@ -105,7 +108,7 @@ 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 등)에는 영향 없습니다.
+**IntelliJ Claude Code plugin** — statusline 위젯이 이전 프레임과 새 프레임을 글자 단위로 잘못 합쳐 `Cache expires 59:548` 같은 잔재 문자열이 보이는 버그가 있습니다 (이모지가 포함된 출력에서만 재현). v2.8.5+는 `TERMINAL_EMULATOR=JetBrains-JediTerm`을 감지하면 자동으로 text 모드로 폴백해 이모지 없이 출력합니다 (`--icon` 플래그도 IntelliJ에서는 무시됩니다). 다른 터미널(iTerm, Terminal, WSL 등)에는 영향 없습니다.
 
 ## 라이선스
 

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "claude-token-saver",
-  "version": "2.8.5",
+  "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/",