claude-token-saver 2.9.0 → 2.9.1

package/README.en.md

@@ -33,17 +33,21 @@ claude-token-saver install
 After install, Claude Code's bottom statusline updates every 5 seconds with cache state (postinstall registers it in `~/.claude/settings.json` automatically).
 
 ```
-🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 59:51 · 📦 Ctx 200k · 💰 Cache saved $221 · last 1d
+🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
 ```
 
-Risk chips lead when something's wrong:
+Segments — `🤖 model` · `🧠 cache hit rate` · `⏳ TTL countdown` · `✦ current` (5-hour window) · `📅 weekly` (7-day window) · `📦 context` · `💰 cumulative savings` · `last <window>`.
+
+When excessive token usage is detected, a warning chip is prepended at the front of the statusline:
 
 ```
-🚨 5H 94% (resets in 12m) · 🤖 Opus 4.7 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📦 Ctx 200k · last 1d
+🚨 5H 94% (resets in 12m) · 🤖 Opus 4.7 · 🧠 Cache hit 72.1% · ⚠ Cache miss · ✦ current ██████ 94% · 📦 Ctx 200k · last 1d
 ```
 
 Risk chips: `🚨 5H/7D NN%`, `⚠ 1M ON`, `⚠ Input spike`, `⚠ Cache miss`, `⚠ 5m TTL`, `⚠ Rebuild churn`, `⚠ Output heavy`, `⚠ Call surge`.
 
