claude-token-saver 3.9.0 → 3.9.1

package/README.en.md

@@ -144,19 +144,21 @@ An auto `.bak` is kept, but **the session context that earned the rule its place
 
 ## 📦 compact-window — pin where a 1M session compacts
 
-Claude Code compacts when usage approaches `min(autoCompactWindow, model max context)`. On a 1M window, with that value unset, compaction only fires near 800k — and until then every request re-bills the whole context. Pinning 400k keeps twice a 200k session's headroom for the genuinely large pastes while cutting off the runaway tail.
+Claude Code compacts when usage approaches `min(autoCompactWindow, model max context)`. On a 1M window, with that value unset, compaction only fires near 800k — and until then every request re-bills the whole context. **1M is too large; the recommendation is a 400k–700k band** — 2–3.5x a 200k session's headroom for the genuinely large pastes, with the runaway tail cut off.
+
+**Anything inside the band is left alone.** 400k is the floor where the saving beats the extra compactions, and long sessions often want more room than that. Only an unset window, or one above 700k, is warned about (a smaller one is a deliberate, more aggressive choice).
 
 **200k sessions are never warned** — their window is already at or below 200k, so the setting cannot change anything.
 
 ```bash
 claude-token-saver compact-window                       # status (model, window, value, source)
-claude-token-saver compact-window set --global          # pin 400k in ~/.claude/settings.json
+claude-token-saver compact-window set --global          # pin 500k (mid-band) in ~/.claude/settings.json
 claude-token-saver compact-window set --project         # pin it in <root>/.claude/settings.json
-claude-token-saver compact-window set --global --value 250k   # explicit value (100k–1M)
+claude-token-saver compact-window set --global --value 600k   # explicit value (100k–1M)
 claude-token-saver compact-window off | on              # toggle the warning
 ```
 
-- On a 1M model with the value unset or above 400k, the statusline shows `🅷⚠ compact-window?` and the session briefing hands the model the exact registration command.
+- On a 1M model with the value unset or above 700k, the statusline shows `🅷⚠ compact-window?` and the session briefing hands the model the exact registration command.
 - Scope (`--global`/`--project`) is **required** for `set` — a global settings file is never edited on a guess.
 - Every other key in `settings.json` is preserved and a `.bak` is written first. Malformed JSON aborts the write untouched.
 - An exported `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats settings.json; `set` detects that and says so.
@@ -263,6 +265,9 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.9.1 (2026-08-01)
+- **compact-window now recommends a 400k–700k band instead of a single 400k** — 400k proved too tight in practice and compacted too often. The advice is a range now, and **a window inside it (or below it) is never warned about**; only an unset value or one above 700k raises `🅷⚠ compact-window?` and the briefing. `set` defaults to 500k (mid-band); pick your own with `--value 600k`.
+
 ### v3.9.0 (2026-08-01)
 
 Compared this tool's design against manifest.build's "Everyone is building LLM routers, we deprecated ours" (a retrospective on 4 months across 7,000 users) and closed the four of their failure modes that were not already ruled out here. Full comparison in [TIER_CRITERIA.md §3.9](./docs/TIER_CRITERIA.md).

package/README.md

@@ -125,15 +125,17 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 
 ## 📦 compact-window — 1M 컨텍스트의 자동 압축 지점 고정
 
-Claude Code는 `min(autoCompactWindow, 모델 최대 창)`에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. 40만으로 고정하면 큰 붙여넣기용 여유는 200k 세션의 두 배로 남기면서 꼬리만 잘라냅니다.
+Claude Code는 `min(autoCompactWindow, 모델 최대 창)`에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. **1M은 너무 크니 40만~70만 범위를 권장합니다** — 큰 붙여넣기용 여유는 200k 세션의 2~3.5배로 남기면서 꼬리만 잘라냅니다.
+
+**권장 범위 안이면 경고하지 않습니다.** 40만은 절감이 압축 횟수를 이기는 하한이고, 긴 세션은 그보다 여유가 더 필요한 경우가 많습니다. 미설정이거나 70만을 넘을 때만 알립니다(그보다 낮게 잡은 건 더 공격적으로 아끼겠다는 선택이라 그냥 둡니다).
 
 **200k 컨텍스트는 경고 대상이 아닙니다** — 창이 이미 200k 이하라 이 설정이 바꿀 게 없습니다.
 
 ```bash
 claude-token-saver compact-window                       # 현재 상태 (모델·창·설정값·출처)
