Prompt Caching in Coding Agents: How Claude Code, Codex CLI, OpenCode and Pi Keep the Prefix Stable

Published 27 October 2026. Facts checked 27 October 2026: we re-read every provider's documentation and prices and the Claude Code documentation that day, and code claims link to harness source at the commits we read on 17 October 2026.

A coding agent sends its entire context again on every request, so prompt caching decides most of what a session costs: in the worked example below, a 60-request session on Claude Sonnet 5.5 costs $12.99 with no caching and $1.31 when every request hits the cache. Providers match the cache on an exact prefix, which gives the harness one job, keeping the start of each request byte-identical for as long as the session lasts, and the harnesses do that job in visibly different ways. Claude Code layers its prompt from the most stable content to the least and delivers every later change as a message at the end. Codex CLI sets no breakpoints at all and relies on a session-scoped prompt_cache_key. OpenCode replaced its "first two system messages, last two messages" scheme on its dev branch with a four-breakpoint policy that marks the last tool, both ends of the system prompt and the newest message. Pi marks the system prompt, the last tool and the last user-role message, and freezes its tool list so that tool changes never touch the cached prefix.

Arpit Bhayani's summary of three of these harnesses, posted on X in mid-October 2026, states the principle correctly: static content first, volatile content last, and a stable key per session. The provider APIs enforce that order: on the Claude API a changed tool definition invalidates the whole request, and a timestamp in the system prompt makes every request pay the write price. The provider rules below come from each provider's documentation, re-checked on 27 October 2026, and the harness behaviour from the repositories themselves, cloned on 17 October 2026.

The cache matches an exact prefix, so the order of the prompt decides what gets reused

A model holds nothing between calls, so a coding agent rebuilds the full request every turn: system prompt, tool definitions, project files such as CLAUDE.md, every earlier message and tool result, and the new instruction. Claude Code's documentation puts the consequence plainly: the API "caches by matching the start of each request, called the prefix", the match "is exact, so a change anywhere in the prefix recomputes everything after it", and "there is no per-file or per-segment caching."

On the Claude API the order of the three parts is fixed by the API itself, tools first, then system, then messages, and a change at one level invalidates that level and everything after it. Changing a tool definition invalidates everything. Turning web search, citations or fast mode on or off invalidates the system prompt and the messages. Changing tool_choice or adding or removing images invalidates only the messages. Changing the thinking or effort settings always invalidates the messages, and on some models the tools and system prompt too. A harness cannot reorder those levels; what it controls is what goes inside each one and where it places its breakpoints.

A breakpoint is a cache_control marker on a content block. You can set up to four per request, or set one top-level cache_control and let the API place the breakpoint on the last cacheable block and move it forward as the conversation grows. Each breakpoint looks back at most 20 blocks for an entry an earlier request already wrote. On the Claude API a run of consecutive tool_use blocks counts as one position, and so does a run of consecutive tool_result blocks, so a turn with many parallel tool calls does not push the previous entry out of the window on its own; a route that does not group them that way can still miss a cache that exists. The minimum cacheable prompt is 512 tokens on Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1, and up to 4,096 tokens on some older models; a shorter prompt is silently not cached, with no error.

Other providers cache implicitly, with no breakpoints in the request. OpenAI caches implicitly from 1,024 tokens on GPT-5.6 and later, and GPT-5.6 also added optional explicit breakpoints. Gemini caches implicitly on 2.5 and newer models and passes on the cost saving automatically when a request hits the cache, and offers explicit cached content on supported Gemini 3 and 2.5 models through the generateContent API. DeepSeek caches on disk automatically on a best-effort basis. All of them still match on the prefix, so the ordering rule holds everywhere; what changes is whether the harness writes breakpoints, sends a cache key, or does neither.

A high cache hit rate also raises your effective rate limit, because cache reads do not count toward input-tokens-per-minute limits on most current Claude models, while cache writes do. Caches also never cross organisations: Anthropic isolates them per workspace on the Claude API and per organisation on Bedrock and Google Cloud, and OpenAI does not share them across organisations.

Caching takes a modelled 60-request Sonnet 5.5 session from $12.99 to $1.31, and a broken cache costs $16.18

