# Prompt Caching for Coding Agents, Explained

> Why Claude Code cache misses happen, what fast mode costs, and how model, effort, MCP tool and speed changes affect prompt caching, as of November 2026.

Updated November 17, 2026 (first published October 9, 2026) · by the AQ team · Canonical: https://aq.dev/guides/prompt-caching-for-coding-agents-explained/

Prompt caching lets a model provider reuse the unchanged beginning of a request, called the prefix, so a coding agent pays the cached-input rate for history it has already processed. In Claude Code, changing the model, effort level, tools, or fast/standard speed can make the next turn read part or all of the conversation uncached, with documented exceptions for some models, authentication methods and deferred tools. The cache lives with the model provider, and a miss usually means one slower, more expensive turn while the new prefix is written. A build, test suite or training run that keeps the agent waiting longer than the cache lifetime has the same effect: the next request writes the whole prefix again.

**AQ gives teams shared live coding-agent workspaces with isolated worktrees, real CLIs, and shared terminal, editor and preview access on team-controlled or AQ-managed machines.** AQ is where teams put AI agents to work in shared workspaces on the agent subscriptions they already have; the prompt cache and the bill for that usage stay between each agent and its provider. AQ does not change the provider's cache, billing, entitlement or retention rules described in this guide.

## Why coding agents depend on caching

A model API is stateless: it remembers nothing between requests, so an agent harness sends the full history on every turn, and an agent task is rarely one request. A single "fix the failing test" task might be 30 model requests; at 150,000 tokens of accumulated context, that is about 4.5 million input tokens without caching. With caching, each request bills the unchanged prefix at the cached rate and only the newly appended content at full price.

Agent sessions are cache-friendly when the conversation grows by appending to the end. The match must be exact, so one changed value early in the request can reprocess everything after it at full price. A **cache write** is the request that stores a new prefix, and some vendors charge extra for it. A **cache read**, or hit, is a later request reusing that entry at the discounted rate.

## What causes a Claude Code cache miss

Anthropic's [current Claude Code prompt-caching documentation](https://code.claude.com/docs/en/prompt-caching) orders a request into the system prompt, project context and conversation. A conversation change can leave the earlier layers cached; a system-prompt change invalidates everything after it. There is no per-file cache that can rescue the rest of an edited prefix.

