Claude代码缓存修复工具

Install

npm install -g claude-code-cache-fix

Docker

A multi-arch (amd64, arm64) container image is published to GitHub Container Registry on every release tag.

```bash docker run -d --name cache-fix-proxy \ --restart=always \ -p 9801:9801 \ ghcr.io/cnighswonger/claude-code-cache-fix:latest

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.

```bash

Quick Start: Preload (CC v2.1.112 and earlier)

If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor works without a proxy:

npm install -g claude-code-cache-fix
NODE_OPTIONS="--import claude-code-cache-fix" claude

Note: The preload does NOT work on CC v2.1.113+ (Bun binary). Use the proxy above.

See docs/preload-setup.md for wrapper scripts, shell aliases, Windows instructions, and VS Code preload-mode integration.

It prints the two env vars to wire the client, e.g.:

Proxy configuration

All proxy settings are controlled via environment variables. Set them before starting the proxy server.

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.

Example (Windows PowerShell):

$env:HTTPS_PROXY = 'http://proxy.corp.example:8080'
$env:NO_PROXY    = 'localhost,127.0.0.1,.corp.example'
$env:CACHE_FIX_PROXY_CA_FILE = 'C:\corp\zscaler-root.pem'
node "$(npm root -g)\claude-code-cache-fix\proxy\server.mjs"

Stderr will print [upstream] using proxy http://proxy.corp.example:8080 ... on first request when the agent is wired correctly. With no proxy/CA env vars set, behavior is unchanged from earlier versions (Node default agent, system trust store).

Recommended CC operational config

The proxy fixes what it can fix at the request layer. A handful of CC client-side env vars and ~/.claude/settings.json knobs solve adjacent problems the proxy can't reach — silent model swaps on CC update, ambiguous model fallback, schema-strip side effects. Surfacing these here as a recommendation; users decide their own config.

These findings come from @fgrosswig's binary analysis of CC v2.1.91. Methodology is public PowerShell + ASCII string extraction; he shared the resulting punch list privately as a courtesy.

Suggested `~/.claude/settings.json` env block

The model IDs below are illustrative — replace with your preferred main and small-fast models. The point is that pinning something explicit beats relying on CC's defaults.

{
  "env": {
    "CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP": "1",
    "ANTHROPIC_MODEL": "claude-opus-4-7",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
  }
}

CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1 — single most impactful flag. CC has a legacy code path that silently remaps your pinned model to a different one after certain version updates. Setting this to 1 disables the remap; the model you pin is the model you get. (If you don't pin, CC's defaults apply as usual.)

ANTHROPIC_MODEL — pins the primary model. Keeping this explicit means the cache prefix hash stays stable across CC version bumps that would otherwise swap your default. Adjust to whichever model you actually want.

ANTHROPIC_SMALL_FAST_MODEL — pins the side-channel "fast" model CC uses for short auxiliary calls (e.g., title generation, classification). Without an explicit pin, this can silently fall back to a different family on update.

Embedder note (Bun hosts, DAP-style integrations using `createProxyServer()` / `startProxy()`)

v4.0.0 flips CACHE_FIX_THINKING_SANITIZE from default-off to default-on. The v1 omitted-text drop will run on every request body passing through the embedded proxy. If your host depends on the prior no-sanitization behavior (e.g., your downstream code expects empty thinking blocks to survive the proxy round-trip), preserve it by either:

• Setting CACHE_FIX_THINKING_SANITIZE=off in your host's environment, OR
• Setting process.env.CACHE_FIX_THINKING_SANITIZE = "off" in your code at any point before request handling — the mode is read per-request via modeFromEnv(), not cached at module load.

The flip is backed by 7 days of prod dogfood (37 sessions, zero cannot be modified 400s, cache hit-rate aggregate 94.66% vs 92.44% baseline). See PR #201 for the validation data and #63147 for upstream context.

Picking up a new extension or a code change to an existing one in v4.0.0 requires a supervisor-level proxy restart. There are two upgrade flows depending on whether you also want to opt back into hot-reload.

VS Code Extension

The VS Code extension (v0.5.0) supports both proxy and preload modes:

Proxy mode (recommended): 1. Start the proxy (see above) 2. In VS Code command palette: Claude Code Cache Fix: Enable Proxy Mode 3. Restart any active Claude Code session

Preload mode (CC ≤v2.1.112): 1. npm install -g claude-code-cache-fix 2. Download the VSIX from GitHub Releases 3. Install: code --install-extension claude-code-cache-fix-0.5.0.vsix 4. Command palette: Claude Code Cache Fix: Enable

For manual VS Code wrapper setup (without the VSIX), see docs/preload-setup.md.