The example uses Claude Sonnet 5.5 list prices as of 27 October 2026, unchanged since the draft was first written: $2 per million input tokens, $10 output, $2.50 for a five-minute cache write, $4 for a one-hour write and $0.10 for a cache read. The session starts with a 30,000-token prefix (system prompt, tool definitions and project instructions), adds 2,500 input tokens per request (tool results, the previous reply and the next instruction), writes 400 output tokens per request, and runs for 60 requests, ending at 180,000 tokens of context. Output is $0.24 of every total below; the rest is input.

Caching cut the session by 90%. The timestamp row is the expensive one: when the prefix changes on every request, each request pays the 1.25x write price on its whole input and never reads anything back, so the session spends 25% more on input than it would with caching switched off. On OpenAI's GPT-5.6 and later, which also bill cache writes at 1.25x for the default 30-minute cache lifetime, a cache key that changes on every request has the same effect.

The table also explains why a one-line question late in a long session is not cheap. At 180,000 tokens of context, "what does this function return?" still sends 180,000 tokens: about $0.018 when the prefix is cached and $0.36 when it is not, before a single output token.

Anything that edits the prefix breaks the cache; anything appended at the end keeps it

Each of these actions costs one slow, fully billed request, according to Claude Code's documentation; most of them apply to any harness running on Claude:

• A model switch re-reads the whole conversation uncached, because "each model has its own cache"; with the opusplan setting, every plan-mode toggle is a model switch.
• An effort change misses on most models, since each effort level has its own cache; on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 with an API key or subscription, the cache now survives it.
• Turning on fast mode adds a request header that is part of the cache key, so the first fast request in a conversation misses.
• Adding or removing tools invalidates everything only when tool search is off; with tool search on, the default on supported models, Claude Code keeps the first request's tool list for the whole conversation and loads new MCP tools as deferred definitions. The same applies to a bare-name deny rule such as Bash.
• Compacting and dropping old images rewrite the history, and upgrading Claude Code usually changes the system prompt or tool definitions.

Every action that keeps the cache appends to the end of the request and leaves the prefix alone. Editing CLAUDE.md mid-session keeps the cache because Claude Code read the file once at startup, which also means the edit does not apply until /clear, /compact or a restart. Plan mode keeps it because, as Thariq Shihipar's post on the Claude Code team's caching lessons explains, Claude Code keeps every tool in the request and models entering and leaving plan mode as tools themselves. Skills, permission changes, output-style changes, /recap, /rewind and spawning a subagent all keep it too.

The bugs Anthropic has fixed in its own changelog are the best guide to what breaks a harness you write yourself: a date in the system prompt, tool order shuffled between requests, dynamic text inside tool descriptions, tool schemas re-rendered after an OAuth token refresh roughly once an hour, and a memory file's "age" note that changed between requests. Thariq's post lists one more: changing which agents the Agent tool is allowed to call. A gateway is the other trap: one that strips the cache_control breakpoints while still returning success makes "your entire conversation history bill as uncached input on every turn," in the documentation's words.

Tool changes and cache expiry together cause under a fifth of misses in measured sessions. Mohammed Reschreiter's audit of 93 Pi sessions and 10,186 assistant turns, published 30 August 2026, found an 80.08% overall hit rate and attributed 70.05% of misses to large file reads and context compaction, against 17.44% for tool activation and cache expiry combined. Most uncached tokens in a coding session are new content entering the context, which no cache can discount, so the misses worth chasing are the prefix changes.

Measure the hit rate from the usage object: cache writes that stay high every turn mean the top of the prompt is changing

Every provider reports cache tokens in its usage object, and the ratio of read tokens to total input tokens is the number to watch.

On Anthropic, input_tokens counts only the tokens after the last breakpoint, so total input is read plus creation plus input. If creation stays high turn after turn, something near the top of the prompt is changing. In Claude Code, /usage shows a "Prompt cache (main)" line with the session's hit ratio, miss count and whether the cache is warm (v2.1.251 and later), and from v2.1.260 it names the likely cause of the last miss, such as "likely cause: tool definitions changed". Pi shows cache reads and writes in its footer and its /session view, and the OpenTelemetry exporters in Claude Code and Codex CLI report the same numbers per user and session.

