08 / 20Context6 MIN READ

Context Window

The context window is the fixed token budget that holds everything Claude knows about the session — the system prompt, your project instructions, every message, and every tool result — and is re-sent in full on each request.

What it is

The model remembers nothing between requests. On every turn Claude Code re-sends the whole context: the system prompt, your project context, every prior message and tool result, and your new message. The window is the ceiling on that total. It fills from the moment the session starts, before you type anything.

Startup content includes the system prompt, auto memory, environment details, MCP tool names, skill descriptions, and your CLAUDE.md files. Then each file Claude reads, each command’s output, each image, and each of Claude’s own responses adds to the total. Path-scoped rules load when a matching file is read. Nested CLAUDE.md files load when Claude touches their directory.

Fable 5, Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support a one-million-token window; availability varies by plan and provider. A larger window changes when you hit the wall, not the shape of the problem: content in the middle of a long context gets less reliable attention than content at the ends, so a full window degrades answer quality before it degrades anything else.

What it does for you

It sets the hard limit on what Claude can consider at once. Past it, Claude Code compacts, and everything you did not preserve becomes a summary.
It is the main cost driver. Every token in the window is re-sent on every request, which is why prompt caching exists and why a bloated window is expensive as well as slow.
It determines answer quality on long tasks. A window packed with three unrelated tasks produces worse work than a cleared window holding only the current one.

How it works

01Startup content loads before your first message
The system prompt, environment info, the first 200 lines or 25KB of MEMORY.md, MCP tool names, skill descriptions, and every CLAUDE.md in the ancestor chain. Your setup may add an output style or --append-system-prompt text on top.
02Every tool result is appended
A file read adds the file. A Bash command adds up to roughly 30,000 characters inline; past that Claude Code writes the output to a file and passes the path plus a preview instead.
03Lazily loaded instructions arrive mid-session
A rule with paths: frontmatter enters context the first time Claude reads a matching file. A nested CLAUDE.md enters when Claude reads a file in its directory. Neither is loaded at launch.
04Subagents fill their own window instead of yours
A delegated task runs in a separate context window and returns one text result. Fifty file reads inside a subagent cost your session a summary.
05The auto-compact window decides when compaction fires
By default Claude Code compacts when the conversation reaches the model’s context limit, with earlier thresholds for cloud sessions, Sonnet 5, and models running at 200K. Set your own with /autocompact 500k.
06Compaction replaces history with a summary
The system prompt and output style are untouched. Project-root CLAUDE.md, unscoped rules, and auto memory are re-injected from disk. Invoked skill bodies come back truncated to 5,000 tokens each and 25,000 total. Path-scoped rules and nested CLAUDE.md files are lost until their trigger file is read again.

How to implement it

01Run /context to see the actual breakdown
It renders usage as a colored grid by category, names which CLAUDE.md and memory files loaded, and flags context-heavy tools. Pass all to expand the per-item list.
02Cut the largest startup line item first
Usually that is CLAUDE.md over 200 lines, an over-broad skill listing, or MCP tool definitions loaded upfront instead of deferred. Fixing startup cost pays on every turn of every session.
03Scope your reads
Ask for the function, not the file: Grep to find the lines, then read a range. A 3,000-line file read whole to answer one question is the most common avoidable cost.
04Delegate bulk reading to a subagent
Send "find every call site" work to a subagent so the reads land in its window and only the summary lands in yours.
05Clear between unrelated tasks
Run /clear when you switch subjects. Old conversation crowds out the files you need next and costs tokens on every message until it is compacted away.

Examples

Managing the window in a sessionbash

/context            # what is in the window right now, by category
/context all        # expand the per-item breakdown

/compact focus on the auth refactor and the failing specs
                    # summarize now, keeping what you name

/autocompact 500k   # compact at 500K instead of the model's limit
/autocompact auto   # back to the window tuned for your model

/clear              # new conversation, project memory intact

The four commands that matter, in the order you reach for them.

.claude/settings.jsonjson

{
  "autoCompactWindow": 500000
}

Compact earlier than the default so the summarisation happens while there is still room to work.

Scoping a readbash

# Costly: pulls the entire file into the window
"Read src/server/router.ts and tell me how auth middleware is registered."

# Cheap: find the lines first, then read only around them
"Grep for 'authMiddleware' under src/server/, then read 20 lines either side
 of each hit and tell me how it is registered."

# Cheapest for bulk work: the reads never enter your window at all
"Use the Explore agent to find every place authMiddleware is registered and
 report the file, line, and order of registration."

Ask for the lines, not the file. The difference is the whole file versus forty lines.

Use it when

Diagnosing why a session slowed down or got expensive, by running /context and reading the largest categories.
Deciding whether to compact, clear, or delegate before starting a long task.
Choosing where a piece of guidance lives: always-loaded CLAUDE.md, on-demand skill, or path-scoped rule.
Setting an auto-compact window that fires at a natural break rather than mid-task.
Explaining to a teammate why Claude "forgot" something they said an hour ago.

Avoid it when

Optimising a short session. Startup content is a fixed cost and a ten-turn conversation will not approach the limit; time spent trimming is time not spent working.
Trimming CLAUDE.md below the point where it is useful. Adherence drops when instructions are missing, not only when the file is long.
Reaching for a one-million-token window as the fix. It moves the wall without improving attention over a packed context, and on some plans it bills to usage credits.
Delegating small reads to subagents. The spawn-and-summarise round trip costs more than the file you were avoiding.

Common mistakes

SYMPTOMA session gets slower and vaguer over an afternoon and nobody notices why.
FIXRun /context. The usual cause is one huge file read or a long unrelated task still sitting in history. Compact with a focus, or clear and restate the current task.
SYMPTOMAn instruction from earlier in the session stops being followed.
FIXCompaction summarised it away. Only project-root CLAUDE.md, unscoped rules, and auto memory are re-injected from disk — move the instruction into CLAUDE.md.
SYMPTOMA path-scoped rule that worked earlier stops applying after a compact.
FIXRules with paths: frontmatter are lost until a matching file is read again. Drop the paths: key or move the content to the project-root CLAUDE.md if it must persist.
SYMPTOMAuto-compaction fires in the middle of a delicate task.
FIXSet the window lower with /autocompact 500k so compaction happens with room to spare, and run /compact yourself at task boundaries.
SYMPTOMReading a huge log file to find one error fills the window.
FIXGrep the file for the pattern, or let the Bash tool write the output to a file — past roughly 30,000 characters Claude Code passes a path and a preview instead of the whole thing.

Best practices

Run /context when a session feels off, before guessing at the cause.
Treat startup content as the expensive part: it is paid on every request of every session.
Grep before you read, and read ranges rather than whole files.
Delegate bulk exploration to a subagent so the reads land in its window.
Run /clear between unrelated tasks and /compact <focus> at natural breaks inside one.
Put instructions that must survive compaction in the project-root CLAUDE.md, not in chat.

Try it in five minutes

Measure your own context, then cut it in half.

1.Open a real project and run claude, then /context before typing anything. Note the startup total and the biggest category.
2.Ask Claude to read your three largest source files, then run /context again and compare.
3.Run /clear, then ask the same question but phrased as "grep for X and read 20 lines around each hit".
4.Run /context a third time and compare the totals.
5.Run /compact focus on <your current task> and check what survived with /context.

Verified against code.claude.com/docs/en/context-window on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS