What does the 'Prompt cache (main)' line in Claude Code's /usage report, and how do you act on its misses?
answer
- one line in the Session block
- hit ratio, misses, warm or cold
- expected rebuild is not a fault
- main conversation only, not subagents
- likely cause names the miss
basics
~20 sClaude Code's /usage adds a Prompt cache (main) line from v2.1.251: requests, the share of input tokens served from cache, misses with tokens re-cached, expected rebuilds from compaction, and whether the cache is warm. It covers the main conversation only.
solid answer
~50 sAfter the first response, `/usage` (or `/cost`) adds `Prompt cache (main)` to the Session block (v2.1.251+): request count, the percentage of input tokens read from cache, misses with when the last happened and how many tokens were re-cached, expected rebuilds when Claude Code itself rewrote history by compaction or tool-result clearing, and warm or cold with the TTL in effect. From v2.1.260 a miss can carry a likely cause such as `tool definitions changed`. It covers the main conversation only, works on every provider because it reads the API's cache token fields, and resets on `/clear`. Act when misses keep growing: avoid mid-task `/model` switches and plan toggles under `opusplan`, keep tool definitions stable, and expect a cold rebuild after idling past the TTL. `no prompt caching reported by the API` means caching is disabled or a gateway strips the markers.
go deeper
Recall that /usage shows a Prompt cache (main) line with a hit percentage, misses and a warm or cold status, and that a higher percentage means cheaper, faster turns.
Explain each part of the line, why expected rebuilds are counted apart from misses, and why it covers the main conversation only and resets on /clear.
Diagnose from the line: map a likely cause or a miss pattern to model switches, changed tool definitions or idle gaps, and recognise when 'no prompt caching reported' is a gateway or configuration fault.
Decide what the line can and cannot tell a team: it is per session and per machine, so fleet-wide cache health needs OpenTelemetry's cache token types rather than screenshots of /usage.
## Where the line lives Claude Code's `/usage` command (aliases `/cost` and `/stats`) opens with a **Session block** of token and cost totals. From **v2.1.251**, after the main conversation's first API response, Claude Code adds one more line to that block: **`Prompt cache (main)`**. It summarises how well the session's prompt cache is working, so you no longer have to infer it from raw cache-read and cache-write token counts. A typical line, as the docs show it: ``` Prompt cache (main): 14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago) ``` ## Reading it part by part | Part | What it means | | - | - | | `14 requests` | API requests the main conversation has made this session | | `91% of input tokens from cache` | The share of input tokens served as cache reads — the session's hit ratio | | `2 misses (last … ago, … re-cached)` | Requests that re-processed content the cache already held, when the last one happened, and how many tokens they wrote back | | `1 expected rebuild` | Misses Claude Code caused on purpose by rewriting history — compaction or clearing old tool results; shown only once one has happened | | `warm (1h TTL, last activity 40s ago)` | The cached prefix is still within its lifetime, and which TTL applies; when cold, the line shows how long the session has been idle | Two more variants matter: - From **v2.1.260**, a miss can carry a **likely cause**, for example `likely cause: tool definitions changed`, when Claude Code can identify one. - When no response has reported any cache tokens, the line ends with **`no prompt caching reported by the API`** instead of warm or cold. ## What it covers — and what it does not - **Main conversation only.** Subagents run their own conversations with their own caches and are not in this line. - **Every provider and gateway.** The counts come from the cache token fields in the API's responses, so the line works on the Claude API, Bedrock, Google Cloud's Agent Platform, Foundry or behind a gateway. - **One session.** `/clear` resets it along with the rest of the Session block. A status line script can read the same numbers from the `prompt_cache` object it receives, which is how a team shows cache health continuously; rendering it is a status-line concern. ## Acting on misses A healthy line has a high cache percentage, misses that are rare, and a warm cache while you are working. The signal to act on is **misses that keep growing, or a percentage that falls turn after turn**. The usual causes and their fixes: 1. **Model switches.** Each model has its own cache, so `/model`, the plan-mode toggle under the `opusplan` setting, or a skill whose frontmatter names another `model` makes the next request read the whole history uncached. Pick the model at the start of a session. 2. **Changed tool definitions.** When tool definitions load upfront rather than deferred behind tool search, connecting or removing an MCP server, or denying a whole tool, rewrites the system-prompt layer. The likely-cause text can name this case. 3. **Idle past the TTL.** A cold line after a break means the next request rebuilt the cache from scratch. On API-key billing the main conversation's default TTL is five minutes; a longer TTL is a setting. 4. **Effort changes** on models that cache per effort level, and the first turn after turning on fast mode. An **expected rebuild** is not a fault: compaction replaces history with a summary, so the next request cannot share the old prefix. If expected rebuilds pile up, compaction or tool-result clearing is firing mid-task, and running `/compact` at natural breaks moves the compaction cost to a moment you choose. The line **`no prompt caching reported by the API`** points at configuration rather than behaviour: caching turned off with `DISABLE_PROMPT_CACHING`, or a gateway behind `ANTHROPIC_BASE_URL` that removes the cache markers Claude Code sends. ## How it relates to the raw counts The Session block's per-model row still shows `cache read` and `cache write` tokens, and a status line's `current_usage` object carries `cache_creation_input_tokens` and `cache_read_input_tokens` per turn. A high read-to-creation ratio means caching works; creation that stays high turn after turn means something in the prefix keeps changing. The `Prompt cache (main)` line is the same evidence, pre-digested into a ratio, a miss count and a warm-or-cold verdict.
- Why can the line read 91% from cache while a session's subagents are missing constantly?The line covers the main conversation only. A subagent starts its own conversation with its own system prompt and tools, so it builds a separate cache, and on a subscription its requests default to a five-minute TTL. Its misses never appear in `Prompt cache (main)`; the plan breakdown in `/usage` or OpenTelemetry's `query_source` attribute is where subagent usage shows up.
- The line shows a growing count of expected rebuilds. Is that a problem?Not a fault: an expected rebuild is a miss Claude Code caused by compacting or clearing old tool results, since a rewritten history cannot share the old prefix. Many of them usually mean compaction keeps firing in the middle of work. Running `/compact` at a natural break, or `/clear` between unrelated tasks, moves that cost to a moment you pick.
- The Prompt cache (main) line adds up cache use across all subagents too.
- An expected rebuild means something misconfigured is breaking the cache.
- The cache line only works on the Claude API, never on Bedrock or a gateway.
- A cold cache line means prompt caching is turned off for the session.
- The cache statistics keep accumulating across /clear for the whole process.
Assumes Claude Code 2.1.286; the Prompt cache (main) line requires v2.1.251 or later and its likely-cause text v2.1.260 or later.