Claude Code Context Window Prompt Caching Performance Cost Management

Claude Code's Context Window: What Fills It, Caching, Compaction

Q: Hands-on: watch a session fill and recover

Measure with /context and /usage, and you will know which habit to change first.

By Shoaib HossainJuly 31, 202613 min readUpdated October 17, 2026

Every request Claude Code sends to the model carries the whole session so far: the system prompt, your CLAUDE.md files, every message, every file Claude read, and every command's output. That one fact explains why long sessions get slower, more expensive, and less precise, why a model switch costs a slow turn, and why /clear is the most underrated command. Anthropic's best-practices page calls the context window the most important resource to manage, because model performance degrades as it fills.

This guide follows Anthropic's context-window, prompt-caching, and compaction documentation. It covers what loads before you type, what each action adds, how the prompt cache works and which actions invalidate it (including a common misconception about editing CLAUDE.md), what survives compaction, and how to steer it. For the cost side, see Claude Code Costs; for keeping large repositories in check, see Claude Code in Monorepos.

What fills Claude Code's context window: startup content, then your prompts, file reads, tool output, and responses, until compaction summarizes it

What fills the context window

Before you type anything, Claude Code loads startup content. Anthropic's interactive walkthrough uses these representative figures: a system prompt of about 4,200 tokens, auto memory (MEMORY.md, the first 200 lines or 25 KB) of about 680, environment info of about 280, MCP tool names of about 120 (full schemas are deferred until needed), skill descriptions of about 450, your user CLAUDE.md of about 320, and a project CLAUDE.md of about 1,800. Your own numbers depend on your setup.

Then the session grows with:

Your prompts and Claude's replies.
File reads, which are often the largest items. A long file can cost thousands of tokens.
Path-scoped rules and nested CLAUDE.md files, which load when Claude touches matching files.
Tool output: grep results, test runs, build logs. A noisy npm test can be bigger than the code it tests.
Hook output and system reminders, such as notices that a file changed.

A subagent works in its own separate context window. It loads its own copy of the system prompt and project CLAUDE.md, does its reading there, and returns only a summary, which is why delegating wide exploration keeps the main session usable.

Quick reference

Run /context for a live breakdown by category, including which CLAUDE.md and memory files loaded, with optimisation suggestions.
Fable models, Sonnet 5 and later, Haiku 5.5, Opus 4.6 and later, and Sonnet 4.6 support a 1 million token window on eligible plans; compaction works the same way at the larger limit.
A bigger window delays the problem; it does not remove the cost and attention penalty of a cluttered context.

Remember this

Startup is a few thousand tokens; file reads and tool output are what fill the window, so they are what to manage.

How prompt caching works

Because every request resends the full context, the API caches by prefix: if the start of a request exactly matches content it recently processed, it reuses that work and bills the re-read at the cheaper cached-token rate. A change anywhere in the prefix recomputes everything after it; there is no per-file caching.

Claude Code orders each request so the parts that rarely change come first:

System prompt (core instructions and tool definitions), which changes when the set of loaded tools changes.
Project context (CLAUDE.md, auto memory, unscoped rules), which changes at session start, /clear, or /compact.
Conversation, which changes every turn but only by appending.

Cache lifetime depends on billing. On a Claude subscription within plan usage, the main conversation gets a one-hour TTL; on an API key, a cloud provider, or once you draw on usage credits, the default is five minutes. Subagents, workflows, and compaction requests default to five minutes even on a subscription. promptCacheTtl and subagentPromptCacheTtl let you choose. After a gap longer than the TTL, the next turn reprocesses everything, which is why the first message after lunch can be slow.

Prompt cache layers: changes to the system prompt invalidate everything, conversation changes only append, and some actions keep the cache

Quick reference

Check cache health with /usage: the Prompt cache line shows the hit ratio, misses, and whether the cache is warm, and names a likely cause for the last miss.
A status line script can show cache_read_input_tokens and cache_creation_input_tokens live; high creation turn after turn means something keeps changing in your prefix.
The one-hour TTL charges more for cache writes, so it only pays off when you actually take long breaks.

Remember this

Caching reuses an exact prefix; keep the front of the request stable and work within the TTL.

What invalidates the cache, and what does not

These actions make the next request miss part or all of the cache, giving one slower, more expensive turn:

Switching models. Each model has its own cache. Claude Code asks you to confirm a /model switch while the cache is warm. The opusplan setting switches models every time you enter or leave plan mode.
Changing effort level on most models (Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1 keep the cache with an API key or subscription).
Turning on fast mode, once per conversation.
Connecting or removing an MCP server when tools are loaded upfront; with tool search deferring tools (the default), mid-session connections do not disturb the cache.
Denying an entire tool, again only when tool search is off.
Compacting, by design, plus accumulating many images and upgrading Claude Code.

And a common misconception: editing CLAUDE.md mid-session does not invalidate the cache, because the edit does not apply. Your project-root and user CLAUDE.md are read once at session start and held in memory; the new version loads on the next /clear, /compact, or restart. Editing repository files, changing permission mode, switching output style, invoking skills, and /rewind also keep the cache.

Quick reference