+**What to do** — run the `/claude-token-saver` Skill in Claude. It calls `claude-token-saver last` and surfaces the root cause + step-by-step fix. Saying the chip wording out loud (e.g. "5H cap is up", "cache miss") also auto-activates the same Skill. See the [Skill workflow](#when-a-warning-chip-appears--skill-workflow) section below for the full flow.
+
 If postinstall was skipped (you already use a different statusline, etc.), wire it manually:
 
 ```json
@@ -58,9 +62,16 @@ If postinstall was skipped (you already use a different statusline, etc.), wire
 
 `refreshInterval: 5` keeps the TTL countdown ticking while idle. For Windows PowerShell see `examples/statusline-command.ps1`.
 
-## Skill — mention a chip, it activates
+## When a warning chip appears — Skill workflow
+
+The Claude Code Skill registered at install time bridges "warning chip → remediation":
 
-The Claude Code Skill registered at install time auto-activates whenever you mention chip wording in chat ("cache hit rate", "1M context", "5H cap"). It runs `claude-token-saver last` to surface the most recent warning + remediation, then points you at `history` / `handoff` for follow-up. (v2.6.0 folded the legacy `/token-monitor` slash command into this Skill — older installs are cleaned up automatically the next time you run `claude-token-saver install`.)
+1. **A risk chip appears in the statusline** — e.g. `🚨 5H 94%`, `⚠ Cache miss`, `⚠ 1M ON`.
+2. **Run `/claude-token-saver`** — invoking the Skill via slash is the simplest path. Mentioning the chip wording to Claude ("5H cap is up", "cache miss showing", "why is 1M context on?") auto-activates the same Skill.
+3. **The Skill fetches the remediation.** Internally it runs `claude-token-saver last` to surface the most recent warning + root-cause code + step-by-step fix, and recommends `claude-token-saver handoff` when a cap is imminent.
+4. **Run manually any time.** `claude-token-saver last` (latest event), `claude-token-saver history` (last 7 days of transitions), `claude-token-saver handoff` (back up before a cap blocks you) — same information, on demand.
+
+> v2.6.0 folded the legacy `/token-monitor` slash command into this Skill. On older installs, run `claude-token-saver install` once and the legacy file is cleaned up automatically.
 
 ## One-shot report
 
@@ -90,6 +101,8 @@ claude-token-saver mode       # show current settings
 
 ## Commands
 
+All of the commands below run in your **shell (terminal)**. Inside a Claude Code session, the only entry point is the `/claude-token-saver` Skill, which calls these commands for you. The `--statusline` form is invoked automatically by Claude Code on each statusline refresh — you never type it yourself.
+
 | Command | What it does |
 |---|---|
 | `claude-token-saver` | Last-1-day diagnostic report (`--days N` to change window) |
@@ -178,6 +191,11 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## Release notes
 
+### v2.9.1 (2026-04-27)
+- Fix the README statusline sample so it matches actual output (includes the `✦ current` / `📅 weekly` window segments that were missing).
+- Add a 4-step "When a warning chip appears" Skill workflow — spot the chip → mention its wording to Claude → Skill runs `last` → apply remediation.
+- Move `language` from `cfg.statusline.language` to top-level `cfg.language` (it doesn't belong with statusline toggles). The legacy location is still read as a fallback so existing configs migrate transparently. `mode` output also splits the statusline section from the output-language section.
+
 ### v2.9.0 (2026-04-27)
 - **Output language is now configurable.** `last` / `history` / advice render in a single language at a time. English by default; switch with `claude-token-saver mode ko`. Statusline chips remain symbolic.
 - History files stay bilingual on disk; the language toggle is applied at display time.

package/README.md

@@ -33,16 +33,20 @@ claude-token-saver install
 설치 후 Claude Code 하단 statusline에 캐시 상태가 5초마다 갱신됩니다 (postinstall이 `~/.claude/settings.json`에 자동 등록).
 
 ```
-🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 59:51 · 📦 Ctx 200k · 💰 Cache saved $221 · last 1d
+🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
 ```
 
-위험 상황에서는 경고 칩이 맨 앞으로 나옵니다.
+세그먼트 — `🤖 모델` · `🧠 캐시 히트율` · `⏳ TTL 카운트다운` · `✦ current` (5시간 윈도) · `📅 weekly` (7일 윈도) · `📦 컨텍스트` · `💰 누적 절감액` · `last <기간>`.
+
+토큰이 과도하게 사용되는 상황이 감지되면 경고 칩이 맨 앞에 노출됩니다.
 
 ```
-🚨 5H 94% (resets in 12m) · 🤖 Opus 4.7 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📦 Ctx 200k · last 1d
+🚨 5H 94% (resets in 12m) · 🤖 Opus 4.7 · 🧠 Cache hit 72.1% · ⚠ Cache miss · ✦ current ██████ 94% · 📦 Ctx 200k · last 1d
 ```
 
-표시되는 경고 칩 — `🚨 5H/7D NN%`, `⚠ 1M ON`, `⚠ Input spike`, `⚠ Cache miss`, `⚠ 5m TTL`, `⚠ Rebuild churn`, `⚠ Output heavy`, `⚠ Call surge`.
+경고 칩 종류 — `🚨 5H/7D NN%`, `⚠ 1M ON`, `⚠ Input spike`, `⚠ Cache miss`, `⚠ 5m TTL`, `⚠ Rebuild churn`, `⚠ Output heavy`, `⚠ Call surge`.
+
+**해야 할 일** — Claude에서 `/claude-token-saver` Skill을 실행하면 됩니다. Skill이 `claude-token-saver last`를 호출해 원인 코드와 단계별 해결 명령을 자동으로 보여줍니다. 칩 문구(예: "5H cap 떴어", "cache miss")만 말해도 동일한 Skill이 자동 활성화됩니다. 자세한 흐름은 아래 [Skill 워크플로](#경고-칩이-떴을-때--skill-워크플로) 참고.
 
 수동 등록이 필요한 경우(다른 statusline을 이미 쓰고 있어 postinstall이 건너뛴 경우 등):
 
@@ -58,9 +62,16 @@ claude-token-saver install
 
 `refreshInterval: 5`는 idle 상태에서도 TTL 카운트다운을 5초마다 갱신합니다. Windows(PowerShell)는 `examples/statusline-command.ps1` 참고.
 
-## Skill — 칩을 언급하면 자동 활성화
+## 경고 칩이 떴을 때 — Skill 워크플로
+
+설치 시 함께 등록되는 Claude Code Skill이 "경고 칩 → 처방"의 다리 역할을 합니다.
 
-설치 시 함께 등록되는 Claude Code Skill 덕분에 대화 중 "cache hit rate", "1M context", "5H cap" 같은 칩 단어를 언급하면 Claude가 자동으로 `claude-token-saver last`를 실행해 가장 최근 경고와 처방을 보여주고, 필요 시 `history` / `handoff`로 후속 조치를 안내합니다. (v2.6.0에서 레거시 `/token-monitor` 슬래시 커맨드는 Skill로 흡수됐습니다 — 이전 버전 사용자는 `claude-token-saver install`을 한 번 다시 실행하면 자동 정리됩니다.)
+1. **statusline에 경고 칩이 뜬다** — 예: `🚨 5H 94%`, `⚠ Cache miss`, `⚠ 1M ON`.
+2. **`/claude-token-saver` Skill을 실행한다** — Claude에서 슬래시로 Skill을 직접 호출하는 게 가장 간단합니다. 또는 칩 문구를 그대로 말해도 동일한 Skill이 자동 활성화됩니다 ("5H cap 떴어", "cache miss 떴어", "1M context 왜 켜졌지?" 등 — 칩 텍스트가 트리거 단어로 등록돼 있음).
+3. **Skill이 처방을 가져온다** — 내부적으로 `claude-token-saver last`를 실행해 가장 최근 경고 + 원인 코드 + 단계별 해결 명령을 한 번에 보여주고, 캡 임박 시에는 `claude-token-saver handoff`로 현재 작업 백업을 권합니다.
+4. **수동 확인이 필요하면** — `claude-token-saver last` (최근 1건), `claude-token-saver history` (최근 7일 전이 로그), `claude-token-saver handoff` (cap 직전 백업)를 직접 실행해도 같은 정보를 얻을 수 있습니다.
+
+> v2.6.0에서 레거시 `/token-monitor` 슬래시 커맨드는 이 Skill로 흡수됐습니다. 이전 버전 사용자는 `claude-token-saver install`을 한 번 더 실행하면 자동 정리됩니다.
 
 ## 단발 리포트
 
@@ -90,6 +101,8 @@ claude-token-saver mode       # 현재 설정 확인
 
 ## 주요 명령
 
+아래 명령은 모두 **셸(터미널)에서 직접 실행**합니다. Claude Code 세션 안에서는 `/claude-token-saver` Skill 하나만 쓰며, Skill이 내부적으로 이 명령들을 호출합니다. `--statusline` 형식은 Claude Code가 statusline 갱신마다 자동으로 호출하므로 사용자가 직접 입력하지 않습니다.
+
 | 명령 | 설명 |
 |---|---|
 | `claude-token-saver` | 최근 1일 진단 리포트 (`--days N`로 기간 변경) |
@@ -138,6 +151,11 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.9.1 (2026-04-27)
+- README의 statusline 예시를 실제 출력(`✦ current` / `📅 weekly` 윈도 세그먼트 포함)으로 정정.
+- "경고 칩이 떴을 때" Skill 워크플로 4단계 가이드 추가 — 칩 발견 → Claude에게 칩 문구 그대로 말하기 → Skill이 `last` 실행 → 처방 적용.
+- `language` 설정 위치를 `cfg.statusline` 하위에서 top-level `cfg.language`로 이동(statusline 토글이 아니므로). 구버전 위치도 fallback으로 계속 읽어 마이그레이션은 자동. `mode` 출력도 statusline / output language를 분리해서 표시.
+
 ### v2.9.0 (2026-04-27)
 - **출력 언어 전환 추가** — `last` / `history` / 처방 메시지가 한 번에 한 언어만 출력합니다. 기본은 영어, `claude-token-saver mode ko`로 한국어 전환 (statusline 칩은 영향 없음).
 - 기존 history 파일은 이중언어로 보관되며, 표시할 때 선택한 언어만 필터링됩니다.

package/bin/cli.js

@@ -396,21 +396,23 @@ async function main() {
   //   claude-token-saver mode icon verbose       # set icon + verbose
   //   claude-token-saver mode reset              # clear back to defaults
   if (args[0] === 'mode') {
-    const { applyMode, loadConfig, configPath, statuslineDefaults, VALID_KEYWORDS } =
+    const { applyMode, loadConfig, configPath, statuslineDefaults, userLanguage, VALID_KEYWORDS } =
       await import('../src/config.js');
     const words = args.slice(1);
     if (words.length === 0) {
       const eff = statuslineDefaults();
-      const raw = loadConfig().statusline || {};
-      console.log('Statusline mode (effective):');
-      console.log(`  icon:     ${eff.icon}`);
-      console.log(`  verbose:  ${eff.verbose}`);
-      console.log(`  timer:    ${eff.timer}`);
-      console.log(`  color:    ${eff.color}`);
-      console.log(`  language: ${eff.language}  (advice / history / last)`);
-      console.log(`  window:   ${eff.windowLabel} (${eff.windowHours}h)`);
+      const raw = loadConfig();
+      console.log('Statusline (effective):');
+      console.log(`  icon:    ${eff.icon}`);
+      console.log(`  verbose: ${eff.verbose}`);
+      console.log(`  timer:   ${eff.timer}`);
+      console.log(`  color:   ${eff.color}`);
+      console.log(`  window:  ${eff.windowLabel} (${eff.windowHours}h)`);
       console.log('');
-      console.log(`Stored config (${configPath()}):`);
+      console.log('Output language (advice / history / last):');
+      console.log(`  language: ${userLanguage()}`);
+      console.log('');
+      console.log(`Stored config file (${configPath()}):`);
       console.log(`  ${Object.keys(raw).length === 0 ? '(none — using defaults)' : JSON.stringify(raw)}`);
       console.log('');
       console.log('Change with: claude-token-saver mode <keywords...>');
@@ -425,7 +427,7 @@ async function main() {
     }
     const eff = statuslineDefaults();
     console.log(`Updated: ${applied.join(', ')}`);
-    console.log(`Now: icon=${eff.icon} verbose=${eff.verbose} timer=${eff.timer} color=${eff.color} language=${eff.language} window=${eff.windowLabel}`);
+    console.log(`Now: icon=${eff.icon} verbose=${eff.verbose} timer=${eff.timer} color=${eff.color} window=${eff.windowLabel} language=${userLanguage()}`);
     console.log('Statusline picks up the change on the next refresh (~1s).');
     return;
   }

package/package.json

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

package/src/config.js

@@ -36,6 +36,7 @@ export function saveConfig(cfg) {
 
 // Each keyword maps to a single statusline option toggle.
 // Orthogonal — `mode icon verbose` flips both without resetting the rest.
+// Statusline-only toggles. Stored under `cfg.statusline`.
 const KEYWORDS = {
   icon:       { key: 'icon',    value: true  },
   text:       { key: 'icon',    value: false },
@@ -45,12 +46,16 @@ const KEYWORDS = {
   'no-timer': { key: 'timer',   value: false },
   color:      { key: 'color',   value: true  },
   'no-color': { key: 'color',   value: false },
-  // Language for advice / history / `last` output. Default is `en`.
-  // Statusline chips themselves stay symbolic (e.g. `🚨 5H 94%`) regardless.
-  en:         { key: 'language', value: 'en' },
-  english:    { key: 'language', value: 'en' },
-  ko:         { key: 'language', value: 'ko' },
-  korean:     { key: 'language', value: 'ko' },
+};
+
+// Output language for `last`/`history`/advice. Stored at top level
+// (`cfg.language`) because it has nothing to do with statusline rendering —
+// the chips themselves stay symbolic regardless.
+const LANG_KEYWORDS = {
+  en:      'en',
+  english: 'en',
+  ko:      'ko',
+  korean:  'ko',
 };
 
 // Window preset accepts forms like:
@@ -71,13 +76,15 @@ function parseWindow(word) {
   return null;
 }
 
-export const VALID_KEYWORDS = Object.keys(KEYWORDS).concat([
-  '<N>h (e.g. 1h, 6h, 24h)',
-  '<N>d (e.g. 1d, 7d, 30d)',
-  'lang=en | lang=ko',
-  'reset',
-  'default',
-]);
+export const VALID_KEYWORDS = Object.keys(KEYWORDS)
+  .concat(Object.keys(LANG_KEYWORDS))
+  .concat([
+    '<N>h (e.g. 1h, 6h, 24h)',
+    '<N>d (e.g. 1d, 7d, 30d)',
+    'lang=en | lang=ko',
+    'reset',
+    'default',
+  ]);
 
 /**
  * Apply user-supplied mode keywords to the persisted config.
@@ -94,16 +101,25 @@ export function applyMode(words) {
     const lower = String(w).toLowerCase();
     if (lower === 'reset' || lower === 'default') {
       cfg.statusline = {};
+      delete cfg.language;
       applied.push(lower);
       continue;
     }
     const langMatch = lower.match(/^lang(?:uage)?=(en|english|ko|korean)$/);
     if (langMatch) {
       const v = langMatch[1].startsWith('k') ? 'ko' : 'en';
-      cfg.statusline.language = v;
+      cfg.language = v;
+      // Migrate any legacy value that lived under cfg.statusline.language.
+      if (cfg.statusline) delete cfg.statusline.language;
       applied.push(`lang=${v}`);
       continue;
     }
+    if (LANG_KEYWORDS[lower]) {
+      cfg.language = LANG_KEYWORDS[lower];
+      if (cfg.statusline) delete cfg.statusline.language;
+      applied.push(`lang=${cfg.language}`);
+      continue;
+    }
     const hours = parseWindow(lower);
     if (hours !== null && hours > 0) {
       cfg.statusline.windowHours = hours;
@@ -150,7 +166,6 @@ export function statuslineDefaults() {
     verbose:     s.verbose !== false,
     timer:       s.timer   !== false,
     color:       s.color   !== false,
-    language:    s.language === 'ko' ? 'ko' : 'en',
     windowHours,
     windowLabel: formatWindow(windowHours),
   };
@@ -158,9 +173,13 @@ export function statuslineDefaults() {
 
 // Resolve the user's preferred output language for advice/history/last.
 // Returns 'en' or 'ko'; defaults to 'en' for first-time users.
+// Reads `cfg.language` (current location) with a fallback to the legacy
+// `cfg.statusline.language` slot so configs from earlier 2.9.x installs
+// keep working.
 export function userLanguage() {
-  const s = loadConfig().statusline || {};
-  return s.language === 'ko' ? 'ko' : 'en';
+  const cfg = loadConfig();
+  const v = cfg.language || (cfg.statusline && cfg.statusline.language);
+  return v === 'ko' ? 'ko' : 'en';
 }
 
 /**