claude-code-cache-fix

What It Is (confidence: medium)

claude-code-cache-fix (cnighswonger/claude-code-cache-fix) is a local HTTP proxy (localhost:9801) that fixes a silent prompt-cache regression in Claude Code: on --resume//resume the cache breaks silently and the API rebuilds the prefix every turn — a session that should cost ~$0.50/hourburning$5–10/hour. Repo headline claim: “up to 20x cost increase on resumed sessions.” Preload mode (NODE_OPTIONS="--import claude-code-cache-fix") patches globalThis.fetch for CC ≤ v2.1.112.

Key Points (confidence: medium)

• Root cause, three interacting bugs: partial block scatter (attachment blocks drift out of messages[0]), fingerprint instability (cc_version fingerprint derives from messages[0]), non-deterministic tool ordering (tool definitions arrive in different byte orders between turns). Base64 images persist in history and ride every subsequent call.
• Fix = request-normalization proxy, not a client patch: ordered chain of extensions — fingerprint-strip, sort-stabilization, ttl-management, identity-normalization, cache-control-normalize, cache-telemetry, thinking-block-sanitize, session-health. Both modes idempotent (untouched requests pass through byte-identical). Forward-proxy mode (HTTP CONNECT + selective MITM) exists because a custom ANTHROPIC_BASE_URL disables Remote Control on CC ≥ 2.1.196.
• Measured impact: A/B baseline — 95.5% cache hit via proxy vs 82.3% direct on first warm turn (CC v2.1.117); prod dogfood 7 days/37 sessions zero “cannot be modified” 400s, 94.66% vs 92.44% aggregate hit rate; community 7.5h/536-call session at 98.4% hit rate.
• Observability is the real value: writes ~/.claude/quota-status/account.json + per-session files (TTL tier, hit rate); quota-statusline.sh shows Q5h/Q7d bars with exhaust-vs-reset projection, TTL tier, overage flag. Server-side overage TTL downgrade (1h → 5m at Q5h ≥ 100%) is otherwise invisible.
• Native flags beat proxy patches at the source: CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1 saves ~1,800 tokens/call (community: 18-token cache creation vs thousands); model pinning (ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL) keeps the prefix hash stable across CC updates.

Implications (confidence: medium)

This is the concrete tool-side story behind prompt-caching’s economics and a live example of the paper’s lesson: cache traffic dominates the bill (~80-87%), so keeping the cache intact dwarfs payload trimming. It also documents a second silent-cost mode — inflated cached history from diagnostic slash commands (e.g. +3,480 cache_creation_input_tokens per /context on v2.1.148) that never appears in the local transcript. The “native flag beats proxy patch” principle aligns with claude-code-best-practices’ layered-config guidance.

Open Questions

• Version-sensitive: preload works only on CC ≤ v2.1.112; reverse-proxy mode breaks Remote Control on CC ≥ 2.1.196; auto-1M guard targets v2.1.161+; thinking-block-sanitize default flipped on in v4.0.0. Self-reported figures: “20x” and “$0.50\to$5–10/hr” are the author’s framing; several metrics are one-off community A/B tests.
• Fingerprint salt and block-detection heuristics derive from CC internals — a major CC refactor could break them; no sigstore provenance attestation published.

Related

prompt-caching — core subject: cache-hit rates, prefix stability, TTL tiers token-usage-reduction — git-status flag, image stripping, model pinning as token levers token-reduction-is-not-cost-reduction — Opus 4.7 tokenizer inflation is an explicit case headroom — quota/overage monitoring, Q5h/Q7d statusline analogs claude-code-best-practices — recommended operational env config

Sources

• raw/external/github-com-claude-code-cache-fix-0e94ee20.md