Published hit rates give a rough baseline. Requesty's April 2026 data (updated 16 May 2026), measured as cached tokens over input tokens with no sample size or method published, shows Claude Code at 92%, OpenCode at 89%, Aider at 84% and Cline at 61%. Galileo's May 2026 analysis of 167 agent sessions from one machine measured Claude Code at 92.7% across 17 sessions and Codex at 89.6% across 37. Anthropic publishes no figure of its own; the Claude Code team alerts on its prompt cache hit rate and treats cache breaks as incidents, because, as Thariq writes, "a few percentage points of cache miss rate can dramatically affect cost and latency."

Claude Code, Aider, Roo Code and Goose write breakpoints; Codex CLI and Gemini CLI rely on a cache key; OpenCode, Pi and Cline do both

At the commits listed in the sources, the harnesses split three ways. Claude Code, Aider, Roo Code and Goose write explicit breakpoints and send no cache key. Codex CLI and Gemini CLI write none. They leave the provider to cache implicitly and send the session ID as a cache key, which the provider uses to route each request to the machine that already holds its prefix (session affinity). OpenCode, Pi and Cline write breakpoints on Anthropic-style routes and send the session ID as a cache key on the others.

Claude Code. Claude Code layers its prompt from static to volatile and sends every later change as a message; its source is closed, so the evidence is Anthropic's documentation and Thariq's post of 30 April 2026, titled "Prompt caching is everything". The documentation lists three layers: the system prompt with tool definitions, then project context such as CLAUDE.md and auto memory, then the conversation. Thariq's post describes the design intent of caching the static system prompt globally, CLAUDE.md within a project and session context within a session. Anything that changes later, such as a file edited outside the agent, arrives as a <system-reminder> in the next user message or tool result, never as an edit to the system prompt. The system prompt embeds auto-memory paths and the conversation opens with the working directory, platform, shell and OS, so the cache is effectively scoped to one machine and one directory: parallel sessions in the same directory share it, and sequential ones share it only when the git status snapshot at startup matches.

OpenCode. The "first two system messages and last two non-system messages" description is accurate for the v1 line: applyCaching in provider/transform.ts takes system.slice(0, 2) and the last two other messages, runs only for Anthropic-family and Alibaba models, and leaves tools unmarked. The dev branch no longer has that function. Caching moved into a new packages/ai/src/cache-policy.ts whose default places breakpoints "at the last tool definition, the first and last distinct system parts, and the conversation tail", capped at four. Breakpoints go only to routes on an allowlist such as Anthropic, Bedrock, Vertex and OpenRouter's anthropic/* models; OpenAI and Gemini routes get none, and a code comment notes that on Gemini a moving tail breakpoint "writes a new cache every step and costs more than none." The session affinity code sends the parent session's ID as the cache key, so subagents and forks route to the same cache as their parent.

Pi. The Anthropic provider marks the system prompt, the last tool, and the last message when its role is user or system. That last message often holds tool results, so "last user message" means the last user-role block, not the last thing you typed. With a Claude subscription token Pi sends two marked system blocks, which brings it to four breakpoints. Tools added mid-session arrive as tool_addition and tool_removal blocks inside a system message, so, in the code's words, "the cached prefix survives every tool change." The system prompt carries the working directory and no date. Pi's compaction calls run with caching turned off, because a summary is read once and a cache write on it would be wasted.

Codex CLI. There is no cache_control anywhere in the Rust code. The prompt_cache_key function returns an override if one is set, otherwise "{source}:{parent_thread_id}" for internal subagents, otherwise the session ID, and root agents send the same value as a session_id header. Context such as the environment, AGENTS.md and permissions is held as snapshotted sections; later turns append only what changed. The date is day-level and sits in a user-role <environment_context> item, and tools inside a namespace are sorted by name so their order never shuffles.

Aider, Cline, Roo Code, Goose and Gemini CLI. Aider caches only when you pass --cache-prompts, and then places up to three breakpoints on its fixed message order: system and examples, read-only files and repo map, history and chat files. Cline's current SDK marks the last user message and adds a top-level cache_control on Anthropic routes. Roo Code marks the system prompt and the last two user messages, so the newest one is written while the one before it is read. Goose marks the system prompt, the last tool and the last two user messages, and on OpenRouter, LiteLLM and Databricks it adds a second breakpoint roughly 20 blocks back so the next request stays inside Anthropic's 20-block lookback after a burst of parallel tool calls on routes that may not group consecutive tool blocks the way the Claude API does. Gemini CLI sends no breakpoints and moves the date, OS and directory tree out of the system instruction and into the first user message.

