claude-code-cache-fix

English | 中文 | 한국어 | Français | Português

Cache optimization proxy for Claude Code. Fixes prompt cache bugs that cause excessive quota burn, stabilizes the request prefix, and monitors for silent regressions. Works with all CC versions including the v2.1.113+ Bun binary.

This README documents current main; release availability is noted per feature.

What it does to your traffic

A local proxy sits between Claude Code and Anthropic. Before you read further, here is exactly what that means — the full treatment is in Security model.

• Binds to 127.0.0.1 by default.
• Forwards Claude Code traffic to Anthropic. On the default path it makes no other outbound calls — telemetry is written to local files under ~/.claude/, never sent anywhere. Two opt-in features do perform their own egress, both off unless you enable them: OAuth refresh (CACHE_FIX_OAUTH_REFRESH=on) posts to Anthropic's token endpoint, and forward-proxy download acceleration re-issues release downloads to downloads.claude.ai / storage.googleapis.com.
• Can read and rewrite POST /v1/messages. That capability is the cache repair — there is no version of this that works without it.
• It is idempotent: if nothing needs fixing, the request passes through unmodified. It normalizes request structure (block order, fingerprint, TTL); it does not modify your conversation.
• Each transform is one file in proxy/extensions/, readable in isolation.
• Independently assessed as a legitimate tool by @TheAuditorTool (2026-04-14).

Forward-proxy mode (--remote-control) additionally terminates TLS for api.anthropic.com using a locally-generated CA, which your client must trust. Everything else is blind-tunnelled. That mode is opt-in and off by default.

Do you need this?

Install or test it if: resumed or long-running sessions show repeated cache_creation_input_tokens spikes; your cache-read ratio is low or unstable; you see unexpected TTL 5m downgrades, thinking-desync 400s, or image-retry storms; or one of the non-cache surfaces documented below applies.

You can skip it if: your sessions already hold a stable high cache-read ratio; you rarely resume long sessions; you are not under quota pressure; or you would rather not place a local proxy in the API path. All four are good reasons not to install this.

If you are not sure which applies, measure it — you do not need this project installed to find out.

Check whether you have this problem

Claude Code already records per-request cache accounting in its own session transcripts, so you can measure your cache health right now, before installing anything.

# Replace <session-uuid>, or use a glob to pick your most recent session.
jq -r 'select(.message.usage.cache_read_input_tokens != null) |
  "\(.requestId)\t\(.message.usage.cache_read_input_tokens) \(.message.usage.cache_creation_input_tokens)"' \
  ~/.claude/projects/*/<session-uuid>.jsonl |
  sort -u -k1,1 | cut -f2 |
  awk '{n++; r+=$1; c+=$2}
       END {if (n==0) print "no usage rows found — check the session path";
            else printf "requests=%d cache_read=%d creation=%d read-ratio=%.0f%%\n", n, r, c, 100*r/(r+c)}'

