claude-code-cache-fix 3.0.3 → 3.0.5

package/README.md

@@ -89,6 +89,20 @@ curl http://127.0.0.1:9801/health
 # {"status":"ok"}
 ```
 
+### Proxy configuration
+
+All proxy settings are controlled via environment variables. Set them before starting the proxy server.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CACHE_FIX_PROXY_PORT` | `9801` | Listen port |
+| `CACHE_FIX_PROXY_BIND` | `127.0.0.1` | Bind address |
+| `CACHE_FIX_PROXY_UPSTREAM` | `https://api.anthropic.com` | Upstream URL. Change to chain another proxy (e.g. `http://localhost:8080`) |
+| `CACHE_FIX_PROXY_TIMEOUT` | `600000` | Request timeout in milliseconds |
+| `CACHE_FIX_EXTENSIONS_DIR` | `proxy/extensions/` | Directory for extension `.mjs` files |
+| `CACHE_FIX_EXTENSIONS_CONFIG` | `proxy/extensions.json` | Extension configuration file |
+| `CACHE_FIX_DEBUG` | `0` | Enable debug logging |
+
 ### Corporate environments (proxies, custom CAs)
 
 The proxy honors the following environment variables when forwarding to `api.anthropic.com`. Behind Zscaler / Netskope / Forcepoint / Bluecoat / corporate squid, set these in the proxy's environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",

package/proxy/extensions/cache-telemetry.mjs

