claude-token-saver 2.0.0

package/README.md

@@ -0,0 +1,346 @@
+# claude-token-saver
+
+> **Renamed from `claude-cache-monitor` in v2.0.** The old name still works — `npm i claude-cache-monitor` now redirects here, and the `claude-cache-monitor` binary remains available as an alias. See [migration notes](#migration-from-claude-cache-monitor).
+
+> 📺 **HNPulse Shorts** — 이 도구가 만들어진 배경 (캐시 TTL 1h→5m 변경 이슈):
+> **[▶ Watch the Short](https://www.youtube.com/shorts/oSx2sg935nI)** · [All HNPulse Shorts](https://www.youtube.com/@HNPulseKR/shorts)
+>
+> [![HNPulse Short](https://img.youtube.com/vi/oSx2sg935nI/hqdefault.jpg)](https://www.youtube.com/shorts/oSx2sg935nI)
+
+**Save tokens on Claude Code.** Catch the session that suddenly burned 10× your usual input, figure out *why*, and get a one-line remediation you can paste.
+
+v1.5 adds three things on top of the original cache monitor:
+- **Spike diagnosis** — detect recent sessions whose input tokens exploded vs. your own baseline, and name the cause (1M context, 5m TTL churn, cache rebuild, chatty output).
+- **1M-context detection** — Opus 4.7+ auto-enables 1M context on Max plans, silently. This tool surfaces it on the statusline as `Ctx 1M` (red) vs. `Ctx 200k` (green), with the OS-specific command to turn it off.
+- **Actionable advice** — OS-aware remediation (`~/.zshrc` vs. `setx`) and the warning for the known `/model` toggle bug ([anthropics/claude-code#31640](https://github.com/anthropics/claude-code/issues/31640)).
+
+The original functionality still works: cache hit rate, TTL breakdown, cost impact vs. no-cache, TTL countdown timer, and Claude Code statusline integration.
+
+---
+
+**Claude Code 토큰 아껴쓰기 도구.** 평소보다 10배 토큰을 태운 세션을 찾고, *왜 튀었는지* 진단하고, 붙여넣을 수 있는 한 줄 해결책까지 내줍니다.
+
+v1.5 신규:
+- **토큰 급증 진단** — 최근 세션 중 내 평소 기준보다 입력 토큰이 폭증한 세션을 찾아 원인까지 분류 (1M 컨텍스트 / 5분 TTL 반복 쓰기 / 캐시 재작성 / 출력 과다).
+- **1M 컨텍스트 감지** — Opus 4.7부터 Max 플랜은 1M 컨텍스트가 자동 ON. Statusline에 `Ctx 1M`(빨강) / `Ctx 200k`(초록)으로 표시하고, OS별 OFF 명령까지 안내.
+- **실행 가능한 권장 액션** — macOS/Linux/WSL는 `~/.zshrc`, Windows는 `setx` 명령. [`/model`로 200k 선택해도 1M에 머무는 알려진 버그](https://github.com/anthropics/claude-code/issues/31640)에 대한 경고 포함.
+
+기존 기능(캐시 히트율·TTL 분포·비용 절감·TTL 카운트다운·statusline)은 그대로 유지됩니다.
+
+## Quick Start
+
+```bash
+# Run instantly (no install required)
+npx claude-token-saver
+
+# Last 7 days only
+npx claude-token-saver --days 7
+
+# JSON output (for pipelines)
+npx claude-token-saver --format json
+
+# CSV output (for spreadsheets)
+npx claude-token-saver --format csv
+```
+
+## Spike Diagnosis (new in v1.5.0)
+
+When you run `npx claude-token-saver`, sessions from the last 24 hours whose total input tokens are **≥ 3× your p95 baseline** (or whose single-request context exceeds 250k, indicating 1M context) appear at the top of the report with root causes and remediation commands. Example output:
+
+```
+  ⚠ 토큰 급증 감지
+  ──────────────────────────────────────────────────
+  컨텍스트 모드 추정: 1M  (최근 단일 요청 최대 480k 토큰)
+
+  • a1b2c3d4 [myproject]  총 입력 320.45M  (5.2× p95, 요청 142회)
+      단일 요청 최대 컨텍스트: 480k 토큰
+      · 요청당 입력 토큰이 평소보다 매우 큽니다 (1M 컨텍스트 의심)
+
+  권장 액션
+  ──────────────────────────────────────────────────
+  ▸ 요청당 입력 토큰이 평소보다 매우 큽니다 (1M 컨텍스트 의심)
+    Opus 4.7부터 1M 컨텍스트가 표준 가격으로 풀리면서 Max 플랜은 자동으로 1M로 승격됩니다 ...
+    - 1M 컨텍스트 OFF (환경변수)
+        echo 'export CLAUDE_CODE_DISABLE_1M_CONTEXT=1' >> ~/.zshrc && source ~/.zshrc
+    - 세션 내 토글
+        단축키 ⌥ P (mac) / Alt + P (linux) 로 즉시 On/Off
+    - ⚠ 알려진 버그 #31640
+        /model 로 200k 선택해도 컨텍스트가 1M에 머무는 케이스가 있습니다.
+        확실히 끄려면 위 환경변수를 설정한 뒤 Claude Code를 재시작하세요.
+```
+
+Issue codes detected:
+
+| Code | Meaning |
+|---|---|
+| `LARGE_INPUT_PER_REQUEST` | avg input/request is 8×+ your baseline, or a single request > 250k tokens → 1M context likely |
+| `LOW_HIT_RATE` | cache hit rate < 50% and materially below your baseline |
+| `BUCKET_5M_DOMINANT` | > 70% of cache writes land in the 5m bucket (Pro plan, or Max users getting downgraded) |
+| `HIGH_OUTPUT_RATIO` | output/input > 0.15 (output is 5× input price — matters a lot) |
+| `HIGH_REQUEST_COUNT` | session made 3×+ your median request count (tool-loop suspect) |
+| `FREQUENT_CACHE_REBUILD` | `cache_creation` > `cache_read` (cache being made, not reused) |
+
+Remediation commands are chosen from `process.platform` — macOS/Linux/WSL get `~/.zshrc` snippets, Windows gets `setx` and the PowerShell equivalent.
+
+## Statusline Mode (new in v1.2.0)
+
+Always-on one-line display in Claude Code's native statusline — no need to run commands manually.
+
+Claude Code 내장 statusline에 한 줄로 상시 표시. 커맨드 수동 실행 불필요.
+
+```bash
+# Preview (prints one line — text mode, default)
+npx claude-token-saver --statusline
+#  → Cache hit 97.5% · Expires 1h 42:15 · Cost saved $4.8K · Ctx 200k · 7d
+
+# When 1M context is silently on and a session is spiking:
+#  → Cache hit 88.0% · Expires 1h 42:15 · Cost saved $4.8K · Ctx 1M · ⚠ 1M컨텍스트 · 7d
+
+# Icon mode (🧠 / ⏳ / 💰 / 📦)
+npx claude-token-saver --statusline --icon
+#  → 🧠 97.5% · ⏳ 1h 42:15 · 💰 $4.8K · 📦 200k · 7d
+
+# Verbose (longer labels; combines with --icon too)
+npx claude-token-saver --statusline --verbose
+#  → Cache hit 97.5% · 1h bucket · expires in 42:15 · Cost saved $4.8K · last 7d
+
+npx claude-token-saver --statusline --icon --verbose
+#  → 🧠 Cache hit 97.5% · ⏳ Expires 1h 42:15 · 💰 Cost saved $4.8K · last 7d
+
+# Hide the TTL countdown
+npx claude-token-saver --statusline --no-timer
+
+# No ANSI color (plain text)
+npx claude-token-saver --statusline --no-color
+```
+
+### TTL countdown (v1.2.1+)
+
+Your subscription plan fixes the TTL bucket (5m for Pro, 1h for Max) — the actionable number isn't the bucket, it's **how much time is left on your last API call's cache entry**. The `TTL 1h MM:SS` segment is a live stopwatch against the dominant bucket:
+
+구독 플랜이 TTL 값(Pro = 5분, Max = 1시간)을 고정하므로 의미 있는 수치는 "버킷"이 아니라 "마지막 API 호출의 캐시가 만료되기까지 몇 초"입니다. `TTL 1h MM:SS` 세그먼트가 그 스톱워치입니다 (앞쪽이 버킷, 뒤쪽이 남은 시간):
+
+- 🟢 &gt;30% remaining — plenty of time to send the next prompt within TTL
+- 🟡 10–30% remaining — consider firing a cheap prompt soon to keep prefix cached
+- 🔴 &lt;10% remaining or `EXPIRED` — next prompt will pay cache-write cost again
+
+This enables the "5-minute rule" in practice: a quick dummy question before the timer hits zero resets the TTL and preserves the prefix cache.
+
+### Enable in Claude Code
+
+The Claude Code statusline is event-driven — it only re-renders on assistant messages / mode changes. To keep the countdown ticking while you're idle, set `refreshInterval: 1` alongside the `statusLine` command.
+
+#### macOS / Linux / WSL
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-token-saver --statusline --icon",
+    "refreshInterval": 1
+  }
+}
+```
+
+Or combine with an existing statusline script — see [`examples/statusline-command.sh`](examples/statusline-command.sh) for a drop-in that prints `user@host:cwd | <cache monitor>`.
+
+#### Windows (native PowerShell, not WSL)
+
+Use the PowerShell example in [`examples/statusline-command.ps1`](examples/statusline-command.ps1):
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File %USERPROFILE%\\.claude\\statusline-command.ps1",
+    "refreshInterval": 1
+  }
+}
+```
+
+Works best in **Windows Terminal** or **PowerShell 7+** (ANSI color + emoji). Classic `conhost cmd` may garble emoji — prefer `--no-icon`-style plain text or use Windows Terminal.
+
+#### Windows (WSL)
+
+Same as Linux — install the package in your WSL Node.js and point to the POSIX sh script.
+
+#### Combine with rz1989s/claude-code-statusline
+
+If you already use [rz1989s/claude-code-statusline](https://github.com/rz1989s/claude-code-statusline) for its rich layout (repo, cost, MCP, prayer times, themes), drop in [`examples/statusline-with-rz1989s.sh`](examples/statusline-with-rz1989s.sh) to append our cache segment at the end — no conflict, no feature overlap.
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash ~/.claude/statusline-with-rz1989s.sh",
+    "refreshInterval": 1
+  }
+}
+```
+
+---
+
+Claude Code calls this every ~300ms on events, plus once per `refreshInterval` second while idle. Colors are emitted when the terminal supports them:
+
+- **Hit rate** — 🟢 ≥85% · 🟡 70–85% · 🔴 <70%
+- **TTL bucket** — 🟢 1h (good) · 🟡 5m (warning)
+- **Countdown** — 🟢 >30% remaining · 🟡 10–30% · 🔴 <10% or EXPIRED
+- **Context window** — 🟢 `Ctx 200k` (standard) · 🔴 `Ctx 1M` (Opus 4.7+ Max auto-enabled — expensive if unintended)
+- **Spike chip** — appears only when the current session is flagged (e.g. `⚠ 1M컨텍스트`, `⚠ 5m TTL`, `⚠ 캐시미스`, `⚠ 입력폭주`)
+
+Statusline mode uses the last 7 days by default (override with `--days N`) and never emits multi-line errors, so your statusline stays clean even when there's no session data yet.
+
+## Hook Setup
+
+Automatically logs cache stats on every tool call and alerts when hit rate drops below a threshold.
+
+매 도구 호출마다 자동으로 캐시 통계를 기록하고, 히트율이 임계값 이하로 떨어지면 경고합니다.
+
+```bash
+# Install hook (default threshold 70%)
+npx claude-token-saver --install-hook
+
+# Custom threshold
+npx claude-token-saver --install-hook --threshold 0.8
+
+# Remove hook
+npx claude-token-saver --uninstall-hook
+```
+
+When the hook is installed:
+- Session-level stats are automatically recorded to `~/.claude/cache-stats.jsonl`
+- A warning is displayed in Claude Code when hit rate falls below the threshold
+
+## Output Example
+
+```
+  Claude Cache Monitor — Last 30 days
+  ══════════════════════════════════════════════════
+
+  Summary
+  Sessions: 380  |  API calls: 10,813  |  Model: claude-opus-new
+  Cache hit rate: 98.2%  |  Total input: 1957.94M tokens
+
+  TTL Breakdown
+  ┌────────────────────┬──────────────────┬──────────────────┐
+  │                    │     5m Ephemeral │      1h Extended │
+  ├────────────────────┼──────────────────┼──────────────────┤
+  │ Cache writes       │    167.7K (0.5%) │    34.8M (99.5%) │
+  └────────────────────┴──────────────────┴──────────────────┘
+
+  Cost Impact (estimated)
+  ┌──────────────────────────┬──────────────┐
+  │ Actual cost              │      $793.93 │
+  │ Without cache            │     $5958.52 │
+  ├──────────────────────────┼──────────────┤
+  │ Savings                  │ $5164.6 (86.7%) │
+  │ Extra cost if 5m-only    │     +$239.99 │
+  └──────────────────────────┴──────────────┘
+
+  Daily Trend
+  ┌────────────┬──────────┬─────────┬────────────┬────────────┬───────┐
+  │ Date       │  HitRate │   Calls │       Read │      Write │   5m% │
+  ├────────────┼──────────┼─────────┼────────────┼────────────┼───────┤
+  │ 2026-04-10 │    98.5% │     341 │     88.98M │      1.35M │  0.0% │
+  │ 2026-04-11 │    97.1% │     118 │      9.51M │      0.27M │  0.0% │
+  │ 2026-04-12 │    91.7% │      77 │      2.69M │      0.22M │  0.0% │
+  └────────────┴──────────┴─────────┴────────────┴────────────┴───────┘
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--days, -d` | Analysis period in days | 30 |
+| `--format, -f` | Output format: `table`, `json`, `csv` | table |
+| `--project, -p` | Filter by project directory | all |
+| `--threshold` | Cache hit rate alert threshold (0.0-1.0) | 0.7 |
+| `--install-hook` | Install Claude Code PostToolUse hook | - |
+| `--uninstall-hook` | Remove hook | - |
+| `--statusline` | Emit one-line output for Claude Code statusline API | - |
+| `--icon` | (with `--statusline`) use 🧠 / ⏳ / 💰 icons instead of word labels | text |
+| `--verbose` | (with `--statusline`) use longer labels | - |
+| `--no-timer` | (with `--statusline`) hide the TTL countdown | show |
+| `--no-color` | Strip ANSI escape codes | - |
+
+Statusline segments always include the context-window chip (`Ctx 200k`/`Ctx 1M` or `📦 200k`/`📦 1M` in `--icon` mode). A spike chip is appended only when the most recent session is diagnosed as a spike.
+
+## How It Works
+
+Claude Code logs usage data for every API call into session JSONL files:
+
+```
+~/.claude/projects/<project-dir>/<session-id>.jsonl
+```
+
+Each API response contains these fields:
+- `cache_read_input_tokens` — tokens read from cache (cheap, 0.1x)
+- `cache_creation_input_tokens` — tokens written to cache (expensive, 1.25x~2x)
+- `cache_creation.ephemeral_5m_input_tokens` — tokens created with 5-minute TTL
+- `cache_creation.ephemeral_1h_input_tokens` — tokens created with 1-hour TTL
+
+This tool deduplicates streaming chunks by `requestId` and aggregates by day/session.
+
+## Key Findings
+
+Cache TTL is determined by your subscription plan, not by user choice:
+
+| Plan | Cache TTL | Controlled by |
+|------|-----------|---------------|
+| **Max** ($100~200/mo) | **1h automatic** | `tengu_prompt_cache_1h_config` feature flag |
+| **Pro** ($20/mo) | **5m fixed** | Not configurable |
+| **API key** | **5m default** (1h via beta header) | `cache_control.ttl` parameter |
+
+## Pricing (updated 2026-04 for Opus 4.7)
+
+Cost estimates use current Anthropic pricing, auto-detected from the model id in session logs:
+
+| Tier (internal id) | Matching models | Input | 5m Cache Write | 1h Cache Write | Cache Read | Output |
+|---|---|---|---|---|---|---|
+| `claude-opus-new` | Opus **4.5 / 4.6 / 4.7** | $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-haiku-4-5` | Haiku 4.5 | $1 | $1.25 | $2 | $0.10 | $5 |
+| `claude-haiku-3-5` | Haiku 3.5 | $0.80 | $1 | $1.6 | $0.08 | $4 |
+| `claude-haiku-3` | Haiku 3 | $0.25 | $0.30 | $0.50 | $0.03 | $1.25 |
+
+5m and 1h cache writes are now billed at separate rates (previously applied a single blended rate). Prior versions (≤ 1.0.x) used legacy Opus 4 pricing for all Opus models, over-estimating Opus 4.5+ costs by ~3x — **upgrade to 1.1.0 if you run Opus 4.5 or newer**.
+
+Source: [Anthropic pricing documentation](https://docs.claude.com/en/docs/about-claude/pricing)
+
+## Platform Support
+
+Works on **macOS**, **Windows**, and **Linux**. Requires Node.js >= 18.
+
+Zero dependencies.
+
+## Background
+
+- [GitHub Issue #46829](https://github.com/anthropics/claude-code/issues/46829): Cache TTL regression analysis
+- [HN Discussion](https://news.ycombinator.com/item?id=47736476): Community reaction (168 points, 142 comments)
+- [HNPulse KR](https://www.youtube.com/@HNPulseKR): Hacker News tech deep-dives in Korean ([Shorts](https://www.youtube.com/@HNPulseKR/shorts))
+
+## Migration from claude-cache-monitor
+
+v2.0 renamed the package to reflect the expanded scope (spike diagnosis + 1M-context detection + remediation, not just cache monitoring). **No action required** in most cases:
+
+- `npm i claude-cache-monitor` still installs — the old package is deprecated and redirects here.
+- The binary `claude-cache-monitor` still works alongside the new `claude-token-saver` (both map to the same entry point).
+- Your existing `statusLine.command` setting in `~/.claude/settings.json` keeps working.
+
+If you want to update:
+
+```bash
+npm uninstall -g claude-cache-monitor
+npm i -g claude-token-saver
+
+# then in ~/.claude/settings.json, change:
+#   "command": "claude-cache-monitor --statusline --icon"
+# to:
+#   "command": "claude-token-saver --statusline --icon"
+```
+
+## License
+
+MIT
+

package/bin/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * claude-token-saver CLI (formerly claude-cache-monitor)
+ *
+ * Usage:
+ *   npx claude-token-saver                    # default report (last 30 days)
+ *   npx claude-token-saver --days 7           # last 7 days
+ *   npx claude-token-saver --format json      # JSON output
+ *   npx claude-token-saver --format csv       # CSV output
+ *   npx claude-token-saver --project myproj   # filter by project
+ *   npx claude-token-saver --install-hook     # install PostToolUse hook
+ *   npx claude-token-saver --uninstall-hook   # remove hook
+ *   npx claude-token-saver --hook-run         # internal: called by hook
+ *   npx claude-token-saver --statusline       # one-line output for Claude Code statusline API
+ *   npx claude-token-saver --statusline --verbose  # longer labels
+ *   npx claude-token-saver --statusline --no-color # strip ANSI colors
+ *   npx claude-token-saver --statusline --icon     # use 🧠 ⏳ 💰 icons
+ *   npx claude-token-saver --statusline --no-timer # hide the TTL countdown
+ *   npx claude-token-saver --statusline --exclude-session <path>
+ *                                               # exclude a JSONL path from lastActivity
+ *                                               # (or set CACHE_MONITOR_EXCLUDE_SESSION env var)
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
+import {
+  dailyTrend,
+  ttlBreakdown,
+  detectAnomalies,
+  summary,
+  detectSpikes,
+  detectContextWindow,
+  sessionMetrics,
+  diagnoseSession,
+} from '../src/stats.js';
+import { estimateCost } from '../src/cost.js';
+import { chipForIssues } from '../src/advice.js';
+
+const args = process.argv.slice(2);
+
+const PKG_VERSION = (() => {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || '';
+  } catch {
+    return '';
+  }
+})();
+
+function getArg(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+async function main() {
+  // Hook management
+  if (hasFlag('--install-hook')) {
+    const { installHook } = await import('../src/hook-manager.js');
+    const threshold = parseFloat(getArg('--threshold') || '0.7');
+    await installHook({ threshold });
+    return;
+  }
+
+  if (hasFlag('--uninstall-hook')) {
+    const { uninstallHook } = await import('../src/hook-manager.js');
+    await uninstallHook();
+    return;
+  }
+
+  // Hook internal execution
+  if (hasFlag('--hook-run')) {
+    await import('../src/hook.cjs');
+    return;
+  }
+
+  // Statusline mode shortcut
+  const isStatusline = hasFlag('--statusline') || getArg('--format') === 'statusline';
+
+  // Report generation
+  // Statusline default = 7 days (fast, called every ~300ms). Others = 30 days.
+  const defaultDays = isStatusline ? 7 : 30;
+  const days = parseInt(getArg('--days') || getArg('-d') || String(defaultDays), 10);
+  const format = isStatusline ? 'statusline' : (getArg('--format') || getArg('-f') || 'table');
+  const projectFilter = getArg('--project') || getArg('-p');
+
+  if (format === 'table') {
+    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.
+  const excludeSessionPath =
+    getArg('--exclude-session') || process.env.CACHE_MONITOR_EXCLUDE_SESSION || undefined;
+
+  const sessions = await parseAllSessions({ days, projectFilter, excludeSessionPath });
+
+  if (sessions.length === 0) {
+    // Statusline must always emit a single line (no multi-line help spam every 300ms)
+    if (format === 'statusline') {
+      const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR;
+      const gray = colorOk ? '\x1b[90m' : '';
+      const reset = colorOk ? '\x1b[0m' : '';
+      console.log(`${gray}🧠 no session data · ${days}d${reset}`);
+      return;
+    }
+    console.log('No session data found for the given period.');
+    console.log('');
+    console.log('This tool analyzes Claude Code session logs (~/.claude/projects/).');
+    console.log('');
+    console.log('Possible causes:');
+    console.log('  - You haven\'t used Claude Code in the last ' + days + ' days');
+    console.log('  - You\'re using the Claude API directly (SDK/curl) without Claude Code');
+    console.log('    → This tool requires Claude Code. API-only usage does not generate session logs.');
+    console.log('  - Try increasing the period: --days 90');
+    process.exit(1);
+  }
+
+  const trend = dailyTrend(sessions);
+  const ttl = ttlBreakdown(sessions);
+  const sum = summary(sessions);
+  const anomalies = detectAnomalies(trend);
+  const cost = estimateCost(sum, sessions[0]?.model);
+  const spikeReport = detectSpikes(sessions, { recentHours: 24, multiplier: 3 });
+  const contextWindow = detectContextWindow(sessions, { recentHours: 24 });
+
+  // For statusline: attach a single-word chip only when there's something
+  // actionable right now. 1M context is always shown; otherwise only fire
+  // if the most recent session actually appears in the spike list.
+  let spikeChip = null;
+  if (format === 'statusline') {
+    if (contextWindow.size === '1M') {
+      spikeChip = chipForIssues([], contextWindow);
+    } else {
+      const recentSession = sessions
+        .slice()
+        .sort((a, b) => (b.endTime?.getTime() || 0) - (a.endTime?.getTime() || 0))[0];
+      const recentIsSpiking = recentSession && spikeReport.spikes.some(
+        (sp) => sp.metrics.sessionId === recentSession.sessionId,
+      );
+      if (recentIsSpiking) {
+        const m = sessionMetrics(recentSession);
+        const issues = diagnoseSession(m, spikeReport.baseline);
+        spikeChip = chipForIssues(issues, contextWindow);
+      }
+    }
+  }
+
+  // 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).
+  const otherLastActivity = sessions
+    .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
+  // agent's tool calls would otherwise reset the countdown every few seconds
+  // as long as Claude Code is streaming a response.
+  let currentSessionLastUser = 0;
+  if (excludeSessionPath) {
+    try {
+      const t = await getLastUserMessageTime(excludeSessionPath);
+      if (t) currentSessionLastUser = t.getTime();
+    } catch {
+      // ignore — keep 0 so it doesn't raise the max
+    }
+  }
+  const lastActivity = Math.max(otherLastActivity, currentSessionLastUser);
+
+  const data = {
+    summary: sum,
+    trend,
+    ttl,
+    anomalies,
+    cost,
+    options: { days, version: PKG_VERSION },
+    lastActivity,
+    spikeReport,
+    contextWindow,
+    spikeChip,
+  };
+
+  let output;
+  if (format === 'json') {
+    const { formatReport } = await import('../src/formatters/json.js');
+    output = formatReport(data);
+  } else if (format === 'csv') {
+    const { formatReport } = await import('../src/formatters/csv.js');
+    output = formatReport(data);
+  } else if (format === 'statusline') {
+    const { formatReport } = await import('../src/formatters/statusline.js');
+    const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR;
+    const mode = hasFlag('--icon') ? 'icon' : 'text';
+    output = formatReport(data, {
+      color: colorOk,
+      verbose: hasFlag('--verbose'),
+      timer: !hasFlag('--no-timer'),
+      mode,
+    });
+  } else {
+    const { formatReport } = await import('../src/formatters/table.js');
+    output = formatReport(data);
+  }
+
+  console.log(output);
+}
+
+main().catch((err) => {
+  // Statusline mode must never spam multi-line errors (called every ~300ms)
+  const isStatusline = process.argv.includes('--statusline') || process.argv.includes('statusline');
+  if (isStatusline) {
+    const colorOk = !process.argv.includes('--no-color') && !process.env.NO_COLOR;
+    const red = colorOk ? '\x1b[31m' : '';
+    const reset = colorOk ? '\x1b[0m' : '';
+    console.log(`${red}🧠 error${reset}`);
+    process.exit(0);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/examples/statusline-command.ps1

@@ -0,0 +1,43 @@
+# Claude Code statusline (Windows PowerShell version)
+# Mirrors the POSIX sh script — prints "user@host:cwd" then appends
+# claude-token-saver output as a second segment.
+#
+# Install:
+#   1) npm install -g claude-token-saver
+#   2) Save this file as: %USERPROFILE%\.claude\statusline-command.ps1
+#   3) In %USERPROFILE%\.claude\settings.json add:
+#      {
+#        "statusLine": {
+#          "type": "command",
+#          "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File %USERPROFILE%\\.claude\\statusline-command.ps1",
+#          "refreshInterval": 1
+#        }
+#      }
+#
+# Requires Windows Terminal or PowerShell 7+ for ANSI color + emoji rendering.
+# (Classic conhost cmd renders colors but may garble emoji.)
+
+$stdin = [Console]::In.ReadToEnd()
+
+# Extract cwd from the JSON payload without requiring jq.
+$cwdMatch = [regex]::Match($stdin, '"cwd"\s*:\s*"([^"]*)"')
+$cwd = if ($cwdMatch.Success) { $cwdMatch.Groups[1].Value } else { (Get-Location).Path }
+
+# 1) user@host:cwd  (ANSI: green user@host, blue cwd)
+$esc = [char]27
+Write-Host -NoNewline "$esc[01;32m$env:USERNAME@$env:COMPUTERNAME$esc[00m`:$esc[01;34m$cwd$esc[00m"
+
+# 2) cache monitor (appended). Separator " | ". Falls back silently.
+Write-Host -NoNewline " $esc[90m|$esc[00m "
+
+$cacheMonitor = Get-Command claude-token-saver -ErrorAction SilentlyContinue
+if ($cacheMonitor) {
+  try {
+    & claude-token-saver --statusline --icon 2>$null
+  } catch { }
+} else {
+  # fallback: npx (first run downloads the package; subsequent runs are warm)
+  try {
+    & npx --yes claude-token-saver@latest --statusline --icon 2>$null
+  } catch { }
+}

package/examples/statusline-command.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+# Claude Code statusline (POSIX sh — works on macOS, Linux, and WSL)
+# Prints "user@host:cwd" then appends claude-token-saver as a second segment.
+#
+# Install:
+#   1) npm install -g claude-token-saver
+#   2) Save this file as: ~/.claude/statusline-command.sh
+#      chmod +x ~/.claude/statusline-command.sh  (optional)
+#   3) In ~/.claude/settings.json:
+#      {
+#        "statusLine": {
+#          "type": "command",
+#          "command": "bash ~/.claude/statusline-command.sh",
+#          "refreshInterval": 1
+#        }
+#      }
+#
+# refreshInterval keeps the TTL countdown ticking while you're idle.
+# Drop to 2 or 5 if you want lower local CPU.
+
+input=$(cat)
+
+# Extract cwd without jq dependency (jq may not be installed system-wide).
+cwd=$(echo "$input" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+cwd=${cwd:-$(pwd)}
+
+# 1) user@host:cwd
+printf '\033[01;32m%s@%s\033[00m:\033[01;34m%s\033[00m' "$(whoami)" "$(hostname -s)" "$cwd"
+
+# 2) cache monitor (appended). Separator " | ". Falls back silently.
+printf ' \033[90m|\033[00m '
+if command -v claude-token-saver >/dev/null 2>&1; then
+  claude-token-saver --statusline --icon 2>/dev/null || true
+else
+  npx --yes claude-token-saver@latest --statusline --icon 2>/dev/null || true
+fi