---
title: "Prompt caching for Claude Code and Codex, in plain English"
description: "Stable context lets Claude Code and Codex reuse work. Here is what developers should keep fixed, what should stay fresh, and why correctness still wins."
date: "2026-08-08"
tags: ["prompt caching", "Claude Code", "Codex", "coding agents", "developer workflow", "context engineering", "costs", "latency", "analysis"]
canonical: "https://news.maestromojo.com/news/prompt-caching-claude-code-codex-plain-english/"
---


*Your coding agent keeps rereading the same instructions. Stable context lets the platform reuse that work. Change the beginning, and it may have to start over.*

**Maestro’s take.** The best coding-agent context is not the smallest. It is the useful part that stays stable.

*Analysis · August 8, 2026 · coding agents, prompt caching, Claude Code, Codex, developer workflow*

![An origami Maestro conducts a repeating line of folded context cards; one changed card causes the following cards to unfold and be processed again.](https://maestromojo.s3.us-west-2.amazonaws.com/fileman/dd2b61c52a194955a85e8919127dabda/site_media/prompt-caching-claude-code-codex-hero_48684172.jpg)

*Change the beginning, and the work behind it may need to happen again.*

## TL;DR

Claude Code and Codex do not send only your newest sentence to the model.

They send a package. It can include system rules, available tools, project instructions, earlier messages, file contents, and tool results.

That package grows as the agent works.

Prompt caching lets the model reuse work it already did on an identical beginning of that package. This can make repeated calls faster and cheaper.

Change something near the beginning, and the reusable part can disappear.

You do not need to become a cache engineer to use Claude Code or Codex. The products manage most of this. But your workflow can help—or make the machinery work much harder.

## Think of it as onboarding a contractor

Imagine giving a contractor the same 80-page handbook before every assignment.

Without caching, they reread all 80 pages every time.

With caching, they can say: “I already processed this exact handbook. Just give me the new task.”

Now add today’s timestamp to page one. Shuffle the rules. Swap the available tools. Change the model.

The handbook is no longer identical. Some or all of it may need to be processed again.

That is a cache miss.

It does not mean the agent forgot everything. It means the platform lost a shortcut.

![Diagram showing a cache-friendly coding-agent context: stable organization policy, project rules, tools, and workflow conventions first; task constraints, live repository state, and current tool results later.](https://maestromojo.s3.us-west-2.amazonaws.com/fileman/dd2b61c52a194955a85e8919127dabda/site_media/cache-friendly-coding-agent-context_117a8ef3.svg)

*Stable does not mean stale. Correct the rules when reality changes; keep naturally changing evidence in the live tail.*

## Why Claude Code and Codex care

[OpenAI explains](https://openai.com/index/unrolling-the-codex-agent-loop/) that Codex intentionally keeps the old prompt as an exact prefix of the new one. New messages and tool results are appended. That shape makes prompt caching possible.

OpenAI also lists changes that can cause misses in Codex: switching models, changing the tool set, or changing sandbox, approval, or working-directory configuration. Codex tries to append configuration changes instead of rewriting earlier context when it can.

[Anthropic’s API](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) uses the same basic law. The reusable beginning includes tools, system instructions, and messages in a specific order. A cached read costs 10% of ordinary input pricing on the Claude API. The first cache write costs more than ordinary input, so reuse is what makes the economics work.

Claude Code and Codex hide most of these plumbing decisions from ordinary users. If you pay through a subscription, you may not see a neat “cache saved $2.14” line. The effect may appear as latency, quota consumption, or simply a session that stays efficient as it grows.

## Six practical do-and-don't examples

### 1. Keep project rules stable

**Do not:** Turn `CLAUDE.md` or `AGENTS.md` into a live status report.

Bad:

> It is 2:17 p.m. The current branch is feature-482. Three tests are failing right now.

That sentence will expire quickly. It can also make tomorrow's agent trust yesterday's state.

**Do this:** Put durable project instructions in those files.

Good:

> Run the API tests before committing. Never edit generated migration files by hand.

Put the branch name and current failures in the task brief, work log, or a fresh tool result.

**Why:** Stable rules are easier for people and agents to reuse. Live state still reaches the agent, but it arrives in the part of the context expected to change.

These files help shape context when a session is assembled. Editing one does not guarantee that an already-running session reloads it immediately. It also does not prove an instant cache miss.

### 2. State expensive constraints before work begins

**Do not:** Reveal the dangerous part of the assignment after the agent has built the easy part.

Bad opening brief:

> Add a required `company_id` field to every customer.

Then, on turn twelve:

> This must deploy with zero downtime. The old mobile app must keep working for 30 days.

**Do this:** Put deployment, compatibility, security, data-migration, and approval constraints in the opening brief.

Better opening brief:

> Add `company_id`. Existing rows cannot break. Deploy without locking the table. Keep the old API response valid for 30 days. Show me the migration plan before editing.

**Why:** The agent can design the migration, API, tests, and rollout around reality. It avoids reversing work built on a false assumption.

The saved engineering time matters more than the saved tokens.

[Jordan Carson’s “Cacheonomics” article](https://pub.towardsai.net/harnesses-part-2-cacheonomics-af9e6b92139e) calls this the cost of a reversal. That is the stronger idea hiding beneath the token math.

Cache efficiency saves computation. Early constraints save work.

### 3. Keep one session about one coherent job

**Do not:** Turn an authentication-debugging session into a billing redesign because a related thought occurred.

Bad:

> The login fix works. While we are here, redesign subscription upgrades and compare three payment providers.

**Do this:** Keep follow-ups that serve the same objective in the same task. Start a new task when the objective materially changes.

Better:

> Finish the login regression tests here. Create a separate task brief for the subscription redesign, using the authentication decision as a linked dependency.

**Why:** An old prefix can remain cacheable while becoming irrelevant. The platform may cheaply reuse context the agent should not be thinking about.

Anthropic’s own [Claude Code guidance](https://www.anthropic.com/engineering/claude-code-best-practices) recommends clearing context between unrelated tasks.

Warm garbage is still garbage.

### 4. Load large evidence when it becomes relevant

**Do not:** Paste a 50,000-line log, the complete schema, and a repository map into the opening prompt “just in case.”

That spends context before the agent knows which evidence matters. It also buries the assignment.

**Do this:** Give the agent a durable map and a retrieval path.

Better:

> Diagnose checkout timeouts. The service map is in `docs/architecture.md`. Logs are in the `checkout-api` stream. Start with the last failed request ID. Pull the exact schema or wider time window only if the evidence points there.

**Why:** The agent knows what exists without carrying all of it on every turn. It loads the specific file or log when the investigation reaches it.

This is the middle ground between loading everything and making the agent guess blindly.

### 5. Avoid casual model and tool switching mid-job

**Do not:** Change the model, working directory, sandbox, approval policy, or tool surface mid-job merely to experiment.

Bad:

> The implementation is halfway done. Switch models and enable every connector. Maybe it will feel faster.

**Do this:** Switch when there is a measured reason: missing capability, weak quality, a security boundary, or a meaningful cost test. Keep the environment stable while comparing like with like.

For harness builders, keep tool ordering deterministic and discover specialist tools when they become relevant. Ordinary Claude Code users do not need to place API cache breakpoints or manage tool-definition caching themselves.

**Why:** OpenAI says model, tool, sandbox, approval, and working-directory changes can break Codex prompt reuse. On Anthropic’s API, tool definitions are also part of the cached prefix.

Anthropic’s [tool-caching guidance](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching) explains how an API harness can discover tools on demand and append their definitions without rewriting the prefix.

Switch when the job requires it. Do not switch because a dropdown looked lonely.

### 6. Never protect the cache from the truth

**Do not:** Keep stale instructions, a confused thread, or the wrong model merely to preserve a warm cache.

Bad:

> The production API changed, but do not refresh the docs or start a clean task. We have a good cache-hit rate.

**Do this:** Replace stale evidence. Correct wrong instructions. Start a clean task when the old context is misleading. Switch models when the work genuinely needs a different capability. Save important decisions in durable project memory.

**Why:** The cache is a speed shortcut, not a source of truth. A warm prompt that confidently describes the wrong system produces cheap mistakes.

Correctness wins. Every time.

## Cache problems and context problems are different

A cache miss means the platform must process more input again.

A context problem means the agent has the wrong information, too much irrelevant information, or an important fact arrived too late.

They often travel together. They are not the same.

Anthropic demonstrated the distinction in an [April 2026 Claude Code postmortem](https://www.anthropic.com/engineering/april-23-postmortem). A caching optimization accidentally discarded earlier reasoning on every turn after a session went idle. Users saw forgetfulness, repetition, odd tool choices, more cache misses, and faster usage-limit drain.

The lesson is not “never compact context.” Long sessions need compaction.

The lesson is that context management affects both economics and intelligence. A cheaper prompt that removes the reason behind the work can become very expensive code.

## Claude versus Codex

The principle is the same. The controls differ.

| | Claude / Anthropic | Codex / OpenAI |
|---|---|---|
| What ordinary users manage | Task shape, project instructions, sessions, tools | Task shape, `AGENTS.md`, sessions, tools |
| What the product manages | Claude Code’s context and caching behavior | Codex’s agent loop, context, and caching behavior |
| What API builders can inspect | Cache creation and cache-read tokens | Cached tokens and, on GPT-5.6, cache-write tokens |
| Important current detail | Claude API offers automatic or explicit caching with short and one-hour lifetimes | Recent OpenAI models cache automatically; GPT-5.6 also supports explicit breakpoints |

Do not choose Claude Code or Codex from this table alone. Cache design is one part of a much larger product.

But if you build your own harness, this table becomes architecture.

## Why Maestro users should care

Coding agents are becoming fleets.

One agent scopes. Another implements. Another tests. Another reviews.

If every agent receives a different wall of duplicated instructions, tools, timestamps, and workspace state, the fleet repeatedly pays to reconstruct the same world.

The smarter pattern is layered context:

1. stable organization and project rules;
2. a precise task brief and approval boundary;
3. live files, logs, and tool results appended as the work unfolds;
4. durable memory for decisions that must survive the session.

The cache rewards that structure. More importantly, the agents understand it.

## One thing to try

Open one of your project instruction files.

Label every line either **durable rule** or **live state**.

Move the live state out.

Then check whether the remaining rules are short enough to understand, complete enough to prevent an expensive reversal, and stable enough to reuse across many tasks.

That is cacheonomics without the economics degree.

## Sources considered

- Jordan Carson, [“Harnesses, Part 2: Cacheonomics”](https://pub.towardsai.net/harnesses-part-2-cacheonomics-af9e6b92139e), published August 5, 2026. Secondary analysis that inspired the question; its harness estimates are not treated as audited benchmarks.
- OpenAI, [“Unrolling the Codex agent loop”](https://openai.com/index/unrolling-the-codex-agent-loop/).
- OpenAI, [Prompt caching documentation](https://developers.openai.com/api/docs/guides/prompt-caching).
- Anthropic, [Prompt caching documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
- Anthropic, [Tool use with prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching).
- Anthropic, [Claude Code best practices](https://www.anthropic.com/engineering/claude-code-best-practices).
- Anthropic, [“An update on recent Claude Code quality reports”](https://www.anthropic.com/engineering/april-23-postmortem).

*Maestro’s analysis and summaries are AI-generated. A separate AI editor reviewed this draft for evidence, scope, and internal residue. Cite the linked primary sources for product behavior and Maestro Brief for this analysis.*