sort -u -k1,1 counts each API call once — Claude Code writes multiple transcript rows per request, and not always the same number of times per request (ArkNill's analysis). Summing raw rows weights each call by its own duplicate count. Two independent sweeps of the local transcripts on one machine (2026-08-02) agreed on the shape: short sessions are where this bites — over half of sessions under 20 requests shifted by a point or more without the dedup, worst case 41 points, while long sessions were almost all sub-point (3 of ~37). Short sessions are exactly what a first-time reader will run this against.

Reading the result:

• Fewer than ~20 requests: the number is meaningless. A cold start has nothing to read yet, so creation dominates and every healthy session looks broken. Use a long or resumed session.
• Sustained low ratio on a long session, or creation spiking on every --resume — that is the problem this project exists to fix.
• High ratio on a long session — you do not need this. See Do you need this? above.

Current advisories

v4.0.0 — Local HTTP proxy with a pipeline of cost-impact and observability extensions. Two long-standing defaults flipped: thinking-block-sanitize v1 is on by default (mitigates the thinking-desync 400 wedge — #63147) and in-process extension hot-reload is opt-in (CACHE_FIX_HOT_RELOAD=on). A/B baseline (v3.0.0 on v2.1.117): 95.5% cache hit rate through proxy vs 82.3% direct on first warm turn. Full release notes →

Opus 4.7 advisory: Metered data shows 4.7 burns Q5h quota at ~2.4x the rate of 4.6 for equivalent visible token counts (independently confirmed by @ArkNill). Two factors: a new tokenizer (up to 35% more tokens, documented) and adaptive thinking overhead (~105%, not documented in usage response). The Q5h impact compounds into Q7d — the weekly quota ceiling that most heavy users will hit first. Workaround: CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 reduces burn by ~3.3x but may reduce quality on complex tasks. See Discussion #25 (initial observation) and Discussion #42 (controlled A/B data + Q7d analysis).

Quick Start: Proxy (recommended)

The proxy works with any CC version — Node.js or Bun binary. It sits between Claude Code and the Anthropic API, applying cache fixes as composable extensions.

# Install
npm install -g claude-code-cache-fix

# Start the proxy (runs on localhost:9801)
node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" &

# Launch Claude Code through it
ANTHROPIC_BASE_URL=http://127.0.0.1:9801 claude

That's it. The proxy applies its default extension pipeline automatically. No wrapper scripts, no NODE_OPTIONS, no preload.

Forward-proxy mode (keeps Remote Control working)

The quick-start above is reverse-proxy mode: you point ANTHROPIC_BASE_URL at the proxy. That is simple, but on Claude Code >= 2.1.196 a non-Anthropic ANTHROPIC_BASE_URL disables Remote Control (/remote-control), /schedule, and claude.ai MCP connectors (CC treats any custom base URL like a Bedrock/Vertex gateway). If you rely on those features, use forward-proxy mode instead.

In forward-proxy mode the proxy sits in front of the real api.anthropic.com as an HTTPS_PROXY. Claude Code's base URL stays api.anthropic.com, so Remote Control keeps working, while the proxy still sees and transforms /v1/messages.

# Start the proxy in forward-proxy mode
CACHE_FIX_FORWARD_PROXY=on node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" &
# It prints the two env vars to wire the client, e.g.:
#   export HTTPS_PROXY=http://127.0.0.1:9801
#   export NODE_EXTRA_CA_CERTS=~/.claude/cache-fix-ca/ca.pem

# Launch Claude Code through it (leave ANTHROPIC_BASE_URL UNSET)
HTTPS_PROXY=http://127.0.0.1:9801 \
NODE_EXTRA_CA_CERTS=~/.claude/cache-fix-ca/ca.pem \
  claude

Or let the launcher do both steps for you with --remote-control:

# Spawns the proxy with CACHE_FIX_FORWARD_PROXY=on and wires the client
# (HTTPS_PROXY + the MITM CA, ANTHROPIC_BASE_URL left unset) automatically.
cache-fix-proxy --remote-control

The --remote-control flag is the one-command equivalent of the manual wiring above: it starts the proxy in forward-proxy mode, waits for the CA, and launches claude pointed at HTTPS_PROXY with NODE_EXTRA_CA_CERTS set (and adds 127.0.0.1,localhost,::1 to NO_PROXY so local services — e.g. HTTP/SSE-transport MCP servers on localhost — bypass the proxy rather than being routed at it; any existing NO_PROXY is preserved). Without the flag the launcher stays in reverse-proxy mode (sets ANTHROPIC_BASE_URL), unchanged. Two things worth knowing: Remote Control does a trusted-device enrollment on first connect that can need a few /remote-control retries (a Claude Code step that runs upstream, not a proxy failure); and enabling RC on an already-warm session costs a single prompt-cache rebuild (RC adds an anthropic-beta the cache keys on), so if you want RC, launching with --remote-control from the start avoids that one-time flip. cache-fix-proxy --help documents both.

If you wire forward-proxy mode manually (setting HTTPS_PROXY yourself instead of using --remote-control), set NO_PROXY=127.0.0.1,localhost,::1 as well, or local HTTP-transport MCP servers and other localhost services will be routed at the cache-fix proxy and fail. stdio-transport MCP servers are unaffected (they use pipes, not the network).

How it works: the p