@@ -1,8 +1,63 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const QUOTA_PATH = join(homedir(), ".claude", "quota-status.json");
+
+function parseHeaders(headers) {
+  const get = (key) => headers[key] || "";
+  const num = (key) => parseFloat(get(key)) || 0;
+
+  const q5h_util = num("anthropic-ratelimit-unified-5h-utilization");
+  const q7d_util = num("anthropic-ratelimit-unified-7d-utilization");
+  const q5h_reset = parseInt(get("anthropic-ratelimit-unified-5h-reset")) || 0;
+  const q7d_reset = parseInt(get("anthropic-ratelimit-unified-7d-reset")) || 0;
+  const status = get("anthropic-ratelimit-unified-status") || get("anthropic-ratelimit-unified-5h-status");
+  const overage_status = get("anthropic-ratelimit-unified-overage-status");
+  const overage_util = num("anthropic-ratelimit-unified-overage-utilization");
+  const overage_reset = parseInt(get("anthropic-ratelimit-unified-overage-reset")) || 0;
+  const fallback_pct = get("anthropic-ratelimit-unified-fallback-percentage");
+  const representative = get("anthropic-ratelimit-unified-representative-claim");
+  const surpassed = get("anthropic-ratelimit-unified-7d-surpassed-threshold");
+
+  if (!q5h_reset && !q7d_reset) return null;
+
+  const now = new Date();
+  const hour = now.getUTCHours();
+  const day = now.getUTCDay();
+  const peak = day >= 1 && day <= 5 && hour >= 13 && hour < 19;
+
+  const allHeaders = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.startsWith("anthropic-") || k === "cf-ray" || k === "request-id") {
+      allHeaders[k] = v;
+    }
+  }
+
+  return {
+    five_hour: { utilization: q5h_util, pct: Math.round(q5h_util * 100), resets_at: q5h_reset },
+    seven_day: { utilization: q7d_util, pct: Math.round(q7d_util * 100), resets_at: q7d_reset },
+    status: status || "unknown",
+    overage_status: overage_status || "unknown",
+    peak_hour: peak,
+    all_headers: allHeaders,
+  };
+}
+
 export default {
   name: "cache-telemetry",
-  description: "Extract cache hit/miss stats from response stream for monitoring",
+  description: "Extract cache stats from response stream, persist quota state to ~/.claude/quota-status.json",
   order: 600,
 
+  async onResponseStart(ctx) {
+    if (!ctx.headers) return;
+
+    const quota = parseHeaders(ctx.headers);
+    if (!quota) return;
+
+    ctx.meta._quotaData = quota;
+  },
+
   async onStreamEvent(ctx) {
     const { event, telemetry } = ctx;
     if (!event || !telemetry) return;
@@ -19,6 +74,39 @@ export default {
     if (event.type === "message_delta" && event.usage) {
       if (!ctx.meta.cacheStats) ctx.meta.cacheStats = {};
       ctx.meta.cacheStats.outputTokens = event.usage.output_tokens || 0;
+
+      const stats = ctx.meta.cacheStats;
+      const quota = ctx.meta._quotaData;
+      if (!quota) return;
+
+      const cr = stats.cacheRead || 0;
+      const cc = stats.cacheCreation || 0;
+      const total = cr + cc;
+      const hitRate = total > 0 ? ((cr / total) * 100).toFixed(1) : "N/A";
+
+      const ephemeral1h = cc;
+      const ephemeral5m = 0;
+
+      const ttl = cr > 0 ? "1h" : (cc > 0 ? "5m" : "unknown");
+
+      const output = {
+        cache: {
+          ttl_tier: ttl,
+          cache_creation: cc,
+          cache_read: cr,
+          ephemeral_1h: ephemeral1h,
+          ephemeral_5m: ephemeral5m,
+          hit_rate: hitRate,
+          timestamp: new Date().toISOString(),
+        },
+        timestamp: new Date().toISOString(),
+        ...quota,
+      };
+
+      try {
+        mkdirSync(join(homedir(), ".claude"), { recursive: true });
+        writeFileSync(QUOTA_PATH, JSON.stringify(output, null, 2));
+      } catch {}
     }
   },
 };

package/tools/quota-statusline.sh

@@ -1,68 +1,43 @@
 #!/bin/bash
-# Status line: show quota % and burn rate from claude-meter JSONL
-# Rate is calculated from window start (reset_time - window_size) to now
-# No prev file needed — each reading is self-contained
+# Status line: show quota % and burn rate from quota-status.json
+# Written by cache-fix proxy's cache-telemetry extension on every API call.
 
 input=$(cat)
 
-JSONL="$HOME/.claude/claude-meter.jsonl"
 QS="$HOME/.claude/quota-status.json"
 
-# Primary source: claude-meter.jsonl (requires claude-code-meter package)
-# Fallback: quota-status.json (written by claude-code-cache-fix interceptor)
-if [ -f "$JSONL" ]; then
-  last=$(tail -1 "$JSONL" 2>/dev/null)
-elif [ -f "$QS" ]; then
-  # Translate quota-status.json into the same shape the Python expects
-  last=$(python3 -c "
-import json, pathlib
-qs = json.load(open(pathlib.Path.home() / '.claude' / 'quota-status.json'))
-fh = qs.get('five_hour', {})
-sd = qs.get('seven_day', {})
-print(json.dumps({
-    'q5h': fh.get('utilization', 0),
-    'q7d': sd.get('utilization', 0),
-    'q5h_reset': fh.get('resets_at', 0),
-    'q7d_reset': sd.get('resets_at', 0),
-    'qoverage': qs.get('overage_status', ''),
-    'ts': qs.get('timestamp', ''),
-}))
-" 2>/dev/null)
-else
-  exit 0
-fi
-
-if [ -z "$last" ]; then exit 0; fi
+if [ -f "$QS" ]; then
+  result=$(python3 -c "
+import sys, json, os
+from datetime import datetime, timezone, timedelta
 
-  result=$(echo "$last" | python3 -c "
-import sys, json
-from datetime import datetime, timezone
+qs = json.load(open(os.path.expanduser('~/.claude/quota-status.json')))
 
-r = json.load(sys.stdin)
-q5h = int(r['q5h'] * 100)
-q7d = int(r.get('q7d', 0) * 100)
-overage = r.get('qoverage', '')
-ts = r.get('ts', '')
-q5h_reset = r.get('q5h_reset', 0)
-q7d_reset = r.get('q7d_reset', 0)
+q5h = qs.get('five_hour', {}).get('pct', 0)
+q7d = qs.get('seven_day', {}).get('pct', 0)
+q5h_reset = qs.get('five_hour', {}).get('resets_at', 0)
+q7d_reset = qs.get('seven_day', {}).get('resets_at', 0)
+status = qs.get('status', '')
+overage = qs.get('overage_status', '')
+ts = qs.get('timestamp', '')
 
-now = datetime.fromisoformat(ts.replace('Z', '+00:00'))
+now = datetime.fromisoformat(ts.replace('Z', '+00:00')) if ts else datetime.now(timezone.utc)
 
-# Q5h: 5-hour window, rate = pct / minutes elapsed since window start
+# Q5h burn rate
 rate5 = ''
-if q5h_reset > 0:
-    window_start = datetime.fromtimestamp(q5h_reset, tz=timezone.utc) - __import__('datetime').timedelta(hours=5)
+if q5h_reset > 0 and q5h > 0:
+    window_start = datetime.fromtimestamp(q5h_reset, tz=timezone.utc) - timedelta(hours=5)
     elapsed_min = (now - window_start).total_seconds() / 60
-    if elapsed_min > 1 and q5h > 0:
+    if elapsed_min > 1:
         rate5 = '{:+.1f}'.format(q5h / elapsed_min)
 
-# Q7d: 7-day window
+# Q7d burn rate
 rate7 = ''
-if q7d_reset > 0:
-    window_start_7d = datetime.fromtimestamp(q7d_reset, tz=timezone.utc) - __import__('datetime').timedelta(days=7)
-    elapsed_min_7d = (now - window_start_7d).total_seconds() / 60
-    if elapsed_min_7d > 1 and q7d > 0:
-        rate7 = '{:+.1f}'.format(q7d / (elapsed_min_7d / 60))
+if q7d_reset > 0 and q7d > 0:
+    window_start_7d = datetime.fromtimestamp(q7d_reset, tz=timezone.utc) - timedelta(days=7)
+    elapsed_hr = (now - window_start_7d).total_seconds() / 3600
+    if elapsed_hr > 0.1:
+        rate7 = '{:+.1f}'.format(q7d / elapsed_hr)
 
 label = 'Q5h: {}%'.format(q5h)
 if rate5:
@@ -73,37 +48,23 @@ if rate7:
 if overage == 'active':
     label += ' | OVERAGE'
 
-# Add TTL tier from quota-status.json (written by interceptor)
-import os, pathlib
-qs_path = pathlib.Path.home() / '.claude' / 'quota-status.json'
-try:
-    qs = json.load(open(qs_path))
-    ttl = qs.get('cache', {}).get('ttl_tier', '')
-    hit = qs.get('cache', {}).get('hit_rate', '')
-    if ttl:
-        if ttl == '5m':
-            label += ' | \033[31mTTL:5m\033[0m'  # red
-            # When on 5m tier, show the cold-rebuild size so users know
-            # the cost of idling past 5 minutes
-            cache_cr = qs.get('cache', {}).get('cache_creation', 0)
-            cache_rd = qs.get('cache', {}).get('cache_read', 0)
-            prefix = cache_cr + cache_rd
-            if prefix > 0:
-                if prefix >= 1_000_000:
-                    label += ' \033[31m\u26A0 idle >5m = {:.1f}M rebuild\033[0m'.format(prefix / 1_000_000)
-                else:
-                    label += ' \033[31m\u26A0 idle >5m = {:.0f}K rebuild\033[0m'.format(prefix / 1_000)
-        else:
-            label += ' | TTL:' + ttl
-    if hit and hit != 'N/A':
-        label += ' ' + hit + '%'
-    peak = qs.get('peak_hour', False)
-    if peak:
-        label += ' | \033[33mPEAK\033[0m'  # yellow
-except:
-    pass
+# TTL and cache stats
+ttl = qs.get('cache', {}).get('ttl_tier', '')
+hit = qs.get('cache', {}).get('hit_rate', '')
+if ttl:
+    if ttl == '5m':
+        label += ' | \033[31mTTL:5m\033[0m'
+    else:
+        label += ' | TTL:' + ttl
+if hit and hit != 'N/A':
+    label += ' ' + hit + '%'
+
+peak = qs.get('peak_hour', False)
+if peak:
+    label += ' | \033[33mPEAK\033[0m'
 
 print(label)
 " 2>/dev/null)
 
   [ -n "$result" ] && echo "$result"
+fi