None of these harnesses needs configuration to cache on Claude except Aider, which caches only with --cache-prompts.

Compaction and forks reuse a cache that is already warm; subagents start cold

Compaction is designed to reuse the cache it is about to discard. Claude Code builds the summary request from "the same system prompt, tools, and history as your conversation, plus a summarization instruction appended as a final user message", so while the cache is warm, a /compact on a large context "costs a fraction of what the context size suggests". OpenCode's dev branch does the same, and its tests assert that the compaction request is a byte-prefix extension of the normal request. When Codex CLI's compaction itself overflows, it trims the oldest item, with the comment "Trim from the beginning to preserve cache (prefix-based)". The expensive case is compacting after the cache has expired, because the summary request then reads the whole history uncached; Claude Code v2.1.299 added idle compaction, which compacts a 200,000-token conversation left idle for about 54 minutes, just before its one-hour cache would expire.

Subagents start cold. A Claude Code subagent "starts its own conversation with its own system prompt and tool set", so its first request cannot read the parent's cache; it warms its own and leaves the parent's untouched. A fork is different: it "inherits the parent's system prompt, tools, and conversation history exactly", so its first request reads the parent's cache, and forking became the default subagent mode in v2.1.232. On implicit-cache providers the same idea shows up as key sharing: Codex CLI keys internal subagents on the parent thread, and OpenCode's dev branch keys subagents on the parent session, so both route subagent requests to the machine that already holds the parent's prefix.

Thariq's post also gives the reason to delegate to a cheaper model through a subagent instead of switching the main session. Because caches are per model, moving a 100,000-token Opus conversation to Haiku for one quick answer means writing 100,000 tokens into a fresh Haiku cache, which can cost more than letting Opus answer from its warm cache; a subagent with a short hand-off message pays only for the hand-off.

The one-hour cache pays for itself once the context at your 5-to-60-minute pauses adds up to 62.5% of what you write to cache

A one-hour write costs 2x the input price against 1.25x for five minutes, and reads cost the same either way. On Claude Sonnet 5.5 that makes the extra cost of the hour $1.50 per million tokens written, and the saving from each pause between five and sixty minutes $2.40 per million tokens of context at the moment of the pause, because a five-minute cache has to rewrite that context and a one-hour cache reads it. Dividing the $1.50 extra cost by the $2.40 saving gives 62.5%, and that becomes a rule you can apply without a spreadsheet: the one-hour cache pays for itself once the context sizes at your 5-to-60-minute pauses add up to more than about 62.5% of all the tokens the session writes to cache. The ratio is 62.5% on Opus 5.5 and Sonnet 5.5, 61.2% on Fable 5.1, and 65.2% on Sonnet 5 and Haiku 5.5.

The example session writes 180,000 tokens to cache in total, so a single pause pays for the hour once the context at that point passes 112,500 tokens. A 20-minute pause before request 41, with about 130,000 tokens cached, makes the hour cheaper ($1.58 against $1.62); the same pause before request 20, with about 77,500 tokens cached, makes the five-minute cache cheaper ($1.50 against $1.58). Short bursts with no breaks should stay on five minutes. Long sessions with pauses of 5 to 60 minutes, such as stopping to review a diff, should use the hour.

Claude Code's defaults follow the same reasoning. On a Claude subscription within plan usage the main conversation gets one hour and subagents get five minutes; on an API key or a cloud provider everything gets five minutes, which you change with the promptCacheTtl setting or CLAUDE_CODE_PROMPT_CACHE_TTL (main conversation) and subagentPromptCacheTtl or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL (everything else), on v2.1.242 or later. Jarred Sumner of Anthropic told The Register in April that "a meaningful share of Claude Code's requests are one-shot calls where the cached context is used once and not revisited", which is the case the five-minute default exists for. Pi and Goose offer the hour as an opt-in. Aider keeps the five-minute cache alive instead: --cache-keepalive-pings N resends the cached prefix with max_tokens=1 every 295 seconds, up to N times after each message; each ping costs the read price and keeps the cache alive five more minutes.

