The Claude Code context window is everything the model sees on a given turn: the system prompt, tool names, your CLAUDE.md, every message, every file Claude read and every command output in the session. To manage it, check what is in it with /context, compact long sessions with /compact (or let auto-compact do it), start unrelated work with /clear, keep CLAUDE.md short, and send heavy investigation to subagents so only their summary comes back. The rest of this guide shows how each of these works and when to reach for it.
What fills the context window
A context window is measured in tokens, and in Claude Code it fills from two directions: what loads before you type anything, and what the session piles up as it works.
Loaded at startup
According to Claude Code’s documentation, these are in the context before your first prompt:
- The system prompt and the built-in tools.
- CLAUDE.md files (project, user and any parent folders) and auto memory. AGENTS.md can load in place of CLAUDE.md.
- MCP tool names and server instructions. Full tool definitions are deferred by default and load when a tool is used.
- Skill descriptions. The body of a skill only loads when it is invoked.
We measured this baseline in our token usage post: about 34.4k tokens on the first request with a standard setup, down to about 13.3k with a lean one. That baseline is re-sent on every turn.
Added during the session
This is where most of the growth comes from:
| Source | Why it grows fast |
|---|---|
| File reads | A large file read in full can cost thousands of tokens, and re-reads cost the same again |
| Command output | Test runs, builds and logs are often long and mostly noise |
| Your messages and Claude’s replies | Every turn stays in the history |
| Tool results from MCP servers | A search or query result lands in context in full |
| Failed attempts | Wrong approaches and your corrections stay until you clear or compact |
A single debugging session or codebase exploration can produce tens of thousands of tokens. That matters because, as the Claude Code docs put it, LLM performance degrades as context fills: Claude may start forgetting earlier instructions or making more mistakes.
How big is the window?
It depends on the model. Claude Code’s model configuration docs list a 1M-token context window for recent models (Fable models, Sonnet 5 and later, Haiku 5.5, Opus 4.7 and later run with it by default). Opus 4.6 and Sonnet 4.6 reach 1M only through their [1m] variant; otherwise they work at a 200K boundary.
A bigger window gives you room, not immunity. A session with 600k tokens of old exploration in it is still slower, costlier per turn and noisier than one that carries only what the current task needs.
Read the meter: /context
Before changing anything, look. /context shows a live breakdown of what is using the window, grouped by category, with suggestions. It also lists which CLAUDE.md and memory files were loaded, which is the quickest way to find a forgotten instruction file in a parent folder.
/contextA few related commands help here:
/memoryopens the loaded memory files so you can edit them./mcplists connected servers and lets you disable the ones you are not using./usageshows token use for the session, including a prompt cache line.
You can also put context usage in a custom status line so you see it without asking.
Compact: /compact and auto-compact
/compact replaces the conversation so far with a summary and keeps going in the same session. Claude Code also does this on its own as you approach the limit; that is auto-compact.
Steer the summary
A plain /compact lets Claude decide what to keep. You get better results when you tell it:
/compact Focus on the API changes and the list of files we modifiedYou can make this permanent with a # Compact instructions section in CLAUDE.md, for example: “When compacting, always preserve the full list of modified files and any test commands.”
To compact only part of the conversation, press Esc twice or run /rewind, pick a message and choose Summarize from here or Summarize up to here.
Set when auto-compact runs
By default Claude Code compacts when the conversation reaches the model’s context limit; models running with a native 1M window compact a little earlier, at about 967K tokens. If you would rather compact sooner, set your own window:
/autocompact 500k
/autocompact autoThe first saves a 500k window for the current model; the second returns to the default. The same setting exists as autoCompactWindow in settings.json and as the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable for scripts. Values from 100K to 1M are accepted.
What survives compaction
The docs list what is put back after a compact: the system prompt, the project-root CLAUDE.md, unscoped rules, auto memory and the current plan-mode plan. Recently modified files are re-read, and nested CLAUDE.md files and path-scoped rules reload when Claude works in those folders again. What does not survive verbatim is the conversation itself, so an instruction you only ever typed in chat can lose detail. If it matters, put it in CLAUDE.md.
One cost to keep in mind: /compact reads the whole conversation to summarize it, so the compact itself is a large request.
Start over: /clear
/clear empties the conversation and costs nothing. Use it when you move to unrelated work. Claude Code’s best practices name two failure patterns it fixes:
- The kitchen sink session. You start one task, ask something unrelated, then go back. The context is full of irrelevant material.
- Correcting over and over. After two failed corrections on the same issue, the context is polluted with failed approaches. Clear and write a better first prompt that includes what you learned.
If you might want the session back, name it first with /rename, then /clear; /resume brings it back later. For a quick question that does not need to stay in history, /btw answers without adding to the conversation.
| Situation | Reach for | Why |
|---|---|---|
| Same task, long history | /compact <focus> | Keeps the thread, drops the bulk |
| Only the early part is stale | /rewind → Summarize up to here | Keeps recent turns in full |
| Switching to unrelated work | /clear | Free, and nothing irrelevant carries over |
| Two corrections didn’t work | /clear + better prompt | Failed attempts mislead the next ones |
| One-off question | /btw | Never enters the history |
Keep CLAUDE.md small
CLAUDE.md loads in every session, so every line is paid for on every turn. Claude Code’s docs suggest keeping it under about 200 lines and asking, for each line, whether removing it would cause mistakes. If not, cut it. A bloated file has a second cost beyond tokens: important rules get lost in the noise and Claude ignores them.
What to do with the rest:
- Move workflow-specific instructions (how to release, how to write a migration) into skills. Only their short descriptions load at startup; the body loads when the skill is used.
- Link to detailed docs instead of pasting them.
- Delete anything Claude already does right without being told, or turn it into a hook if it must always happen.
We go deeper on structure in the CLAUDE.md and AGENTS.md guide.
Use subagents to keep the main context clean
Research is the classic context killer: to answer “how does our auth handle token refresh?”, Claude may read twenty files. A subagent runs in its own context window, does that reading there, and returns only a summary to your main session.
Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.Good candidates for a subagent:
- Codebase exploration before a change.
- Reading long logs or test output to find the one failure that matters.
- A review of the diff in a fresh context, which also avoids bias toward code the main session just wrote.
Subagents are not free. They spend their own tokens, and Claude Code’s docs note that agent teams use roughly 7 times as many tokens as a single session. The win is quality and focus in the main thread, not always a smaller bill.
What MCP servers cost
The Model Context Protocol used to be one of the biggest startup costs, because every tool definition of every server loaded up front. Claude Code now defers tool definitions by default (tool search), so until a tool is used, only its name and the server’s instructions are in context.
That changes the advice, but does not remove it:
- Disable servers you are not using in this project with
/mcp. - Prefer CLI tools such as
gh,aws,gcloudorsentry-cliwhen they exist. The docs call them the most context-efficient way to reach external services. - Watch tool results, not just definitions. A database query or a page snapshot returned by an MCP tool lands in context in full.
Signs of context rot
“Context rot” is the informal name for a session that has quietly got worse because its context is too full or too noisy. Typical signs:
- Claude forgets a rule you stated earlier in the conversation, or one from CLAUDE.md.
- It re-reads files it already read, or asks about things it already knows.
- It repeats an approach you already rejected.
- Answers get vaguer and edits touch the wrong place.
- Each turn feels slower and the token counter climbs faster.
When you see two or more of these, run /context. If the conversation is the bulk, compact with a focus; if the session has wandered across tasks, clear. Also note that after an idle break the prompt cache expires, so the next message reprocesses the whole context at full price. A long-idle, large session is a good moment to compact or clear before you continue.
Habits that keep sessions healthy
- One task per session. Name it, finish it, clear.
- Point, don’t browse. Reference files with
@pathand name functions instead of asking Claude to “look around”. - Scope investigations. “Find where rate limits are enforced in
src/api” beats “investigate rate limiting”. Or hand it to a subagent. - Trim command output. Run single tests rather than the whole suite, and filter logs before Claude reads them.
- Compact with a focus, early. A compact you steer, before the window is nearly full, usually keeps the right details better than an automatic one at the limit.
- Review CLAUDE.md like code. Prune it when Claude starts ignoring rules.
Where AgentVera fits
AgentVera runs Claude Code, Codex and other CLI agents side by side in one desktop app. It does not replace the habits above, but it takes some of the bookkeeping off you when you run several agents at once. All of this is on the token savings page:
- Live context size in the pane for each agent, measured from the CLI’s own history, so it works beyond Claude Code and Codex.
- Auto-compact on by default at a 150k-token threshold, using each CLI’s own command (
/compact,/compress,/summarize,/smol). Change it under Settings → Token savings. - Context profiles (Standard, Balanced, Lean) that shrink the startup baseline per agent.
- A read guard, plus smart tools for Claude Code, that refuse a re-read of an unchanged file and hand the agent an outline of a big file first.
- A project map so agents find the relevant files without reading them one by one.
- The MCP manager, whose connection test shows an approximate token cost per tool.
It is still worth learning /context, /compact and /clear yourself. They work the same with or without AgentVera.