-claude-token-saver compact-window set --global          # ~/.claude/settings.json 에 40만 고정
+claude-token-saver compact-window set --global          # ~/.claude/settings.json 에 50만 고정 (범위 중간)
 claude-token-saver compact-window set --project         # <root>/.claude/settings.json 에 고정
-claude-token-saver compact-window set --global --value 250k   # 값 직접 지정 (10만~1M)
+claude-token-saver compact-window set --global --value 600k    # 값 직접 지정 (10만~1M)
 claude-token-saver compact-window off | on              # 경고 표시 토글
 ```
 
@@ -220,6 +222,9 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.9.1 (2026-08-01)
+- **compact-window 권장값이 단일 40만에서 40만~70만 범위로** — 40만은 실사용에서 너무 빡빡해 압축이 잦았습니다. 이제 범위를 제안하고, **그 안(또는 그보다 낮게) 잡아둔 세션은 경고하지 않습니다.** 미설정이거나 70만 초과일 때만 `🅷⚠ compact-window?`와 브리핑이 뜹니다. `set`의 기본값도 범위 중간인 50만으로 올렸고, 원하는 값은 `--value 600k`로 지정합니다.
+
 ### v3.9.0 (2026-08-01)
 
 manifest.build의 "다들 LLM 라우터 만드는데 우리는 폐기했다"(7천 사용자·4개월 실사용 회고)와 이 도구의 설계를 대조해, 그쪽 실패 요인 중 아직 안 막혀 있던 것 4개를 메웠습니다. 자세한 대조는 [TIER_CRITERIA.md §3.9](./docs/TIER_CRITERIA.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.9.0",
+  "version": "3.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/brief.js

@@ -246,7 +246,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
         briefed.add(sig);
         s.briefed = [...briefed];
         const now = st.window ? `현재 ${fmtK(st.window)}` : '현재 미설정';
-        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project (적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
       }
     }
   } catch { /* settings unreadable — other briefings above still apply */ }

package/src/commands/compact-window.js

@@ -1,9 +1,9 @@
 /**
  * Subcommand: compact-window — audit / pin Claude Code's `autoCompactWindow`.
  *   claude-token-saver compact-window                      # status
- *   claude-token-saver compact-window set --global         # pin 400k in ~/.claude/settings.json
- *   claude-token-saver compact-window set --project        # pin 400k in <root>/.claude/settings.json
- *   claude-token-saver compact-window set --global --value 250k
+ *   claude-token-saver compact-window set --global         # pin 500k in ~/.claude/settings.json
+ *   claude-token-saver compact-window set --project        # pin 500k in <root>/.claude/settings.json
+ *   claude-token-saver compact-window set --global --value 600k
  *   claude-token-saver compact-window off | on             # toggle the statusline warning
  *
  * Scope is deliberately explicit for `set`: writing a global settings.json is
@@ -69,22 +69,25 @@ export async function run({ args, hasFlag }) {
       return;
     }
     if (s.ok) {
-      console.log(ko ? '\n✅ 압축 창이 400k 이하로 고정돼 있습니다.' : '\n✅ Compaction window is pinned at or below 400k.');
+      console.log(ko
+        ? `\n✅ 압축 창이 권장 범위(${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)}) 상한 이하입니다.`
+        : `\n✅ Compaction window is at or below the top of the recommended ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} band.`);
       return;
     }
     console.log(ko
       ? `\n⚠ 1M 컨텍스트인데 autoCompactWindow가 ${s.reason === 'unset' ? '설정되지 않았습니다' : `${fmt(s.window)}로 너무 큽니다`} — 자동 압축이 80만 토큰 근처에서야 걸립니다.`
       : `\n⚠ 1M context with autoCompactWindow ${s.reason === 'unset' ? 'unset' : `at ${fmt(s.window)}`} — compaction only fires near 800k.`);
     console.log(ko
-      ? '  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 유지하면서 압축 시점만 앞당깁니다.'
-      : '  Until then every request re-bills the whole context. Pinning 400k keeps the 1M window while capping the runaway tail.');
-    console.log('\n  claude-token-saver compact-window set --global     (~/.claude/settings.json)');
-    console.log('  claude-token-saver compact-window set --project    (<root>/.claude/settings.json)');
+      ? `  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)} 범위를 권장합니다 (기본값 ${fmt(s.recommended)}, --value로 조절). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다.`
+      : `  Until then every request re-bills the whole context. 1M is too large — pick something in ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} (default ${fmt(s.recommended)}, override with --value). The 1M window itself stays.`);
+    console.log(`\n  claude-token-saver compact-window set --global     (~/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --project    (<root>/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --global --value ${fmt(s.recommendedMax)}`);
     console.log(ko ? '  (적용 범위는 사용자에게 먼저 확인할 것)' : '  (confirm the scope with the user first)');
     return;
   }
 
   console.error(`Unknown compact-window subcommand: ${sub}`);
-  console.error('Usage: claude-token-saver compact-window [status|set --global|--project [--value 400k]|off|on]');
+  console.error('Usage: claude-token-saver compact-window [status|set --global|--project [--value 500k]|off|on]');
   process.exit(1);
 }

package/src/compact-window.js

@@ -5,8 +5,13 @@
  * `min(settings.autoCompactWindow, model max context)`. On a 1M window the
  * default lets a session grow past 800k before compaction ever fires, so every
  * later request re-bills a context most sessions never needed. Pinning
- * `autoCompactWindow: 400000` keeps twice the headroom of a 200k session for
- * the genuinely large ones while capping the runaway tail.
+ * `autoCompactWindow` somewhere in 400k–700k keeps 2–3.5x the headroom of a
+ * 200k session for the genuinely large ones while capping the runaway tail.
+ *
+ * The recommendation is a range, not a number: 400k is the floor where the
+ * saving is worth the extra compactions, and in practice long sessions often
+ * want more room than that. Anything at or below 700k is left alone — only an
+ * unset window, or one above 700k, is a real config defect.
  *
  * 200k sessions are exempt by design: their window is already <= 200k, so the
  * setting changes nothing and a warning would be pure noise.
@@ -28,7 +33,13 @@ import { debug } from './debug.js';
 // the app would honor.
 export const MIN_WINDOW = 100_000;
 export const MAX_WINDOW = 1_000_000;
-export const RECOMMENDED_WINDOW = 400_000;
+// Recommended band. Warn only outside it on the high side (or when unset) —
+// a window below RECOMMENDED_MIN is a deliberate, more aggressive choice and
+// costs nothing, so it stays silent.
+export const RECOMMENDED_MIN = 400_000;
+export const RECOMMENDED_MAX = 700_000;
+// What `compact-window set` writes when no --value is given: middle of the band.
+export const RECOMMENDED_WINDOW = 500_000;
 
 // A model id whose context is the 1M variant. Claude Code spells it as a
 // suffix on the model id (`claude-opus-5[1m]`); the beta header form
@@ -116,10 +127,10 @@ export function effectiveWindow(root) {
 /**
  * Full audit result. `ok` is true when there is nothing to warn about — either
  * the session is not on a 1M model (exempt), or the window is already pinned at
- * or below the recommended 400k.
+ * or below the top of the recommended band (700k).
  *
  * `reason` names why it is not ok: 'unset' (no autoCompactWindow anywhere) or
- * 'too-large' (set, but above 400k — still lets context run away).
+ * 'too-large' (set, but above 700k — still lets context run away).
  */
 export function compactWindowStatus({ root = process.cwd() } = {}) {
   const { model, source: modelSource } = resolveModelId(root);
@@ -133,10 +144,12 @@ export function compactWindowStatus({ root = process.cwd() } = {}) {
     windowSource: win.source,
     windowPath: win.path || null,
     recommended: RECOMMENDED_WINDOW,
+    recommendedMin: RECOMMENDED_MIN,
+    recommendedMax: RECOMMENDED_MAX,
   };
   if (!is1m) return { ...base, ok: true, reason: 'not-1m' };
   if (win.value === null) return { ...base, ok: false, reason: 'unset' };
-  if (win.value > RECOMMENDED_WINDOW) return { ...base, ok: false, reason: 'too-large' };
+  if (win.value > RECOMMENDED_MAX) return { ...base, ok: false, reason: 'too-large' };
   return { ...base, ok: true, reason: 'configured' };
 }