On implicit-cache providers, a stable cache key routes requests back to their cache

On providers that cache implicitly, the cache key helps decide which machine serves the request, and only that machine holds your prefix. OpenAI routes each request by "a hash of the initial tokens" of the prompt, tool definitions included, and prompt_cache_key adds your value to that routing decision, which raises the chance that consecutive requests from one session land on the machine holding their prefix. OpenAI's prompt caching guide warns that the key influences routing but does not guarantee a hit, and that traffic above about 15 requests per minute can overflow to other machines; its target is about 15 requests per minute per key, across all prefixes using it. Every harness that sets a key uses the session ID, and OpenCode and Pi clamp it to 64 characters. On GPT-5.6 and later, where cache writes cost 1.25x at the default 30-minute lifetime, a key that changes on every request makes every request a write, the OpenAI version of the $16.18 row above.

The TTL on OpenAI depends on the model. On GPT-5.6 and later a cached prefix stays eligible for at least 30 minutes after its last use by default, and in the Responses API prompt_cache_options.ttl can raise that minimum to 12 hours, with cache writes billed at 2.5x the input price instead of 1.25x. Earlier models set the TTL through prompt_cache_retention: in_memory lasts roughly five to ten minutes idle and at most an hour, while 24h can keep a prefix for up to a day and is the default for organisations without zero data retention. xAI uses an x-grok-conv-id header for the same purpose and warns that "any edit, removal, or reorder breaks the cache." When you run Claude Code through a load balancer with several deployments, the cache lives on one deployment, so a router that spreads requests evenly misses it; LiteLLM's prompt caching check routes each request to the deployment that wrote its cache.

Rules for a harness that keeps its cache: append every change and edit nothing cached

Each rule comes from the harness code, documentation and changelog fixes described above.

1. Put content that never changes first, per-project content next and the conversation last.
2. Keep dates, usernames, git status and other dynamic text out of the system prompt; Gemini CLI and Codex CLI put them in the first user message.
3. Deliver every later change as an appended message, the way Claude Code's <system-reminder> and OpenCode's "Today's date is now" messages work, and never edit text that is already cached.
4. Fix the tool list at the start of the session, sort it deterministically as Codex CLI does, and add tools later through deferred loading or appended definitions, as Claude Code and Pi do.
5. Use one model per session, and send work for a cheaper model to a subagent with a short hand-off.
6. Build compaction requests on the parent's exact prefix, so the summary reads the cache before the history is replaced.
7. Send a stable cache key, such as the session ID, to implicit-cache providers, and give subagents the parent's key, as Codex CLI and OpenCode do.
8. On routes that may not group parallel tool calls into one lookback position, such as some proxies, place a second breakpoint about 20 blocks behind the tail, as Goose does.
9. Log cache read and write tokens on every request and alert when the ratio drops, because a cache miss returns no error and shows up only in the bill.
10. Pick the TTL with the 62.5% test: one hour when long pauses are routine, five minutes for short bursts and subagents, set in Claude Code with promptCacheTtl and subagentPromptCacheTtl.

Per-user memory belongs after the cached prefix, never in the system prompt

An agent product built on one of these harnesses adds something the coding tools do not: facts about the person using it, such as their plan or the bug they reported last week. The caching rules decide where that memory belongs. Per-user memory changes from user to user and often from turn to turn, so splicing it into the system prompt breaks the cache for everyone on every request; placed after the cached prefix, in the latest user message or an appended context block, it costs only its own tokens.

Caching also has a limit that memory does not. A prompt cache lasts five minutes or an hour on Claude and between 30 minutes and a day on OpenAI, depending on the model, so it discounts a conversation while it is running and holds nothing once the user returns tomorrow. Maximem Synap is a memory layer that keeps those facts between sessions: the application sends Synap its conversations as they happen, and before replying it asks for a short, ranked set of facts about the person, ready to drop into the prompt after the cached prefix. The prefix stays stable and cached, and the memory block stays small whatever the length of the user's history. The full cost picture of caching against bounded context in long conversations is in our guide to reducing token costs in long conversations.

