A local cache for Claude Code

Stop paying twice for the same answer.

Ask Claude Code the same question about the same file twice, and it burns the same tokens explaining it twice. ClaudeCache sits in front of Claude Code as an MCP server: it checks a local SQLite cache before a query spends tokens, and invalidates itself the instant a referenced file changes — so a hit is never stale.

Get it on npm → npx claudecached init --yes

CLAUDECACHE

cache_lookup — sample

query"what does auth.js do?"

match typesemantic

similarity0.956

input tokens1,840

output tokens210

you paid$0.00

hit

The problem

Every re-explanation is a full-price re-explanation.

A rephrased question, a teammate asking about the same middleware, a second look after a coffee break — none of it needs to hit the model again if the underlying files haven't moved.

Without ClaudeCache

Mon 9:14 — "summarize auth.js"1,840 tok

Mon 14:02 — same question1,840 tok

Tue 10:31 — teammate asks too1,840 tok

Total spent5,520 tok

With ClaudeCache

Mon 9:14 — "summarize auth.js"1,840 tok

Mon 14:02 — same question$0 · cache hit

Tue 10:31 — teammate asks too$0 · cache hit

Total spent1,840 tok

How it works

Five rules keep it fast and honest.

exact-match key

SHA-256 of the prompt plus every referenced file's current content hash. Change one byte of a file and the key changes — a stale answer is structurally incapable of matching.

semantic fallback

No exact match? ClaudeCache embeds the prompt locally (Xenova/all-MiniLM-L6-v2, ~23MB, CPU-only) and compares it to every cached entry by cosine similarity — a rephrasing still hits above a configurable threshold, default 0.92.

never stale

Every lookup re-checks the hash of every file an entry depends on. A change — or a deletion — invalidates it on the spot, with the reason logged. Correctness always outranks a hit.

ttl + lru

Entries older than ttlHours (default 168) are swept away lazily. Past maxCacheSizeMB (default 500), least-recently-used entries are evicted first.

secrets redacted

AWS keys, GitHub/Slack tokens, private key blocks, JWTs, and generic api_key=/token= assignments are stripped before anything touches disk.

Quickstart

Sixty seconds, one command.

Everything below runs entirely on your machine — see the FAQ for exactly what that means.

$ npx claudecached init --yes
✓ .claudecache/ created, config.json written
✓ .gitignore updated
✓ registered in .mcp.json

$ npx claudecached stats
Entries: 84   Hit rate: 71.4%   Saved: $1.42

Config reference

Everything is a knob, nothing is a surprise.

Set in .claudecache/config.json, written by init.

Key	Default	Description
similarityThreshold	0.92	Minimum cosine similarity for a semantic-match hit
ttlHours	168	Entries older than this are treated as misses and removed
maxCacheSizeMB	500	Logical cache size budget before LRU eviction kicks in
evictionPolicy	"lru"	Eviction policy — LRU is the only one implemented today
pricePerMillionInputTokens	3.0	Used to estimate $ saved in `claudecache stats`
pricePerMillionOutputTokens	15.0	Same, for output tokens
verbose	false	Log every lookup's reasoning — query hash, similarity, decision

FAQ

The questions worth asking before you install a random tool.

Is my code sent anywhere?

No. The cache is a SQLite file in your project (.claudecache/cache.db). The embedding model runs locally on CPU. There's no telemetry and no network calls at runtime — the model's weights download once, the same way npm install downloads packages, and are cached locally after that.

What if a file changes between caching something and asking again?

The entry is invalidated automatically the moment any lookup touches that file — content hash mismatch or deletion, either way the stale entry is removed and the reason logged. This is tested explicitly in the project's test suite.

Can I share a warmed cache with my team?

Yes — claudecache export cache.json on one machine, claudecache import cache.json on another. Entries tied to files that don't match locally are invalidated on the next lookup automatically, so there's no risk of importing someone else's stale answers.

Does it cache things like web search results or "what's today's date"?

No — that's out of scope by design. ClaudeCache is for reasoning, code-generation, and explanation-type responses tied to your project's files, not live or time-sensitive data.