skip to content

What does the 'Prompt cache (main)' line in Claude Code's /usage report, and how do you act on its misses?

level: middleimportance: should knowfreq 8%

answer

  1. one line in the Session block
  2. hit ratio, misses, warm or cold
  3. expected rebuild is not a fault
  4. main conversation only, not subagents
  5. likely cause names the miss

basics

~20 s

Claude 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 s

After 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.