claude-code-cache-fix CLI
Local proxy between Claude Code and Anthropic that fixes prompt-cache misses, stabilizes the request prefix and shows quota use in the status line
- 448 ★ on the repository
- Last commit
Broad access
Why this level
- The proxy sits on the path of every Anthropic API request and can read and rewrite them and the responses, your prompts and code included
- Forward-proxy mode terminates TLS for api.anthropic.com with a local CA the client must trust
- The proxy listens on a port on your machine, and running it as a service keeps it up permanently
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/claude-code-cache-fixDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The proxy sits on the path of every Anthropic API request and can read and rewrite them and the responses, your prompts and code included
- Forward-proxy mode terminates TLS for api.anthropic.com with a local CA the client must trust
- The proxy listens on a port on your machine, and running it as a service keeps it up permanently
This is third-party code. Review the repository files before installing.
What it does
claude-code-cache-fix installs as an npm package and starts an HTTP proxy on your machine that sits between Claude Code and the Anthropic API. The proxy intercepts POST /v1/messages requests and reshapes them so the prompt cache stops breaking: it strips the unstable version fingerprint from the system prompt, sorts tool and MCP definitions deterministically, places cache_control markers with the right TTL and normalizes message identity fields. If nothing needs fixing, the request passes through unchanged. Beyond the cache, a chain of extensions covers other tasks. thinking-block-sanitize removes empty thinking blocks by default, which prevent the 400 error on resumed sessions. auto-1m-guard notices when Claude Code switches itself to the million-token context and, by setting, warns or strips that flag. bootstrap-defense logs server-supplied prompt fragments in Claude Code and can block them. An optional per-session spend ceiling is available separately. Cache telemetry is written to ~/.claude/quota-status/, and the status line shows the 5-hour and 7-day quota, the TTL tier and the cache hit rate. To run it: install from npm, start the proxy on port 9801 and launch ANTHROPIC_BASE_URL=http://127.0.0.1:9801 claude. For Claude Code 2.1.112 and earlier there is a preload mode with no proxy.
Who it is for. For Claude Code users on a subscription or pay-per-token plans who see spend spikes when resuming long sessions and are ready to put a local proxy in the path.
Good fit when
- After --resume in a long session cache_creation_input_tokens keeps spiking while the cache-read ratio stays low
- The five-hour quota drains faster than it should and you want TTL and hit rate in the status line
- A resumed session fails with a 400 error because of thinking blocks
- You want a hard per-session spending ceiling against runaway subagent fan-out
- You want to see which server-supplied fragments Claude Code mixes into the prompt: the bootstrap-defense extension logs them
Not a fit when
- Your cache already holds a high hit rate: the author names this as a reason not to install the proxy
- You rarely resume long sessions and do not run into the quota
- You do not want a local proxy on the API request path: it can read and rewrite POST /v1/messages
- You need /remote-control, /schedule and claude.ai connectors with a custom ANTHROPIC_BASE_URL: for them a forward-proxy mode exists that requires trusting a local CA
Example request
Install claude-code-cache-fix, start the proxy on port 9801 and check in the logs whether the cache-read share went up after resuming a sessionLimitations
Needs Node.js 18 or newer and Claude Code. The proxy listens on 127.0.0.1:9801. The Anthropic API is unavailable from Russia, so you need your own route to it.
- The proxy sees and can change API requests and responses. The author stresses that cache repair is impossible without this.
- Forward-proxy mode (--remote-control) terminates TLS only for api.anthropic.com using a locally generated CA that the client must trust. All other traffic goes through untouched.
- Two optional features make their own outbound calls: OAuth refresh and download acceleration. Both are off by default.
- Version 4.0.0 turned thinking-block-sanitize on by default; extension hot-reload is now optional.
- The license is MIT.
How to disable. Stop the proxy process, unset ANTHROPIC_BASE_URL (or HTTPS_PROXY and NODE_EXTRA_CA_CERTS in forward-proxy mode) and remove the package with npm rm -g claude-code-cache-fix. The ~/.claude/cache-fix-ca/ directory with the local CA can be deleted by hand.
FAQ
How do I know whether I need claude-code-cache-fix?
Measure the cache-read ratio from the session transcripts in ~/.claude/projects/ with the jq command in the README. If it stays high on a long session, you do not need the proxy. A low ratio and spikes in cache_creation_input_tokens on --resume mean it can help.
How do I run Claude Code through the proxy?
Run npm install -g claude-code-cache-fix, start node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" &, then ANTHROPIC_BASE_URL=http://127.0.0.1:9801 claude. No wrappers or NODE_OPTIONS are needed.
What do I do to keep Remote Control and claude.ai connectors working?
From Claude Code 2.1.196 a custom ANTHROPIC_BASE_URL disables /remote-control, /schedule and claude.ai connectors. Run cache-fix-proxy --remote-control: forward-proxy mode leaves the API address unchanged.
Does the proxy send my data anywhere?
On the default path it only makes the requests to Anthropic that Claude Code would send anyway, and telemetry goes to local files under ~/.claude/. The exceptions are off by default: OAuth refresh and download acceleration.
What does the session-budget-breaker extension do?
An optional hard per-session ceiling: once cumulative tokens, estimated cost or burn rate cross your limit, the proxy cuts that session's requests locally before they reach the API.
Discussion
No questions or reviews yet.
Related
CLI toolsClaude Usage
claude-usage
A local dashboard from Claude Code logs: tokens, models, sessions and projects. For Pro and Max subscribers it shows the full picture instead of a gauge
Shows what Claude Code and Codex actually send to the API: it captures local traffic and splits tokens and cost by source
Claude Code Tools
claude-code-tools
A set of practical tools for Claude Code, Codex CLI and similar agents: utilities, skills, agents, hooks and plugins for terminal work
A GitHub Action that runs Claude Code in pull requests and issues: answers mentions, reviews and makes changes
Continuous Claude
continuous-claude
Claude Code in a continuous loop: iteration, pull request, waiting for checks and merge. Stops on several completion signals. jq and gh are needed
Token Optimizer
token-optimizer
A plugin for Claude Code and Codex: trims wasted tokens, keeps work alive across sessions and compactions and shows cost. The license is noncommercial
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| claude-code-cache-fix (this entry) | no | 448 | ||
| RTK | no | 84,978 | compresses git and test command output so the agent spends fewer tokens reading the terminal | |
| Context Mode | no | not required | 32,835 | an MCP server that keeps large tool output out of the context and stores session memory |
| TokenTracker | no | 2,153 | counts tokens and spend from local logs and shows a dashboard without changing requests |
README in short
The page opens with a frank description of what the proxy does to your traffic and a check for whether you need it. It continues with a way to measure the cache without installing anything, the current advisories and a quick start in reverse-proxy and forward-proxy modes. The main part covers the extension chain with a table, running as a service and in Docker, configuration, upgrading from 3.x, defenses against specific regressions, the quota status line and a preload mode for older Claude Code versions.