The context window is all the text the model can see at one time. It is the model’s only working memory: whatever is not in it, the model does not know. Managing it is the most important skill when working with a coding agent.
How it works
The model itself remembers nothing between calls. The Claude Messages API is stateless: every request carries the full conversation history, and the model reads all of it again before it answers. A “conversation” is just that history growing longer with each turn. Re-sending everything would be slow and expensive, which is why Claude Code relies on prompt caching.
A chat lives inside one conversation; an agent lives inside one session. Each new Claude Code session starts with a fresh context window, without the history of earlier sessions.
What is in it before you type
Before your first message, a Claude Code session already holds:
- the system prompt: Claude Code’s own instructions and the tool definitions;
- environment info: working directory, platform, shell, and a git status snapshot;
- your CLAUDE.md files (user-level and project) and auto memory (the first 200 lines or 25 KB of
MEMORY.md); - MCP tool names (by default the full tool schemas stay deferred and load on demand) and the short descriptions of your skills.
Your first prompt is a small addition on top of all that.
What gets added while you work
- Every file the agent reads. This is usually the biggest consumer. In the terminal you see a one-line
Read auth.ts, but the whole file went into the context. - Command output: test runs, grep results, logs.
- The model’s own replies.
In a chat, the context grows by what you and the model type. In an agent, it also grows by everything the agentic loop touches: one sentence from you can turn into five file reads and a page of test logs. A single debugging session can use tens of thousands of tokens.
Why quality drops
- Attention is a budget. Anthropic describes context as a finite resource with diminishing returns: the more tokens there are, the worse the model gets at recalling any one of them. This is often called context rot. Quality drops well before the window is full.
- Leftovers compete. Files, logs and discussion from an earlier task stay in the window and compete with what the current task needs. The model starts to miss details, mixes old and new information, and fills gaps with made-up answers (hallucinations).
- Compaction loses detail. When the window gets close to its limit, Claude Code first clears older tool outputs, then summarizes the conversation (auto-compaction). The session keeps going, but full logs and intermediate reasoning are gone.
- A bigger window only delays it. Some models support a 1 million token window (a
[1m]model variant). Compaction works the same way at the larger limit.
What survives compaction
After compaction, the conversation is replaced by a structured summary, and Claude Code reloads what it can from disk:
- the system prompt and output style still apply;
- the project-root CLAUDE.md, unscoped rules and auto memory are re-injected from disk, so rules kept there survive;
- up to five of the files Claude read or edited are re-read, most recently modified first (a file over 5,000 tokens comes back only as a path reference);
- invoked skills are re-injected, up to 5,000 tokens each and 25,000 tokens in total.
Everything else, including detailed instructions you typed early in the conversation, survives only as far as the summary kept it. That is where “but we agreed on this twenty minutes ago” comes from.
What to do about it
- Run
/contextto see what is using space: a coloured grid by category, with suggestions for heavy tools, memory bloat and capacity warnings. - Put rules that must stick in CLAUDE.md, not in early chat messages.
- Clear between unrelated tasks with
/clear, and compact on purpose with/compactat a break.
The full set of habits is in Managing context, and the session-level rule is One task per session.
Related
- Prompt caching: how re-sending the whole context every turn stays cheap.
- Agentic loop: where the tool results that fill the window come from.
- Managing context: practical habits to keep the window lean.
- Statusline: keep the context percentage on screen.
- Coding agent vs chat assistant: the limits both share.
- Hallucinations: what the model does when the details it needs are gone.