claude-code-cache-fix

English | 中文 | 한국어 | 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.

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:

# 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 "$@"
}

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.