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

Setup

mkdir -p ~/.claude/hooks
cp "$(npm root -g)/claude-code-cache-fix/tools/quota-statusline.sh" ~/.claude/hooks/
chmod +x ~/.claude/hooks/quota-statusline.sh

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/hooks/quota-statusline.sh"
  }
}

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 hot-reloadable 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.

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.

System prompt rewrite (preload mode, optional)

The interceptor can rewrite Claude Code's # Output efficiency system-prompt section. Disabled by default. Enable with CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT. See docs/output-efficiency-prompts.md for the three known prompt variants and usage instructions.

Canonical filename rule — must mirror proxy/extensions/cache-telemetry.mjs

Image-guard pipeline (v3.3.0)

A conditional pipeline that mirrors Anthropic's actual rules. Strictly opt-in via a single env var:

export CACHE_FIX_IMAGE_GUARD=1

When enabled, the proxy runs:

Execution order: Pass 0 → Pass 3 → Pass 1 → Pass 2 → count cap. Each pass is independent — Pass 1 never resizes; Pass 3 never strips.

Optional sharp dependency

Pass 3 requires sharp for Lanczos resize. It's declared as an optional peer dependency — install separately if you want Pass 3:

npm install sharp

If sharp is missing, Pass 3 skips cleanly (telemetry records library_missing: true); Pass 1 + Pass 2 + the count cap still run.

Precedence matrix

Tunables

Explicit no-op (extension passes through unchanged)

export CACHE_FIX_THINKING_DISPLAY=disabled ```

The extension is default-on as of v3.6.1. The cache-prefix test measured 0% absolute drop in steady-state cache_read ratio when injection is active on Opus 4.7 (5 sequential claude -p calls per window, baseline vs injected — both windows held 1.000 cache_read ratio from call 2 onward). Adding thinking.display to the request body changes the bytes Anthropic hashes, but Anthropic's cache layer accepts and indexes the injected-prefix the same way it does any other prefix. Users who want the older "no injection" behavior (e.g. to avoid any request-body mutation at all) explicitly set CACHE_FIX_THINKING_DISPLAY=disabled.

Scoping rules baked into the extension:

• Model-gated. Only fires on requests whose model matches /^claude-opus-4-7/ — covers claude-opus-4-7 and claude-opus-4-7-1m. Sonnet 4.7 needs separate verification (the API default-flip may differ); future versions (4.8+) require an explicit cache-fix bump rather than auto-applying unverified behavior.
• User opt-out preserved. If the request already has thinking.display set (either "summarized" or "omitted"), the extension never overwrites. Explicit user choice always wins.
• Thinking-active types only. The extension fires on thinking.type ∈ { "enabled", "adaptive" } — the two active modes that produce thinking blocks on Opus 4.7. Other values ("disabled", future modes) are skipped. Conservative: if Anthropic ships a new thinking type with different display semantics, we'd rather miss the fix than auto-apply incorrect behavior.

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.