Frequently asked questions

How does Claude Code use prompt caching?

Claude Code orders every request from the most stable content to the least: the system prompt and tool definitions first, then project context such as CLAUDE.md and auto memory, then the conversation. Changes during the session arrive as <system-reminder> messages at the end, so the cached prefix stays intact. The main conversation gets a one-hour cache on a Claude subscription within plan usage and five minutes otherwise; /usage shows the session's hit ratio and the likely cause of the last miss.

What breaks the prompt cache in Claude Code?

These actions break it: switching models, changing effort on older models, turning on fast mode, connecting or removing MCP tools or denying a whole tool when tool search is off, compacting, dropping old images and upgrading Claude Code. Editing CLAUDE.md, entering plan mode, invoking skills, changing permission mode, /rewind and spawning a subagent all keep the cache.

Does OpenCode still cache the first two system messages and the last two messages?

It does only on its v1 line, where applyCaching in provider/transform.ts still does this at tag v1.19.3 (16 October 2026). The dev branch replaced it with a cache policy that marks the last tool definition, the first and last system parts and the newest message, capped at four breakpoints, and sends the parent session ID as the cache key.

Does Codex CLI use cache_control breakpoints?

No. Codex CLI relies on OpenAI's implicit prefix caching and sets prompt_cache_key to the session ID, or to {source}:{parent_thread_id} for internal subagents, and root agents send the same value as a session_id header. It keeps the prefix stable by snapshotting context sections and appending only the changes.

Should I use the 5-minute or the 1-hour cache?

Use the hour when the context sizes at your pauses of 5 to 60 minutes add up to more than about 62.5% of the tokens the session writes to cache, which is typical of long sessions with breaks to review work. Stay on five minutes for short bursts and for subagents, whose context is usually used once.

Can prompt caching cost more than no caching?

Yes. Each cache write costs 1.25x the input price on Claude's five-minute cache and on OpenAI's GPT-5.6 and later at the default 30-minute lifetime, so if the prefix changes on every request (or, on OpenAI, the cache key), every request pays the write price and never reads anything back. In the worked example, a timestamp in the system prompt made the session's input 25% more expensive than running with no caching at all.

Do subagents share the parent's prompt cache?

A Claude Code subagent has its own system prompt and tools, so it builds its own cache and starts cold; a fork inherits the parent's exact prefix and reads the parent's cache. On OpenAI, Codex CLI and OpenCode give subagents the parent's cache key so their requests route to the same cache.

Do cache reads count against Claude rate limits?

Not on most current Claude models: cache reads are excluded from input-tokens-per-minute limits, while cache writes count. Haiku 3.5 is the exception and counts reads too.

Sources

We read the harness repositories at the commits below on 17 October 2026, and re-checked every provider page, the Claude Code documentation and changelog, and every price on 27 October 2026. Third-party analyses (Requesty, Galileo, Reschreiter, The Register, Thariq Shihipar's post) were also re-read on 27 October 2026.

• How Claude Code uses prompt caching, Claude Code docs and environment variables reference
• Lessons from building Claude Code: Prompt caching is everything, Thariq Shihipar, Anthropic, 30 April 2026
• Claude Code changelog
• Prompt caching, Claude API docs, pricing and rate limits
• Prompt caching guide, OpenAI
• Context caching, Gemini API
• KV cache, DeepSeek API docs
• Prompt caching, Amazon Bedrock user guide
• Prompt caching best practices, xAI docs
• OpenCode source: dev at 8c173a8 and v1.19.3 at e3c4eb2
• Pi source at 8efd314
• Codex CLI source at ce0323f
• Aider source at 5dc9490
• Cline source at a42df8c
• Roo Code source at b867ec9
• Goose source at bfcc6ee
• Gemini CLI source at ed96fae
• Does dynamic tool activation break prompt caching?, Mohammed Reschreiter, 30 August 2026
• Coding agent cache hit rate, April 2026, Requesty
• The 2026 caching playbook for agents, Paul Lacey, Galileo, 26 May 2026
• Claude Code cache confusion, Tim Anderson, The Register, 13 April 2026
• Claude Code prompt cache routing, LiteLLM docs