- **Exact-prefix matching.** Cache hits require identical content through the cached breakpoint. On the API, entries are written at breakpoints and reads look backward for a prior write; changing tool definitions invalidates the tools, system and message layers, while a message-layer change has a smaller blast radius. The [API prompt-caching reference](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) also documents a 20-block lookback window per breakpoint and up to four explicit breakpoints.
- **Switching models.** Each model has its own cache. A `/model` switch makes the next request read the whole conversation uncached even when every byte is identical. The same applies to an `opusplan` plan-mode switch, a skill or command that selects another model for one turn, and automatic model fallback. Claude Code warns before a model switch only while the cache is warm and the new model did not produce the last response, according to the [model-switch rules](https://code.claude.com/docs/en/prompt-caching).
- **Changing effort.** On most models, each effort level has its own cache, so `/effort` causes a full read on the next request. With API-key or Claude-subscription authentication, effort changes preserve the cache by default on Fable 5.1 and later, Opus 5.5, Sonnet 5.5 and Haiku 5.5. That exception does not apply on Amazon Bedrock, Google Cloud's Agent Platform, a Claude apps gateway, a HIPAA-configured organization, or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set. These boundaries come from Anthropic's [effort-change documentation](https://code.claude.com/docs/en/prompt-caching); do not generalize them to other models or providers.
- **Changing speed.** Fast and standard modes keep separate caches. The first fast-mode request in a conversation reads the whole conversation uncached at fast-mode rates. Every later toggle rereads whatever the selected speed has not already cached, including Claude Code's automatic fallback to standard at a fast-mode rate limit and its return to fast after cooldown. Enable fast mode at a session boundary when that trade-off is appropriate; Anthropic documents lower latency at higher token prices, not better task quality. See [fast mode](https://code.claude.com/docs/en/fast-mode) and the [speed-cache rules](https://code.claude.com/docs/en/prompt-caching).
- **Connecting or removing MCP tools.** With deferred tool search, the default on supported models, Claude Code keeps the tool list from the conversation's first request. An MCP server connecting or dropping mid-session therefore leaves the cached prefix intact, and a server that connects later supplies deferred definitions on demand. With tools loaded upfront, adding a definition or intentionally removing one invalidates the cache. An unexpected server dropout keeps the old definitions and the cache; a reconnect can add `WaitForMcpServers` and cause one miss. Editing MCP config alone takes effect only after restart. The full decision table is in Anthropic's [MCP cache documentation](https://code.claude.com/docs/en/prompt-caching), and the [MCP guide](https://aq.dev/guides/mcp-servers-for-coding-agents-explained/) covers the server setup itself.
- **Plugins and deny rules have different cases.** Plugin skills, commands, agents, hooks, monitors and themes append content after the cached prefix, so enabling or disabling them preserves it. A plugin that supplies MCP servers follows the MCP rules above. With tool search active, denying an entire tool leaves the definitions unchanged and preserves the cache; without tool search, adding or removing that deny rule invalidates it. Scoped rules such as `Bash(rm *)`, and allow and ask rules, are checked when a call is attempted and leave the prefix intact, per the [plugin and permission cases](https://code.claude.com/docs/en/prompt-caching).
- **Compaction.** Compaction replaces the conversation with a summary, so the conversation cache changes by design. The system prompt and unchanged project context can stay cached. While the cache is warm, the separate summarization request can read the old prefix; after a cold resume, that request processes the history uncached. The next turn then caches the shorter summary. Running `/compact` at a natural break lets you choose when this work happens, as explained in the [compaction documentation](https://code.claude.com/docs/en/prompt-caching). For the underlying window, see [context windows for coding agents](https://aq.dev/guides/context-windows-for-coding-agents/).
- **Image and PDF removal.** When a request would exceed the applicable count or total-size limit, Claude Code removes a batch of the oldest images and PDFs. The next request reprocesses the conversation from the earliest removed item onward, so this can be a partial rather than a full miss. Batching means one slower turn per removal batch, per [Anthropic's image-removal documentation](https://code.claude.com/docs/en/prompt-caching).
- **Upgrading Claude Code.** A new version typically changes the system prompt or tool definitions, so the first conversation after an upgrade rebuilds the cache from the top. Auto-update applies the new version on the next launch rather than mid-session. Resuming an older conversation reuses only layers whose content and cache lifetime still match, according to the [upgrade and resume documentation](https://code.claude.com/docs/en/prompt-caching).
- **Gateway handling of undefined.** If a gateway forwards the markers unchanged, caching behaves as it does at the provider endpoint. If it rejects the marked request with a 400 naming `cache_control`, Claude Code retries with the marker moved to the last conversation message: the mid-conversation system block is uncached, while the conversation can stay cached. If the gateway silently strips the markers and returns success, the entire conversation bills as uncached input on every turn. Converting block-form system content to a plain string has the same effect. These behaviors are documented under [where the cache lives](https://code.claude.com/docs/en/prompt-caching).

For direct API integrations, preserved thinking adds a related constraint. On Fable 5.2, Anthropic documents the prefix check on every account: editing an earlier system prompt, tool set or message can return a 400 when later thinking blocks are replayed, rather than merely causing a cache miss. Server-side compaction and context editing have explicit handling for this case in the [preserved-thinking reference](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking).

## Fast mode: the price and the second cache

[Anthropic says](https://code.claude.com/docs/en/fast-mode) fast mode uses the same model with an API configuration that can produce up to 2.5 times as many output tokens per second, with the same quality and capabilities. That is Anthropic's latency claim, not an independent measurement of coding speed or task outcomes. Fast mode is available on Fable 5.2 and Opus 5.5; Opus 5 and Opus 4.8 are in research preview.

| Model | Standard input / output per MTok | Fast input / output per MTok | Status |
| --- | --- | --- | --- |
| Fable 5.2 | $8 / $40 | $16 / $80 | Available |
| Opus 5.5 | $4 / $20 | $8 / $40 | Available |
| Opus 5 | $5 / $25 | $10 / $50 | Research preview |
| Opus 4.8 | $5 / $25 | $10 / $50 | Research preview; removal November 30, 2026 |

These are Anthropic's current [standard and fast-mode rates](https://platform.claude.com/docs/en/about-claude/pricing), checked November 12, 2026. Prompt-caching multipliers apply on top of fast-mode prices. Anthropic's [fast-mode guide](https://code.claude.com/docs/en/fast-mode) says Opus 4.8 fast mode was deprecated on October 30, 2026 and will be removed on November 30, 2026; after removal, requests that still select Opus 4.8 with fast mode will be rejected. Switch to Opus 5.5 or turn fast mode off before that date.

On Pro, Max, Ultra, Team and Enterprise subscriptions, fast mode spends usage credits even when included plan usage remains. It is not part of the subscription allowance. Team and Enterprise organizations also need an Owner to enable it, while Console organizations need paid usage and, for Opus 5 or Opus 4.8, provisioned access. At a fast-mode rate limit, Claude Code falls back to standard speed and pricing, then returns to fast after cooldown; exhausted usage credits instead cause rejected fast requests to be retried at standard speed. Each automatic speed change is also a cache toggle, so the first fast turn and later switches can carry uncached input at the selected speed's rates. The [requirements and fallback documentation](https://code.claude.com/docs/en/fast-mode) has the account-specific details.

## Provider prices, lifetimes and defaults

The mechanisms above are Claude Code's rules, not a universal caching contract. This table keeps a small provider comparison using each vendor's current documentation, checked November 12, 2026. Prices are USD per million tokens unless stated otherwise.

| Provider and model | Ordinary input | Cached input | Writes or storage | Lifetime and minimum |
| --- | --- | --- | --- | --- |
| [Claude Sonnet 5.5](https://platform.claude.com/docs/en/about-claude/pricing) | $2 | $0.10 (0.05x) | $2.50 for 5m; $4 for 1h | 5m or 1h, refreshed by reads; 512-token minimum |
| [Claude Opus 5.5](https://platform.claude.com/docs/en/about-claude/pricing) | $4 | $0.20 (0.05x) | $5 for 5m; $8 for 1h | 5m or 1h, refreshed by reads; 512-token minimum |
| [Claude Fable 5.2](https://platform.claude.com/docs/en/about-claude/pricing) | $8 | $0.20 (0.025x) | $10 for 5m; $16 for 1h | 5m or 1h, refreshed by reads; 512-token minimum |
| [OpenAI GPT-6.1 Sol](https://platform.openai.com/docs/pricing) | $2 | $0.10 (0.05x) | $2.50 for 30m; $5 for 12h | Minimum 30m or 12h; 1,024 visible input tokens |
| [OpenAI GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5) | $5 | $0.50 (0.1x) | No cache-write charge | [24h retention](https://developers.openai.com/api/docs/guides/prompt-caching), typically around 30 minutes and up to 24 hours; minimum varies by request |
| [Gemini 3.1 Pro Preview, prompts up to 200k](https://aistudio.google.com/docs/pricing#gemini-3.1-pro-preview) | $2 | $0.20 | Explicit cache storage: $4.50 per million tokens per hour | Implicit caching is on by default; 4,096-token minimum |

Anthropic supports automatic caching through a top-level `cache_control` field and up to four explicit breakpoints on the Messages API. Claude Code manages those markers unless caching is disabled. Its [default TTL](https://code.claude.com/docs/en/prompt-caching) is one hour for the main conversation on a Claude subscription within included plan usage, and five minutes with usage credits, an API key or a cloud provider. Other request buckets default to five minutes apart from server-controlled helpers. Every cache read refreshes the applicable TTL at no charge, measured from the start of that request.

OpenAI enables caching by default on supported models. GPT-5.6 and later offer 30-minute writes at 1.25x ordinary input and 12-hour writes at 2.5x, with 0.1x reads on most models and 0.05x on GPT-6.1 Sol and Terra. Earlier models use different retention and minimum rules; the [OpenAI prompt-caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) is the source for those distinctions. GPT-6 models can preserve an earlier prefix during an effort change by appending a `configuration_update`, which is a different mechanism from Claude's model and authentication exception.

Google enables implicit caching by default on Gemini 2.5 and newer models. The current [context-caching guide](https://aistudio.google.com/docs/caching) lists 4,096 tokens for Gemini 3.1 Pro Preview and 2,048 for Gemini 2.5 Pro and Flash, and recommends similar prefixes sent close together. Explicit caching remains available for supported Gemini 3 and 2.5 models through `generateContent`, with storage billed hourly; the Interactions API and Gemini 4 models use implicit caching only.

## When a long tool run outlasts the cache

A coding agent sends nothing to the model while a tool it called is still running. When Claude Code runs `npm test`, a container build, a training job or a simulation, the conversation waits, and the cache timer keeps counting from the start of the last request that read or wrote the entry, as described in [Anthropic's prompt-caching reference](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). If the tool takes longer than the TTL, the entry has expired by the time the tool result goes back to the model. The next request then pays the write rate on the whole prefix instead of the read rate, and the requests after it read the fresh entry until the next long wait.

How often this happens depends on your tools, not on the model. On a five-minute TTL, every step that keeps the agent waiting more than about five minutes causes one rewrite; on a one-hour TTL, only steps longer than an hour do. Claude Code uses the one-hour TTL for the main conversation on a Claude subscription within included plan usage, and five minutes with usage credits, an API key or a cloud provider, per its [cache-lifetime rules](https://code.claude.com/docs/en/prompt-caching). API-key and usage-credit sessions therefore hit this with ordinary test suites and builds. To estimate it for your own work, count the tool calls in your session logs that ran longer than your TTL.

The price gap comes from Anthropic's [published rates](https://platform.claude.com/docs/en/about-claude/pricing). On Claude Opus 5.5, a 150,000-token prefix costs $0.03 to read from the cache, $0.75 to write again on the five-minute TTL ($5 per million tokens) and $1.20 on the one-hour TTL ($8 per million). That arithmetic covers the prefix only; output tokens are billed separately at the model's output rate.

### Other providers set different lifetimes

The same mechanism applies wherever a cache entry can expire during a wait; the threshold differs by provider. OpenAI's [prompt-caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) gives GPT-5.6 and later a default 30-minute minimum lifetime, refreshed to at least 30 minutes after each read, with a 12-hour option written at 2.5x the uncached input rate. For earlier OpenAI models, it says in-memory entries typically remain active for around 5 to 10 minutes of inactivity, up to one hour, and that 24-hour retention, the default for organizations without Zero Data Retention, typically keeps entries for around 30 minutes and up to 24 hours. Google's [context-caching guide](https://aistudio.google.com/docs/caching?generate-content=true) enables implicit caching by default on Gemini 2.5 and newer models and does not state how long implicit entries live; explicit caches default to a one-hour TTL that you set or update yourself, billed for the storage duration.

### Three ways to bridge the wait

- **The one-hour TTL.** Anthropic charges 2x base input for a one-hour write against 1.25x for five minutes, and its [pricing page](https://platform.claude.com/docs/en/about-claude/pricing) says a five-minute write breaks even after one cache read and a one-hour write after two. It pays when gaps between requests regularly run past five minutes and stay under an hour. Every write in the session costs more, including writes that would have been read well within five minutes. In Claude Code v2.1.242 or later, set `promptCacheTtl` to `1h` in settings or `CLAUDE_CODE_PROMPT_CACHE_TTL=1h` in the environment; `FORCE_PROMPT_CACHING_5M=1` overrides both, per the [TTL precedence rules](https://code.claude.com/docs/en/prompt-caching).
- **Tail-only compression.** Shortening only the part of the request the provider has not cached yet, such as a long tool output, reduces what a rewrite costs and leaves the cached prefix alone. Compression that edits earlier messages changes the prefix and causes the misses it was meant to avoid. It also changes what the model reads, so measure task results along with cost.
- **Keep-warm requests.** Re-sending the cached prefix with a very small output limit before the TTL runs out refreshes the entry, because every cache read resets the timer. Each ping is a billed request: a cache read plus output tokens. At the Opus 5.5 rates above, a 150,000-token prefix costs $0.03 per ping, so about 25 pings cost as much as one five-minute rewrite. Compare the ping count for your longest waits against one rewrite before turning this on.

Whichever you use, these rules hold:

- Keep the cached prefix byte-identical. Any change before the breakpoint, including a reordered tool list or a timestamp in the system prompt, turns the next request into a write.
- Count keep-warm requests as usage. They are billed as cache reads plus output tokens and counted against the limits of the account that sends them.
- Stop keep-warm at the first failed request or the first response that reports zero cached tokens. After a miss, a ping only pays to write the cache again.
- A ping refreshes the cache and nothing else. It does not improve the model's answer or the task result.
- Try the provider's own TTL setting before adding a proxy. A proxy that compresses or pings sits between your CLI and the provider with access to your requests and credentials, so review it like any other component that handles them.

### A measured example from one vendor

OptScale (Hystax), which builds an open-source caching proxy called Kompressor, published a [Terminal-Bench 2.1 comparison](https://optscale.ai/blog/claude-code-prompt-caching) on November 3, 2026: 89 tasks run with Claude Code on Opus 5.5, with and without Kompressor's tail-only compression, keep-warm pings during tool runs and a switch to one-hour entries after the first idle gap over five minutes. In their measurements, the run cost $35.35 without Kompressor and $28.30 with it, solved 89.9% and 90.6% of tasks, and lost 927K and 13K prompt tokens to cache expiry. On the 14 tasks with idle gaps longer than five minutes, cost was 34% lower.

The write-up's own breakdown limits what this shows. Four tasks account for the whole net difference. Results are paired by task, not by path: the agent did not take the same path in both runs, and on three of those four tasks the run without Kompressor took 45 to 72 steps against 19 to 26, so part of the gap may come from different paths rather than caching. Across the other 72 tasks, median cost per step rose 2%. The roughly 20% total is one benchmark run published by the tool's vendor, not a general saving.

## A reproducible Claude Code cache check

You can inspect the behavior with a fabricated repository and no credentials in its files. Use your normal Claude sign-in, and do not paste an API key or session token into the repository or a prompt. [Anthropic added](https://code.claude.com/docs/en/prompt-caching) the `Prompt cache (main)` summary in Claude Code v2.1.251 and its likely-cause text in v2.1.260; use a current release. The following setup creates harmless source, a local MCP server and a status line that prints `current_usage.cache_read_input_tokens` and `current_usage.cache_creation_input_tokens`.

```
mkdir claude-cache-lab
cd claude-cache-lab
git init
mkdir -p src .claude

python3 - <<'PY'
from pathlib import Path
Path("README.md").write_text(
    "# Cache lab\n\n" +
    "\n".join(
        f"{n}: The sample repository contains only fabricated notes for a cache check."
        for n in range(1, 241)
    ) + "\n"
)
Path("src/calc.js").write_text(
    "export function add(left, right) { return left + right; }\n"
)
PY

cat > src/fake-mcp-server.mjs <<'JS'
import readline from "node:readline";
const rl = readline.createInterface({ input: process.stdin });
rl.on("line", (line) => {
  const request = JSON.parse(line);
  if (request.id === undefined) return;
  let result = {};
  if (request.method === "initialize") {
    result = {
      protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
      capabilities: { tools: {} },
      serverInfo: { name: "cache-lab", version: "1.0.0" }
    };
  } else if (request.method === "tools/list") {
    result = { tools: [{
      name: "lab_note",
      description: "Return a harmless note for a cache check",
      inputSchema: { type: "object", properties: {}, additionalProperties: false }
    }] };
  } else if (request.method === "tools/call") {
    result = { content: [{ type: "text", text: "Fabricated MCP note" }] };
  }
  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: request.id, result }) + "\n");
});
JS

cat > .claude/statusline-usage.mjs <<'JS'
let input = "";
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", () => {
  const usage = JSON.parse(input).current_usage ?? {};
  console.log(
    "cache read " + (usage.cache_read_input_tokens ?? 0) +
    " | cache write " + (usage.cache_creation_input_tokens ?? 0)
  );
});
JS

cat > .claude/settings.json <<'JSON'
{
  "statusLine": {
    "type": "command",
    "command": "node .claude/statusline-usage.mjs"
  }
}
JSON

claude mcp add --transport stdio cache-lab -- node "$PWD/src/fake-mcp-server.mjs"
claude
```

Run two ordinary prompts first: `Read README.md and src/calc.js, then explain the function in one sentence.` followed by `Using the same files, name one input and the returned value.` Run `/usage` after each. The Session block's `Prompt cache (main)` line reports the per-session hit ratio, miss count, current warmth and, when Claude Code can identify it, the likely cause of the last miss. Record the values after every scenario below rather than expecting a particular number. The documented expectation is a guide to what changed, not output captured from this fabricated repository.

| Scenario | Action in a fresh or cleared session | Documented behavior to compare with /usage |
| --- | --- | --- |
| Normal turns | Run the two baseline prompts above within the cache TTL. | The second turn can read the unchanged prefix. Warmth depends on the TTL and request timing. |
| Model change | Warm the cache, choose another model with `/model`, send a short follow-up, then inspect `/usage`. | The next request reads the whole conversation uncached because caches are model-specific. |
| Effort change | Warm a fresh session, change level with `/effort`, send a follow-up and inspect the likely cause. | Most models reread the conversation. Fable 5.1+ and Opus/Sonnet/Haiku 5.5 preserve it only with API-key or Claude-subscription auth. |
| MCP with deferred tools | On a supported model with tool search at its default, warm a session, disable and later re-enable `cache-lab` through `/mcp`, sending a short prompt after each change. | Deferred tool search keeps the initial tool list, so these changes preserve the prefix. Repeat with upfront tools to see intentional additions or removals invalidate it. |
| Fast/standard toggle | Only with fast mode and usage credits intentionally enabled, warm a standard-mode session on Opus 5.5, run `/fast on`, send a follow-up, then run `/fast off` and send another. | The first fast request reads the whole conversation uncached at fast rates. Returning to standard reuses only what standard cached and is still warm. |

For non-interactive confirmation, [Anthropic's cache-check instructions](https://code.claude.com/docs/en/prompt-caching) use `claude -p "hello" --output-format json`. Its `usage.cache_creation.ephemeral_1h_input_tokens` and `ephemeral_5m_input_tokens` fields show which TTL the main conversation wrote. The status line above exposes the per-turn `current_usage` read and creation counts; a high read-to-creation ratio across ordinary turns indicates reuse, while repeated creation points to a changing prefix or one of the speed, model and lifetime boundaries above.

## Check a long tool run against your own cache

Run this in a scratch repository with fabricated content. Use your normal Claude sign-in, or an API key that stays in your shell environment; never paste a key or token into the repository, a prompt or a proxy. The script only sleeps, and the README pads the prefix past the caching minimum.

```
mkdir long-run-lab
cd long-run-lab
git init

python3 - <<'PY'
from pathlib import Path
Path("README.md").write_text(
    "# Long run lab\n\n" +
    "\n".join(
        f"{n}: Fabricated notes for a cache-lifetime check."
        for n in range(1, 241)
    ) + "\n"
)
Path("slow.sh").write_text('sleep "$1"\necho "slow step finished"\n')
PY

export BASH_DEFAULT_TIMEOUT_MS=900000

FORCE_PROMPT_CACHING_5M=1 claude -p "Read README.md, run bash slow.sh 30, then reply with the line it printed." \
  --output-format json --allowedTools "Read" "Bash(bash slow.sh *)" > short-5m.json

FORCE_PROMPT_CACHING_5M=1 claude -p "Read README.md, run bash slow.sh 330, then reply with the line it printed." \
  --output-format json --allowedTools "Read" "Bash(bash slow.sh *)" > long-5m.json

CLAUDE_CODE_PROMPT_CACHE_TTL=1h claude -p "Read README.md, run bash slow.sh 330, then reply with the line it printed." \
  --output-format json --allowedTools "Read" "Bash(bash slow.sh *)" > long-1h.json

for f in short-5m.json long-5m.json long-1h.json; do
  jq -c '{file: input_filename,
    cache_read: .usage.cache_read_input_tokens,
    write_5m: .usage.cache_creation.ephemeral_5m_input_tokens,
    write_1h: .usage.cache_creation.ephemeral_1h_input_tokens,
    output: .usage.output_tokens,
    cost_estimate_usd: .total_cost_usd}' "$f"
done
```

1. Create the repository with the first block. It holds only fabricated text and a script that sleeps for the number of seconds you pass.
2. Set `BASH_DEFAULT_TIMEOUT_MS` so Claude Code's two-minute default for a foreground command does not cut off the long sleep, as documented in its [environment variables](https://code.claude.com/docs/en/env-vars).
3. Run the short control: a 30-second sleep with the five-minute TTL forced.
4. Run the long version: a 330-second sleep, just over five minutes, with the same TTL.
5. Run the long version again with the one-hour TTL.
6. Print cache reads, five-minute writes, one-hour writes, output tokens and the cost estimate from each file with the `jq` loop, and write them down. Claude Code documents `total_cost_usd` as a [client-side estimate](https://code.claude.com/docs/en/headless) that can differ from your bill. For billed cost on an API key, check the provider's usage page for that key after each run; on a subscription, the estimate is an API-equivalent figure, not a charge.
7. Repeat each run two or three times. The agent can take a different number of steps from one run to the next, which changes every figure.

Compare your numbers with what Anthropic's rules predict. In the long five-minute run, the request after the sleep should write the prefix again, so five-minute writes should be higher than in the short control. In the one-hour run, that request can read the entry instead, and writes appear as one-hour tokens. This guide includes no captured output from these commands.

Sources checked November 17, 2026: Anthropic's [prompt-caching reference](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [pricing](https://platform.claude.com/docs/en/about-claude/pricing) and [Claude Code prompt-caching documentation](https://code.claude.com/docs/en/prompt-caching); OpenAI's [prompt-caching guide](https://developers.openai.com/api/docs/guides/prompt-caching); Google's [context-caching guide](https://aistudio.google.com/docs/caching?generate-content=true); and the [OptScale write-up](https://optscale.ai/blog/claude-code-prompt-caching).

## Caching, rate limits and cache scope

[Anthropic's API rate limits](https://platform.claude.com/docs/en/api/rate-limits) count ordinary input and cache-write tokens toward input tokens per minute, but exclude cache-read tokens. OpenAI's [prompt-caching FAQ](https://developers.openai.com/api/docs/guides/prompt-caching) says cached tokens still count toward its tokens-per-minute limits. On a Claude subscription, cache behavior also affects how quickly included usage is consumed, but it does not create extra allowance; [Claude Code usage limits](https://aq.dev/guides/claude-code-usage-limits-explained/) explains those windows, and [coding agent token costs](https://aq.dev/guides/coding-agent-token-costs-for-teams/) covers the budget arithmetic.

A cache is provider-side. Claude Code's effective cache scope is one machine and directory because the working directory, platform, shell, OS and memory paths enter the prefix; matching sessions in the same directory can share entries. At the API layer, caches are isolated between organizations and, on the Claude API, Claude Platform on AWS and Microsoft Foundry, between workspaces. Sharing also requires a matching model, speed and prefix. These boundaries come from the [Claude Code cache-scope documentation](https://code.claude.com/docs/en/prompt-caching) and [API storage reference](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).

## Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, on team-controlled or AQ-managed machines. Agents run as real CLIs in persistent sessions inside [isolated git worktrees](https://aq.dev/docs/workspaces/). Teammates with access can open the same live workspace, watch the terminal, use the editor and review the preview; terminal control requires the owner's approval.

Each person connects their own agent subscriptions, and AQ adds no markup to that usage. The cache stays between the CLI and its provider: AQ does not move it, extend its lifetime, combine it across organizations, change fast-mode entitlement or alter the bill. A long build or test run inside an AQ workspace follows the same TTL rules as anywhere else, so the settings in this guide apply unchanged.

On the current [AQ pricing page](https://aq.dev/pricing/), Free is for one person running agents on their own Mac with the AQ Mac app and includes no AQ credits. AQ Pro is $50 per user per month in early access (standard $200), with team-controlled or AQ-managed machines and $10 of AQ credits per seat each month. Your own Claude, OpenAI, Cursor and other agent subscriptions carry no AQ markup.

## Frequently asked questions

### Why is my Claude Code session expensive after a break?

The cached prefix may have expired. Anthropic offers five-minute and one-hour TTLs, and each cache read refreshes the timer from the start of that request. Claude Code defaults the main conversation to one hour on a Claude subscription within included plan usage, and five minutes with usage credits, an API key or a cloud provider; other request buckets generally use five minutes. The first turn after a longer gap reprocesses the conversation and writes a fresh entry. See Anthropic's [cache-lifetime rules](https://code.claude.com/docs/en/prompt-caching), current as of November 12, 2026.

Cache expiry is one of several separate costs that show up after a break. **Compaction:** if the session compacts after the gap, the summarization request reads the old history uncached, which Anthropic says is why `/compact` costs the most when you resume an old session. **Context size:** once the entry is rewritten, every later request still carries the whole history as cached input; cache reads cost less per token, not nothing, and on a subscription a long history still uses up included usage faster. **Output tokens and model price** do not change with caching: a turn on a more expensive model, or one that writes long answers, costs more for those reasons alone. One Claude Code user [wrote on X](https://x.com/frmdomi/status/2121203935767638082) that resuming a seven-hour session after four hours made every later step reread the whole history, and in an [earlier post](https://x.com/frmdomi/status/2121128441365864792) linked a used-up plan to uncompacted sessions he kept resuming; those are one person's accounts, not verified bills. The [Claude Code usage limits guide](https://aq.dev/guides/claude-code-usage-limits-explained/) covers how subscription windows are metered. Rechecked November 17, 2026.

### How often does the prompt cache expire while a tool is running?

Once for every wait longer than the cache lifetime. The cache timer counts from the start of the last request that read or wrote the entry, and the agent sends no request while a build, test suite or training run is going, so a tool run longer than the TTL makes the next request write the whole prefix again. Claude Code's main conversation uses a one-hour TTL on a Claude subscription within included plan usage and five minutes with usage credits, an API key or a cloud provider, so on the five-minute TTL any step over about five minutes counts. Counting the tool calls in your own logs that ran longer than your TTL gives the number for your work. Sources: Anthropic's [prompt-caching reference](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) and [Claude Code cache-lifetime rules](https://code.claude.com/docs/en/prompt-caching), checked November 17, 2026.

### Do other providers' prompt caches expire during long tool runs too?

Yes, whenever the wait outlasts that provider's lifetime, which differs by vendor. OpenAI documents a default 30-minute minimum for GPT-5.6 and later, refreshed after each read, with a 12-hour option; for earlier models it says in-memory entries typically last around 5 to 10 minutes of inactivity, up to one hour, and 24-hour retention typically keeps entries around 30 minutes and up to 24 hours. Google enables implicit caching by default on Gemini 2.5 and newer models without stating an implicit lifetime, and explicit caches default to a one-hour TTL you can change. Sources: [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) and [Google context caching](https://aistudio.google.com/docs/caching?generate-content=true), checked November 17, 2026.

### Does switching models or effort mid-session cost extra?

Usually yes for the next turn. Model caches are separate, and most models also separate caches by effort, so the whole conversation is read uncached once. With API-key or Claude-subscription auth, Fable 5.1 and later plus Opus, Sonnet and Haiku 5.5 preserve the cache across effort changes; other providers and configurations follow the ordinary invalidation rule. Switching back can reuse an earlier entry only if it is still within its TTL. These are Anthropic's [documented model and effort rules](https://code.claude.com/docs/en/prompt-caching).

### What does Claude Code fast mode cost, and is it included in a subscription?

Fast mode costs $16/$80 per MTok input/output on Fable 5.2, $8/$40 on Opus 5.5, and $10/$50 on Opus 5 and Opus 4.8. Standard rates are respectively $8/$40, $4/$20 and $5/$25. On subscriptions it draws usage credits even when included plan usage remains; Team and Enterprise also require Owner enablement. The first fast request in a conversation reads the full context uncached at fast rates, so enabling at a session boundary avoids carrying a long history into that charge. Sources: Anthropic's [pricing](https://platform.claude.com/docs/en/about-claude/pricing) and [fast-mode requirements](https://code.claude.com/docs/en/fast-mode), checked November 12, 2026.

### Does fast mode improve coding answers?

Anthropic says fast mode uses the same model with the same quality and capabilities, at up to 2.5 times the output-token speed and higher per-token prices. That is a vendor latency claim, not evidence of better coding outcomes. Effort is a separate control: lowering it can reduce thinking time and can reduce quality on complex tasks. See Anthropic's [fast mode versus effort comparison](https://code.claude.com/docs/en/fast-mode).

### What happens at a fast-mode rate limit or when credits run out?

At a fast-mode rate limit, Claude Code falls back to standard speed and pricing, then automatically returns to fast after cooldown. When usage credits run out, rejected fast requests are retried at standard speed and pricing. Because fast and standard have separate caches, either transition can reread whatever the selected speed has not cached. Anthropic documents the [fallback behavior](https://code.claude.com/docs/en/fast-mode). Opus 4.8 fast mode is a separate deadline: it is scheduled for removal on November 30, 2026.

### Do I need to configure prompt caching in Claude Code, Codex, or Gemini CLI?

For normal interactive use, the supported CLIs handle caching for you. Claude Code manages cache markers unless disabled, OpenAI enables prompt caching by default on supported models, and Google enables implicit caching by default on Gemini 2.5 and newer models. Direct API use differs: Anthropic's Messages API uses `cache_control`, OpenAI supports implicit and explicit breakpoints on newer models, and Google's explicit cache support depends on model and endpoint. Check the current [Claude](https://code.claude.com/docs/en/prompt-caching), [OpenAI](https://developers.openai.com/api/docs/guides/prompt-caching) and [Google](https://aistudio.google.com/docs/caching) guides for your integration.

### Does prompt caching help with rate limits and usage limits?

On Anthropic's API, cache reads do not count toward input-tokens-per-minute limits, although ordinary input and cache writes do. On OpenAI's API, cached tokens still count toward tokens-per-minute limits. A high hit rate can therefore increase Anthropic API throughput, while both providers charge less for cached input. Subscription windows are a different control: caching can reduce consumption but does not raise the plan's cap or fast-mode entitlement. Sources: [Anthropic rate limits](https://platform.claude.com/docs/en/api/rate-limits) and [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).

---

About AQ: AQ is where teams put AI agents to work on everything they do: code that lands as a reviewed pull request, bots that run the jobs that repeat, and an assistant that starts each day, all on the agents and subscriptions they already have, like Claude Code and Codex, on private cloud machines of their own or on their own Mac. Start at [aq.dev](https://aq.dev/).