Pick the model and effort level at the start of a session, and save /compact for natural breaks between tasks.
Path-scoped rules and nested CLAUDE.md files load on demand, so editing one before it loads does take effect.
If you change CLAUDE.md and want Claude to follow the new version, run /clear or start a new session.

Remember this

Model, effort, and tool-set changes cost a full re-read; CLAUDE.md edits are free but wait for the next /clear or restart.

Compaction: what survives and how to steer it

As you approach the limit, Claude Code compacts automatically: it summarises the conversation history and continues, so a full window does not end the session. The point where this happens depends on the model and configuration; the model-config docs list the default thresholds. What happens to each kind of content afterwards:

Re-injected from disk: the project-root CLAUDE.md and unscoped rules, auto memory, the plan file from plan mode, and a fresh git status snapshot.
Re-read: up to five files Claude read or edited, most recently modified first (a file over 5,000 tokens comes back only as a path reference).
Re-injected with caps: invoked skill bodies, up to 5,000 tokens each and 25,000 in total, oldest dropped first.
Summarised away: the conversation itself, context hooks added earlier, and path-scoped rules and nested CLAUDE.md files, which reload on demand when Claude touches matching files again.
Still running: background commands and background subagents.

You can steer it. /compact focus on the auth bug fix keeps what you choose instead of what the automatic pass guesses. /rewind lets you summarise only part of the conversation. /autocompact 500k sets how full the window gets before the automatic pass. A SessionStart hook with the compact matcher can re-add essentials after every compaction.

What survives compaction: startup content is re-injected, recent files are re-read, and path-scoped rules and hook context are summarized away

Quick reference

Compaction reads the conversation it summarises, so compacting a huge context is itself a large request; with a warm cache it costs a fraction of the context size.
If a rule must survive compaction verbatim, drop its paths: frontmatter or move it into the project-root CLAUDE.md.
Put the most important instructions near the top of a SKILL.md; truncation keeps the start.

Remember this

Compaction keeps startup files and recent reads but summarises the conversation; compact with a focus at natural breaks.

Habits that keep context useful

The pattern behind all of these is the same: every token in context is paid for on every later request and competes for the model's attention. The docs' advice when a session has gone wrong is blunt: after two failed corrections on the same issue, /clear and start again with a better prompt. A clean session with a precise prompt usually beats a long one full of failed attempts.

Searches already respect .gitignore. For committed files you never want read, such as vendored code or generated bundles, add Read deny rules such as Read(./**/vendor/**) in permissions.deny. A .claudeignore file is not read by Claude Code.

Context habits from Anthropic's best-practices and cost guides
Habit	Why it works
/clear between unrelated tasks	Stale context costs tokens on every message and distracts the model
Scope requests to files and symptoms	Unscoped "investigate X" reads hundreds of files
Delegate wide reading to subagents	Their file reads stay in their own context
Keep CLAUDE.md short; move detail into skills or path rules	Startup content loads every session; skills load on use
Filter noisy output with hooks	A hook can return only failing tests instead of the full log
Read deny rules for committed noise	Keeps vendored and generated files out of reads (.claudeignore has no effect)
Prefer CLI tools such as gh over MCP where possible	No per-tool listing in context

Quick reference

/btw answers a side question without adding it to the conversation.
/rename before /clear so you can /resume the old session if you need it.
Images are capped per request; when the cap is hit, Claude Code drops a batch of the oldest, which also invalidates part of the cache.

Remember this

Fewer, more relevant tokens: clear often, scope requests, delegate reading, and keep standing context lean.

Hands-on: watch a session fill and recover

Start a session in a real repository and run /context. Note the startup total and the largest startup item.
Ask Claude to read three large files and run the test suite. Run /context again and note which category grew most.
Run /usage and read the Prompt cache line: hit ratio and warm or cold.
Switch models with /model, accept the confirmation, send one message, and check /usage again for the miss.
Edit your project CLAUDE.md, ask Claude what a rule you changed says, then /clear and ask again.
Run /compact focus on the failing tests and /context once more.

Pass criterion: you can name what filled the window, show the cache miss from the model switch, demonstrate that the CLAUDE.md edit applied only after /clear, and explain what the compaction kept.

Quick reference

If the cache line says no prompt caching was reported, your provider or gateway may be stripping cache markers.
Repeat step 2 with a subagent doing the reading and compare the main session's growth.
Write down your startup total; if it is large, trim CLAUDE.md or MCP servers first.

Remember this

Measure with /context and /usage, and you will know which habit to change first.

Key takeaway

Claude Code resends the whole session on every request, so its context window fills with startup content (a few thousand tokens), then prompts, file reads, and tool output. Prompt caching makes that affordable by reusing an exact prefix within the cache lifetime (an hour for the main conversation on a subscription, five minutes on an API key by default); model switches, most effort changes, tool-set changes, and compaction cost a full re-read, while CLAUDE.md edits keep the cache because they wait for the next /clear, /compact, or restart.

When the window fills, compaction summarises the conversation and re-injects CLAUDE.md, memory, the plan, recent files, and skills, so steer it with /compact <focus> at natural breaks. The habits that matter most are /clear between tasks, scoped requests, subagents for wide reading, and a lean CLAUDE.md. For hooks that filter noisy output, see Claude Code Hooks.

Practice (25 min): run the six steps above in a real repository.