claude-code-cache-fix 1.8.0 → 1.9.1

package/README.md

@@ -1,6 +1,6 @@
 # claude-code-cache-fix
 
-English | [中文](./README.zh.md)
+English | [中文](./README.zh.md) | [Português](./docs/guia-pt-br.md)
 
 Fixes prompt cache regressions in [Claude Code](https://github.com/anthropics/claude-code) that cause **up to 20x cost increase** on resumed sessions, plus monitoring for silent context degradation. Confirmed through v2.1.97.
 
@@ -36,7 +36,10 @@ Create a wrapper script (e.g. `~/bin/claude-fixed`):
 
 ```bash
 #!/bin/bash
-CLAUDE_NPM_CLI="$HOME/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js"
+NPM_GLOBAL_ROOT="$(npm root -g 2>/dev/null)"
+
+CLAUDE_NPM_CLI="$NPM_GLOBAL_ROOT/@anthropic-ai/claude-code/cli.js"
+CACHE_FIX="$NPM_GLOBAL_ROOT/claude-code-cache-fix/preload.mjs"
 
 if [ ! -f "$CLAUDE_NPM_CLI" ]; then
   echo "Error: Claude Code npm package not found at $CLAUDE_NPM_CLI" >&2
@@ -44,7 +47,13 @@ if [ ! -f "$CLAUDE_NPM_CLI" ]; then
   exit 1
 fi
 
-exec env NODE_OPTIONS="--import claude-code-cache-fix" node "$CLAUDE_NPM_CLI" "$@"
+if [ ! -f "$CACHE_FIX" ]; then
+  echo "Error: claude-code-cache-fix not found at $CACHE_FIX" >&2
+  echo "Install with: npm install -g claude-code-cache-fix" >&2
+  exit 1
+fi
+
+exec env NODE_OPTIONS="--import $CACHE_FIX" node "$CLAUDE_NPM_CLI" "$@"
 ```
 
 ```bash
@@ -95,6 +104,30 @@ The wrapper dynamically resolves your npm global root, constructs a `file:///` U
 
 Credit: [@TomTheMenace](https://github.com/anthropics/claude-code/issues/38335) contributed the Windows wrapper and validated the interceptor across a 7.5-hour, 536-call Opus 4.6 session on Windows — 98.4% cache hit rate, 81% of calls had fingerprint instability that the interceptor corrected.
 
+## VS Code Extension (experimental)
+
+If you use Claude Code through the VS Code extension rather than the CLI, you may be able to load the interceptor via VS Code settings:
+
+```json
+{
+  "claude-code.environmentVariables": {
+    "NODE_OPTIONS": "--import /path/to/claude-code-cache-fix/preload.mjs"
+  }
+}
+```
+
+Replace `/path/to` with your npm global root (`npm root -g`). Example for a typical Linux setup:
+
+```json
+{
+  "claude-code.environmentVariables": {
+    "NODE_OPTIONS": "--import /home/username/.npm-global/lib/node_modules/claude-code-cache-fix/preload.mjs"
+  }
+}
+```
+
+**Status: needs community testing.** We've confirmed the `claude-code.environmentVariables` setting exists but haven't verified it propagates `NODE_OPTIONS` to the CC subprocess. If you test this, please report back on [#16](https://github.com/cnighswonger/claude-code-cache-fix/issues/16).
+
 ## How it works
 
 The module intercepts `globalThis.fetch` before Claude Code makes API calls to `/v1/messages`. On each call it:
@@ -198,7 +231,23 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-### Why this matters
+### Recommended: disable git-status injection
+
+Claude Code injects live `git status` output into the system prompt on every call. Any file edit changes the git status, which changes the system prompt, which busts the entire prefix cache. Disabling this saves ~1,800 tokens per call and fully stabilizes the system prompt across file edits:
+
+```bash
+export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1
+```
+
+Or add `"includeGitInstructions": false` to `~/.claude/settings.json`. Claude Code can still run `git status` via the Bash tool when it needs git context — it just won't pre-inject it into every system prompt.
+
+The flag also shrinks the Bash tool description by ~6,364 chars (the Bash tool includes git-related instructions that are stripped when the flag is set), for a total prefix savings of ~7,180 chars (~1,800 tokens) per call.
+
+Community-validated by [@wadabum](https://github.com/cnighswonger/claude-code-cache-fix/issues/11): 18-token cache creation across git state changes (vs thousands without the flag). See [#11](https://github.com/cnighswonger/claude-code-cache-fix/issues/11) for the full telemetry comparison.
+
+**Note:** this flag does not address the `"Primary working directory"` line in the system prompt, which changes per git worktree. A v1.9.0 interceptor fix to strip/normalize both is planned ([#11](https://github.com/cnighswonger/claude-code-cache-fix/issues/11)).
+
+### Why the status line matters
 
 When the server downgrades your TTL to 5m (Layer 2 — quota-aware downgrade at Q5h ≥ 100%), **every idle longer than 5 minutes causes a full context rebuild**. Without the status line, this is invisible — you just notice things getting slower and more expensive. With the status line, the red `TTL:5m` warning tells you immediately: **stop working, wait for the Q5h window to reset, then resume**. Powering through overage compounds the drain; pausing breaks the cycle.
 
@@ -406,8 +455,13 @@ Snapshots are saved to `~/.claude/cache-fix-snapshots/` and diff reports are gen
 | `CACHE_FIX_SKIP_RELOCATE` | `0` | Skip block relocation fix (Bug 1) |
 | `CACHE_FIX_SKIP_FINGERPRINT` | `0` | Skip fingerprint stabilization (Bug 2b) |
 | `CACHE_FIX_SKIP_TOOL_SORT` | `0` | Skip tool ordering stabilization (Bug 2a) |
-| `CACHE_FIX_SKIP_TTL` | `0` | Skip 1h TTL injection (Bug 5) |
+| `CACHE_FIX_SKIP_TTL` | `0` | Skip TTL injection (Bug 5) |
 | `CACHE_FIX_SKIP_IDENTITY` | `0` | Skip identity normalization (Bug 6) |
+| `CACHE_FIX_SKIP_GIT_STATUS` | `0` | Skip git-status stripping |
+| `CACHE_FIX_STRIP_GIT_STATUS` | `0` | Strip volatile git-status from system prompt for prefix stability. Model can still run `git status` via Bash. |
+| `CACHE_FIX_TTL_MAIN` | `1h` | TTL for main-thread requests: `1h`, `5m`, or `none` (pass-through) |
+| `CACHE_FIX_TTL_SUBAGENT` | `1h` | TTL for subagent requests: `1h`, `5m`, or `none` (pass-through) |
+| `CACHE_FIX_DUMP_BREAKPOINTS` | unset | Path to dump cache breakpoint structure (diagnostic for #12) |
 
 ## Limitations
 
@@ -491,6 +545,8 @@ measurable signature of cache-efficiency degradation.
 - **[@Renvect](https://github.com/Renvect)** — Image duplication discovery, cross-project directory contamination analysis
 - **[@fgrosswig](https://github.com/fgrosswig)** — [claude-usage-dashboard](https://github.com/fgrosswig/claude-usage-dashboard) forensic methodology: cost-factor overhead ratio metric, `anthropic-*` header capture pattern, proxy NDJSON schema that informed our dashboard interop layer
 - **[@TomTheMenace](https://github.com/TomTheMenace)** — Windows `.bat` wrapper for the interceptor, first Windows platform validation (7.5h/536-call Opus 4.6 session, 98.4% cache hit rate, 81% fingerprint instability corrected)
+- **[@arjansingh](https://github.com/arjansingh)** — nvm-compatible wrapper script with dynamic `npm root -g` path resolution (PR #15)
+- **[@beekamai](https://github.com/beekamai)** — Windows URL-encoding fix for `claude-fixed.bat` when npm root contains spaces (PR #17)
 
 If you contributed to the community effort on these issues and aren't listed here, please open an issue or PR — we want to credit everyone properly.
 

package/claude-fixed.bat

@@ -17,6 +17,10 @@ REM
 REM Credit: @TomTheMenace (https://github.com/anthropics/claude-code/issues/38335)
 REM Part of claude-code-cache-fix: https://github.com/cnighswonger/claude-code-cache-fix
 
+REM Resolve npm global root and URL-encode it so spaces (e.g. "C:\Program Files\nodejs")
+REM don't break NODE_OPTIONS parsing. Without encoding, Node splits --import file:/// on
+REM the literal space and fails with ERR_MODULE_NOT_FOUND: Cannot find module 'C:\Program'.
 for /f "delims=" %%G in ('npm root -g') do set "NPM_GLOBAL=%%G"
-set NODE_OPTIONS=--import file:///%NPM_GLOBAL:\=/%/claude-code-cache-fix/preload.mjs
+for /f "delims=" %%U in ('powershell -NoProfile -Command "[System.Uri]::EscapeUriString(('%NPM_GLOBAL:\=/%' + '/claude-code-cache-fix/preload.mjs'))"') do set "PRELOAD_URL=%%U"
+set NODE_OPTIONS=--import file:///%PRELOAD_URL%
 node "%NPM_GLOBAL%\@anthropic-ai\claude-code\cli.js" %*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
   "type": "module",
   "exports": "./preload.mjs",

package/preload.mjs

@@ -631,6 +631,9 @@ import { join } from "node:path";
 const DEBUG = process.env.CACHE_FIX_DEBUG === "1";
 const PREFIXDIFF = process.env.CACHE_FIX_PREFIXDIFF === "1";
 const NORMALIZE_IDENTITY = process.env.CACHE_FIX_NORMALIZE_IDENTITY === "1";
+const STRIP_GIT_STATUS = process.env.CACHE_FIX_STRIP_GIT_STATUS === "1";
+const TTL_MAIN = (process.env.CACHE_FIX_TTL_MAIN || "1h").toLowerCase();
+const TTL_SUBAGENT = (process.env.CACHE_FIX_TTL_SUBAGENT || "1h").toLowerCase();
 const LOG_PATH = join(homedir(), ".claude", "cache-fix-debug.log");
 const SNAPSHOT_DIR = join(homedir(), ".claude", "cache-fix-snapshots");
 const USAGE_JSONL = process.env.CACHE_FIX_USAGE_LOG || join(homedir(), ".claude", "usage.jsonl");
@@ -672,6 +675,7 @@ const _STATS_SCHEMA = {
   tool_sort: { applied: 0, skipped: 0, lastApplied: null },
   ttl: { applied: 0, skipped: 0, lastApplied: null },
   identity: { applied: 0, skipped: 0, lastApplied: null },
+  git_status: { applied: 0, skipped: 0, lastApplied: null },
 };
 
 function _createEmptyStats() {
@@ -1221,41 +1225,88 @@ globalThis.fetch = async function (url, options) {
         }
       }
 
-      // Bug 5: 1h TTL enforcement
+      // Optimization: strip volatile git-status from system prompt
+      // CC injects live git-status output (branch, changed files, recent commits)
+      // into a system text block. This changes on every file edit, busting the
+      // entire prefix cache. Opt-in via CACHE_FIX_STRIP_GIT_STATUS=1.
+      // The model can still run `git status` via Bash tool when it needs context.
+      if (STRIP_GIT_STATUS && shouldApplyFix("git_status") && payload.system && Array.isArray(payload.system)) {
+        let stripped = 0;
+        payload.system = payload.system.map((block) => {
+          if (block?.type !== "text" || typeof block.text !== "string") return block;
+          // Match the gitStatus section CC injects. Pattern:
+          //   "gitStatus: This is the git status..."
+          //   followed by branch, status, commits until the next section or end
+          const gitStatusPattern = /gitStatus:.*?(?=\n# |\n## |\nWhen |\nAnswer |\n<[a-z]|$)/s;
+          if (!gitStatusPattern.test(block.text)) return block;
+          const newText = block.text.replace(gitStatusPattern, "gitStatus: [stripped by cache-fix for prefix stability]");
+          if (newText !== block.text) {
+            stripped++;
+            return { ...block, text: newText };
+          }
+          return block;
+        });
+        if (stripped > 0) {
+          modified = true;
+          debugLog(`APPLIED: git-status stripped from ${stripped} system block(s)`);
+          recordFixResult("git_status", "applied");
+        } else {
+          recordFixResult("git_status", "skipped");
+        }
+      }
+
+      // Bug 5: TTL enforcement (configurable per request type)
       // The client gates 1h cache TTL behind a GrowthBook allowlist that checks
       // querySource against patterns like "repl_main_thread*", "sdk", "auto_mode".
       // Interactive CLI sessions may not match any pattern, causing the client to
       // send cache_control without ttl (defaulting to 5m server-side).
       // The server honors whatever TTL the client requests — so we inject it.
       // Discovered by @TigerKay1926 on #42052 using our GrowthBook flag dump.
+      //
+      // v1.9.0: configurable per request type via CACHE_FIX_TTL_MAIN and
+      // CACHE_FIX_TTL_SUBAGENT. Values: "1h" (default), "5m", "none".
+      // "none" = don't inject TTL, pass through caller's original cache_control.
       if (payload.system && shouldApplyFix("ttl")) {
-        let ttlInjected = 0;
-        payload.system = payload.system.map((block) => {
-          if (block.cache_control?.type === "ephemeral" && !block.cache_control.ttl) {
-            ttlInjected++;
-            return { ...block, cache_control: { ...block.cache_control, ttl: "1h" } };
-          }
-          return block;
-        });
-        // Also check messages for cache_control blocks (conversation history breakpoints)
-        if (payload.messages) {
-          for (const msg of payload.messages) {
-            if (!Array.isArray(msg.content)) continue;
-            for (let i = 0; i < msg.content.length; i++) {
-              const b = msg.content[i];
-              if (b.cache_control?.type === "ephemeral" && !b.cache_control.ttl) {
-                msg.content[i] = { ...b, cache_control: { ...b.cache_control, ttl: "1h" } };
-                ttlInjected++;
+        // Detect subagent: Agent SDK identity in system[1]
+        const AGENT_SDK_PREFIX = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+        const isSubagent = Array.isArray(payload.system) &&
+          payload.system.some((b) => b?.type === "text" && typeof b.text === "string" && b.text.startsWith(AGENT_SDK_PREFIX));
+        const ttlValue = isSubagent ? TTL_SUBAGENT : TTL_MAIN;
+        const requestType = isSubagent ? "subagent" : "main";
+
+        if (ttlValue === "none") {
+          debugLog(`SKIPPED: TTL injection (${requestType} set to 'none' — pass-through)`);
+          recordFixResult("ttl", "skipped");
+        } else {
+          const ttlParam = ttlValue === "5m" ? "5m" : "1h";
+          let ttlInjected = 0;
+          payload.system = payload.system.map((block) => {
+            if (block.cache_control?.type === "ephemeral" && !block.cache_control.ttl) {
+              ttlInjected++;
+              return { ...block, cache_control: { ...block.cache_control, ttl: ttlParam } };
+            }
+            return block;
+          });
+          // Also check messages for cache_control blocks (conversation history breakpoints)
+          if (payload.messages) {
+            for (const msg of payload.messages) {
+              if (!Array.isArray(msg.content)) continue;
+              for (let i = 0; i < msg.content.length; i++) {
+                const b = msg.content[i];
+                if (b.cache_control?.type === "ephemeral" && !b.cache_control.ttl) {
+                  msg.content[i] = { ...b, cache_control: { ...b.cache_control, ttl: ttlParam } };
+                  ttlInjected++;
+                }
               }
             }
           }
-        }
-        if (ttlInjected > 0) {
-          modified = true;
-          debugLog(`APPLIED: 1h TTL injected on ${ttlInjected} cache_control block(s)`);
-          recordFixResult("ttl", "applied");
-        } else {
-          recordFixResult("ttl", "skipped");
+          if (ttlInjected > 0) {
+            modified = true;
+            debugLog(`APPLIED: ${ttlParam} TTL injected on ${ttlInjected} cache_control block(s) (${requestType})`);
+            recordFixResult("ttl", "applied");
+          } else {
+            recordFixResult("ttl", "skipped");
+          }
         }
       } else if (payload.system && !shouldApplyFix("ttl")) {
         debugLog("SKIPPED: TTL injection disabled via env var");
@@ -1271,6 +1322,60 @@ globalThis.fetch = async function (url, options) {
         monitorContextDegradation(payload.messages);
       }
 
+      // Diagnostic: dump cache breakpoint structure to a file when
+      // CACHE_FIX_DUMP_BREAKPOINTS=<path> is set. Maps where cache_control markers
+      // sit across system blocks and message content. Used to investigate #12
+      // (missing breakpoint #3 for skills/CLAUDE.md).
+      if (process.env.CACHE_FIX_DUMP_BREAKPOINTS && payload.system) {
+        try {
+          const dumpPath = process.env.CACHE_FIX_DUMP_BREAKPOINTS;
+          const breakpoints = [];
+          // System blocks
+          if (Array.isArray(payload.system)) {
+            payload.system.forEach((block, idx) => {
+              if (block.cache_control) {
+                breakpoints.push({
+                  location: "system",
+                  index: idx,
+                  type: block.type,
+                  cache_control: block.cache_control,
+                  text_preview: (block.text || "").slice(0, 120),
+                  text_chars: (block.text || "").length,
+                });
+              }
+            });
+          }
+          // Message blocks
+          if (payload.messages) {
+            payload.messages.forEach((msg, msgIdx) => {
+              if (!Array.isArray(msg.content)) return;
+              msg.content.forEach((block, blockIdx) => {
+                if (block.cache_control) {
+                  breakpoints.push({
+                    location: `messages[${msgIdx}].content`,
+                    role: msg.role,
+                    index: blockIdx,
+                    type: block.type,
+                    cache_control: block.cache_control,
+                    text_preview: (block.text || "").slice(0, 120),
+                    text_chars: (block.text || "").length,
+                  });
+                }
+              });
+            });
+          }
+          const dump = {
+            timestamp: new Date().toISOString(),
+            breakpoint_count: breakpoints.length,
+            breakpoints,
+            system_block_count: Array.isArray(payload.system) ? payload.system.length : 0,
+            message_count: payload.messages ? payload.messages.length : 0,
+          };
+          writeFileSync(dumpPath, JSON.stringify(dump, null, 2));
+          debugLog(`DUMP: ${breakpoints.length} cache breakpoints written to ${dumpPath}`);
+        } catch (e) { debugLog("BREAKPOINT DUMP ERROR:", e?.message); }
+      }
+
       // Diagnostic: dump full tools array (names, descriptions, schemas, sizes) to a file
       // when CACHE_FIX_DUMP_TOOLS=<path> is set. Useful for per-version tool-schema drift
       // analysis and for understanding which tools contribute prefix bloat. First used

package/tools/cost-report.mjs

@@ -397,13 +397,24 @@ function calculateCosts(entries, ratesData) {
       continue;
     }
 
-    // Determine cache write tier breakdown
-    // If telemetry has eph_1h/eph_5m, use those; otherwise assume all cache_create is 5m
-    let cw1h = entry.eph_1h;
-    let cw5m = entry.eph_5m;
-    if (cw1h === 0 && cw5m === 0 && entry.cache_create > 0) {
-      // No tier breakdown available; assume 5m (conservative — lower rate)
-      cw5m = entry.cache_create;
+    // Determine cache write tier for cache_creation tokens.
+    // eph_1h/eph_5m are READ tokens (cache hits per tier), not write tokens.
+    // But they tell us which tier the request was on — and cache creation on
+    // that request uses the same tier's write rate.
+    // Fix for #7: previously assigned all creation to 5m when eph fields were 0.
+    let cw1h = 0;
+    let cw5m = 0;
+    if (entry.cache_create > 0) {
+      if (entry.eph_1h > 0) {
+        // Request was on 1h tier — creation charged at 1h write rate
+        cw1h = entry.cache_create;
+      } else if (entry.eph_5m > 0) {
+        // Request was on 5m tier — creation charged at 5m write rate
+        cw5m = entry.cache_create;
+      } else {
+        // No tier signal available; assume 5m (conservative — lower rate)
+        cw5m = entry.cache_create;
+      }
     }
 
     const cost = (