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 proxy also handles HTTP CONNECT. It MITMs only the upstream host (api.anthropic.com), terminating TLS with a locally-generated CA so it can run the same extension pipeline, and blind-tunnels every other CONNECT (mcp-proxy, telemetry, npm, ...) untouched. On first start it generates a CA under $CLAUDE_CONFIG_DIR/cache-fix-ca/ (default ~/.claude/cache-fix-ca/; override with CACHE_FIX_CA_DIR); the client must trust it via NODE_EXTRA_CA_CERTS. A WebSocket/Upgrade to the upstream host (e.g. /voice) is relayed to upstream as-is. Because base URL stays api.anthropic.com, all of /api/oauth/*, /v1/agents, Remote Control credential fetches, etc. pass through untouched and RC stays enabled.

Corporate proxy chaining works the same as reverse mode: set HTTPS_PROXY/HTTP_PROXY for the proxy's own upstream egress (the proxy dials api.anthropic.com through it). The client's HTTPS_PROXY points at the cache-fix proxy; the cache-fix proxy's HTTPS_PROXY (in its own env) points at the corporate proxy.

Crash semantics on a shared proxy. In forward-proxy mode the proxy MITMs the whole upstream host, so an in-flight Claude Code session is wired to this port and cannot fail over. To keep one bad request from taking the process down, a successful forward-proxy attach installs process-wide uncaughtException/unhandledRejection handlers that log and keep serving instead of crashing. These are scoped to forward mode (a reverse-only proxy keeps Node's default crash-on-uncaught semantics, letting its supervisor restart it) and are removed when the last forward instance closes. The tradeoff: on a shared / multi-tenant proxy, enabling forward mode changes crash behavior for every client on that instance while the mode is on — a fatal bug is swallowed rather than surfaced to a supervisor. If you run one proxy for many sessions, weigh that against a supervised per-session model.

Running it persistently. The ... node .../proxy/server.mjs & above is fine for a quick try, but a backgrounded process is not supervised: it does not restart if it crashes or if the machine reboots. To run forward-proxy mode as a managed service (auto-restart, start-on-login), use the same install-service path described under Running as a service — just set the flag at install time so it is baked into the unit:

CACHE_FIX_FORWARD_PROXY=on cache-fix-proxy install-service

The generated systemd unit / launchd agent carries CACHE_FIX_FORWARD_PROXY=on, so the service starts the proxy in forward-proxy mode and keeps it up (systemd Restart=on-failure plus the healthcheck timer; launchd KeepAlive).

The service only manages the proxy end. It does not — and cannot — set anything on your claude client, which is a separate process. You still wire the client yourself in whatever shell launches claude, using the two values from the forward-proxy quick-start above:

• HTTPS_PROXY — where the proxy listens: http://127.0.0.1:<port> (default port 9801, or your CACHE_FIX_PROXY_PORT).
• NODE_EXTRA_CA_CERTS — the CA the proxy generated on first start: ~/.claude/cache-fix-ca/ca.pem (or $CACHE_FIX_CA_DIR/ca.pem).

Three ways to wire it, depending on how broadly you want the vars to apply.

If anything else on this host also MITMs api.anthropic.com — a corporate TLS-inspecting agent, an account-switching pin proxy — do not use these recipes. NODE_EXTRA_CA_CERTS takes one file, so pinning it to our CA alone silently untrusts every other component. Use --remote-control, which publishes into ca-trust.d/ and consumes the merged bundle instead. See Coexisting with another MITM.

# a) per-invocation — scoped to just this claude run
HTTPS_PROXY=http://127.0.0.1:9801 \
NODE_EXTRA_CA_CERTS=~/.claude/cache-fix-ca/ca.pem \
  claude

# b) whole shell — add to ~/.zshrc / ~/.bashrc (every HTTPS in that shell goes
#    through the proxy; harmless since non-anthropic hosts are blind-tunneled,
#    but that shell's HTTPS breaks if the proxy is ever down)
export HTTPS_PROXY=http://127.0.0.1:9801
export NODE_EXTRA_CA_CERTS=~/.claude/cache-fix-ca/ca.pem

# c) scoped to claude only — a shell function (recommended; avoids b's blast radius)
claude() {
  HTTPS_PROXY=http://127.0.0.1:9801 \
  NODE_EXTRA_CA_CERTS=~/.claude/cache-fix-ca/ca.pem \
    command claude "$@"
}

Coexisting with another MITM on the same machine (ca-trust.d)

NODE_EXTRA_CA_CERTS takes exactly one file. If anything else on the host also MITMs api.anthropic.com and also sets that variable — a corporate agent, an account-switching pin proxy — the last writer wins and every other CA is silently untrusted. Measured 2026-07-30: two such components on one machine took turns breaking each other's TLS, with no error attributable to either.

So --remote-control does not simply assign the variable. It:

1. Publishes our CA to <config>/ca-trust.d/ccf.pem — our own filename only, never a sibling's, rewritten every launch (the proxy regenerates its CA whenever the CA dir is wiped, and a stale pem advertises a key nothing signs with), skipped when the bytes already match, and written via temp + rename so a reader never sees a half-written file.
2. Reads <config>/ca-trust.pem — a merged bundle built by exactly one external writer from the ambient/corporate roots plus every published ca-trust.d/*.pem — and points NODE_EXTRA_CA_CERTS at it.

<config> is CLAUDE_CONFIG_DIR or ~/.claude. We never write the merged bundle: merging requires finding the ambient corporate roots, which is environment-specific (a Linux host may keep them outside the bundle a shell points at; a Mac keeps them in the keychain), and two components both rebuilding it would race one output.

The bundle is used only if node, handed that file, will actually verify our proxy's leaf. The launcher does not predict that — it asks: a child process with NODE_EXTRA_CA_CERTS set from birth stands up a TLS server holding our leaf and connects to it. Only a bundle from which the loader really loaded our CA can complete that handshake.

A bundle failing that is worse than no bundle — it would make the client distrust the very proxy it is being routed through, so every request fails TLS rather than merely losing some other component's CA.

Why ask rather than parse. The previous version modelled node's loader in a regex: base64 quanta, padding position, dash runs in markers, which of ten whitespace characters openssl tolerates. It took five review rounds and was still wrong in both directions on a real bundle — accepting one node loads nothing from, and refusing one node loads fine. The rule it was reaching for turns out not to be expressible from outside: an identical tear is recovered or fatal depending only on whether its truncated body happens to be complete DER, which is a question about bytes the parser cannot answer. The loader can, in one spawn (~25 ms over a bare node -e '' — measured, 40 interleaved pairs: 17.3 ms bare, 42.4 ms probed). What that is 25 ms of: a --remote-control launch is ~520 ms end to end, of which ~493 ms is forking the proxy and waiting for it to listen. So the probe is ~8% of a launch and very nearly all of the CA work.

Three outcomes, never two. ok, not ok, and unknown — the last meaning the probe could not be run at all. A guard that answers "unusable" when it could not ask drops every corporate root on a machine whose bundle was fine.

A damaged merge does not cost the other publishers their CAs. The damage lives in the merge, not in the files that fed it, so the launcher rebuilds from the ca-trust.d/ publishers that still work rather than falling back to its own CA alone. The saving is one certificate per surviving publisher: measured on this box (ours plus one peer), one certificate under the old fallback against two under the rebuild; on a three-publisher host, one against three.

Both paths are fixed names under <config>, deliberately with no env override of their own. They are two halves of one rendezvous: a knob on either half alone lets a participant publish where no builder looks, or read a file no builder writes, while still appearing to implement the contract. CLAUDE_CONFIG_DIR already relocates the pair, and it moves both halves together.

Note the limit of what a consumer checks: intact, and carries my CA. Whether the bundle is complete — that no corporate root went missing — is the builder's guarantee, and a consumer must not act on it even where it could.

That is a design choice, not a missing capability, and the distinction matters because the other reading is an invitation: someone adds the previous bundle as state, believes the limitation is lifted, and adds a floor. It would still be wrong. A shrink is legitimate whenever a root is retired or a component is uninstalled, and only the builder knows which happened — so a reader holding both bundles still cannot tell a regression from a fact. Measured: a legitimate bundle is 5 certs on one machine here and 168 on another, so any floor that catches narrowing on one host rejects a healthy bundle on the next.

This is a cooperative convention among same-user processes, not a trust boundary. The check proves parses, and carries us — never contains only approved writers. Anyone who can write <config> can hand us a well-formed bundle holding our CA plus their own and it will be accepted, exactly as they could already have replaced ca-trust.d/ccf.pem, the CA dir, or this file. The contract defends against components accidentally untrusting each other, which is the failure that actually happens; it does not defend against a local attacker, who has simpler routes.

CACHE_FIX_DOWNLOAD_REWRITE breaks claude update — leave it off

CACHE_FIX_DOWNLOAD_REWRITE=on reads like a pure performance knob. It is not: turning it on disables claude update entirely on that host. Rewriting a download URL means reading it, which means MITM-ing downloads.claude.ai — and the release-channel client pins public roots only and rejects any private CA, so the version check dies before a byte is downloaded:

Failed to fetch version from .../claude-code-releases/latest after 3 attempt(s):
  unable to verify the first certificate

Measured with openssl s_client -proxy 127.0.0.1:9901 -connect downloads.claude.ai:443 -servername downloads.claude.ai:

CACHE_FIX_DOWNLOAD_REWRITE	leaf CN	verify
on	api.anthropic.com	code 21
off	downloads.claude.ai (WR3 / GTS Root R1)	code 0

Two things make this worse than it first looks:

• It cannot be narrowed to the binary download. MITM is decided per host at CONNECT time, and the version check shares downloads.claude.ai with the download itself. It is all-or-nothing per host.
• No client-side override reaches that client. HTTPS_PROXY / ALL_PROXY, /etc/hosts, /etc/resolv.conf, and NODE_EXTRA_CA_CERTS were each disproved against a control on the identical path — a local resolver logged 0 queries and a TCP forwarder logged 0 connects across a full claude update, while a plain node https.get through that same forwarder returned 200. So no amount of CA injection can make the rewrite work. Only not intercepting works.

Other hosts are unaffected: github.com through the same proxy returns its real certificate and verifies. The flag is off by default; keep it that way unless you are prepared to update Claude Code some other way.

What the proxy does

On every /v1/messages request, the pipeline runs an ordered chain of extensions covering cache stability, observability, thinking-desync mitigation, image, microcompact, breakpoint, bootstrap-channel, and other surfaces. Several are gated behind env vars documented in their own sections below; bootstrap-channel handling defaults to audit mode. The headliners:

Extension	What it fixes
fingerprint-strip	Removes unstable cc_version fingerprint from system prompt
sort-stabilization	Deterministic ordering of tool and MCP definitions
ttl-management	Detects server TTL tier, injects correct cache_control markers
identity-normalization	Normalizes message identity fields for prefix stability
fresh-session-sort	Fixes non-deterministic ordering on first turn
cache-control-normalize	Normalizes cache_control markers across messages
cache-telemetry	Extracts cache stats from response headers → ~/.claude/quota-status/{account.json,sessions/<id>.json}
session-health	Observes per-session thinking-desync risk (context size + thinking-block count) and warns before a session reaches the danger zone. Read-only
thinking-block-sanitize	Drops omitted (empty-text) thinking blocks to head off the CC thinking-desync 400 (#63147). On by default as of v4.0.0 (v1 mode). Set CACHE_FIX_THINKING_SANITIZE=off to disable, =v2 for additional tools-hash-mismatch drop (opt-in).
workflow-agent-id-synthesis	Derives a stable per-leg agent id for Workflow-tool subagents whose canonical x-claude-code-agent-id header CC does not set (CC#66761). On by default; stash lives on ctx.meta._workflowAgentId and never leaves the proxy. usage-log emits the agent_id + agent_id_source fields when CACHE_FIX_USAGE_LOG_AGENT_ID=on AND meter v0.8.0+ is installed. Master switch: CACHE_FIX_WORKFLOW_AGENT_DERIVATION=off.
session-budget-breaker	Opt-in hard per-session spend ceiling — short-circuits a session's requests locally once its cumulative tokens / estimated cost / consumption rate cross a limit you set, so a runaway fan-out can't drive credits or auto-purchase ([CC#68285](https: