Improve your cache hit rate

A cache hit is when the model reuses a prompt prefix it has already processed instead of reprocessing it as fresh input. Anthropic bills cached reads at a fraction of the base input price: 0.1× on most models, and lower on some newer ones.

When PromptConduit flags this

PromptConduit computes cache hit rate from the token counts reported for each request:

cache hit rate = cache_read / (cache_read + cache_write + input)

The “Improve your cache hit rate” tip fires when the rate is below 40%. It needs token data, so it is evaluated only when the metric set includes a cache hit rate. Today that is the signed-in web Trends view (at least 5 prompts in the period). The editor extension’s cost panel computes the same rate per session and shows its own “Reuse context to hit the prompt cache” tip when the rate is below 40% on more than 20,000 input-side tokens and uncached input makes up at least half the cost (or the session’s model is unpriced).

Why it matters

Each request to the model resends the full context: system prompt, tool definitions, project instructions, and every prior message and tool result. Prompt caching lets the API skip reprocessing the part of that request that matches a prefix it recently saw. Matching is exact and prefix-based. A change early in the request recomputes everything after it.

That has two effects:

• Cost. A cache read is billed well below fresh input. A cache write costs more than base input (1.25× for the 5-minute cache, 2× for the 1-hour cache), so a session that keeps rewriting its cache pays a premium for nothing.
• Latency. A turn that misses the cache has to reprocess the whole context, so it is noticeably slower.

A low rate usually means one of three things: sessions are short and keep restarting cold, something mid-session keeps changing the prefix, or there are long idle gaps that let the cache expire.

What to do

Keep one session per task. Claude Code caches automatically. Starting a new session for every small step throws the warm cache away. Use claude --continue to resume the most recent session in a directory instead of starting fresh.

Settle model and effort at the start. Each model has its own cache, so switching with /model makes the next request read the whole history uncached. On most models, changing effort level does the same. Anthropic’s tip: pick both at the top of the session.

Leave MCP and plugin changes for natural breaks. When MCP tools are loaded upfront rather than deferred, connecting a server invalidates the cache. Tool definitions sit at the front of the prompt, so changing them invalidates everything after.

Compact at boundaries, not mid-task. Compaction replaces the history with a summary, which by design invalidates the conversation layer. Run /compact between tasks instead of letting auto-compaction trigger in the middle of one. If you want to abandon a path, /rewind truncates back to a prefix that is already cached. Use /clear when switching to unrelated work.

Don’t re-paste files. Point at a path or use @file once. Pasting the same large file again adds new uncached content.

Watch idle gaps. The cache expires after a period of inactivity: five minutes by default on API keys, one hour for the main conversation on a Claude subscription within plan usage. The promptCacheTtl setting lets you choose 5m or 1h. The 1-hour cache costs more to write, so it only pays off if you actually come back within the hour.

Keep heavy reading out of the main session. Delegate broad exploration to subagents so the bulk of file reads never enters the context you keep resending.

How to check it worked

Run promptconduit cost in the session. The Signals: line prints cache-hit N% using the same formula. The editor extension’s status bar and cost breakdown show it live, and the web Trends view shows it over 7, 30, or 90 days. In Claude Code itself, /usage shows a Prompt cache (main) line with the share of input served from cache, misses, and the likely cause of the last miss, on recent versions.

For a fuller walkthrough of the token fields and where they come from, see track Claude Code token usage and cost. For Cursor, see Cursor AI spend by repo and model. Extension setup is in /docs/editor-extension.