Skip to main content

Context and Compaction

The context window is the amount of text the model can read at one time. When a session gets close to the limit, Claude Code compacts it. It asks the model for a summary. Then it continues from the summary. You can set when this happens. You can also say what the summary must keep.

What Fills the Context​

Sources: How Claude Code Works: The Context Window and Explore the Context Window.

ContentStatusNote
System prompt and tool names
Documented: An official docs page names this item.
MCP tool schemas stay deferred until a tool search loads them.
CLAUDE.md, rules, and auto memory
Documented: An official docs page names this item.
The first 200 lines or 25 KB of MEMORY.md load.
Skill descriptions
Documented: An official docs page names this item.
The body of a skill loads only when the skill runs.
Messages, tool results, and file reads
Documented: An official docs page names this item.
This is the part that grows.
Attachments that Claude Code adds
Undocumented: Only the program shows this item. It can change without notice.
A transcript of 2.1.305 from a stub run shows types such as total_tokens_reminder, output_style, nested_memory, and skill_listing. Transcripts of 2.1.305 from a real machine also showed queued_command, edited_text_file, deferred_tools_record, mcp_instructions_delta, credential_org, and silent_turn_reminder.

The mod event prompt.attachment can rewrite or drop one attachment. For measured token counts of an empty session and ways to shrink it, see Context Budget.

When Compaction Runs​

Let window be the window of the model, or the window you set. Let out be the smaller of the model output limit and 20000.

LevelStatusFormulaExample for a 1,000,000 window
Effective window
Undocumented: Only the program shows this item. It can change without notice.
window - out980,000
Compact threshold
Documented: An official docs page names this item.
effective - 13000967,000, which the docs call "about 967K"
Warning
Undocumented: Only the program shows this item. It can change without notice.
threshold - 20000947,000
Blocked
Undocumented: Only the program shows this item. It can change without notice.
window - out - 3000977,000
Percent override
Documented: An official docs page names this item.
The smaller of effective * pct / 100 and effective - 13000CLAUDE_AUTOCOMPACT_PCT_OVERRIDE sets pct from 1 to 100

At the blocked level, Claude Code stops the turn with a "prompt is too long" error, unless it can recover by compacting. CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE (

Undocumented: Only the program shows this item. It can change without notice.
) replaces the blocked level.

Claude Code finds the window in this order:

  1. CLAUDE_CODE_AUTO_COMPACT_WINDOW
  2. The setting autoCompactWindow (for one model in modelSettings)
  3. Client data from the server
  4. An experiment
  5. The default of the model

The accepted window is from 100K to 1M tokens.

Since 2.1.312, the autoCompactWindow of a subagent also lowers a window that CLAUDE_CODE_AUTO_COMPACT_WINDOW sets. Before, the variable ended the search and the subagent value had no effect. The subagent value is a ceiling. If the window found is larger than the ceiling, Claude Code uses the ceiling (limited by the model window). It never raises the window. Source: the program (chunk-r5cyd28m.js line 83915 and chunk-1wgxyh0t.js line 6088). Sources: Model Configuration: Context Window and Auto-Compaction and the program.

Controls​

Sources: Model Configuration: Set the Auto-Compact Window and Environment Variables.

ItemStatusEffect
/compact [focus]
Documented: An official docs page names this item.
Compacts now. DISABLE_COMPACT removes it.
/autocompact <size|auto>
Documented: An official docs page names this item.
Saves the window for the current model.
--autocompact <auto|tokens>
Documented: An official docs page names this item.
Sets the window for one launch.
autoCompactWindow, autoCompactEnabled
Documented: An official docs page names this item.
Settings. autoCompactWindow also works in the frontmatter of a subagent.
CLAUDE_CODE_AUTO_COMPACT_WINDOW
Documented: An official docs page names this item.
Sets the window. It wins over the command, the flag, and the setting. Accepts k and M suffixes since 2.1.304.
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
Documented: An official docs page names this item.
Sets the percent of the effective window.
DISABLE_AUTO_COMPACT, DISABLE_COMPACT
Documented: An official docs page names this item.
Turn off automatic compaction, or all compaction.
CLAUDE_CODE_MAX_CONTEXT_TOKENS
Documented: An official docs page names this item.
Sets the window for a model ID that Claude Code does not know.
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT
Documented: An official docs page names this item.
Compacts only after the API says the prompt is too long.
CLAUDE_CODE_DISABLE_1M_CONTEXT
Documented: An official docs page names this item.
Turns off the 1M choice.
idleCompaction, CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS
Documented: An official docs page names this item.
Compact a conversation that is idle.
/rewind, then Summarize from here or up to here
Documented: An official docs page names this item.
Compacts one part of the conversation.
/clear
Documented: An official docs page names this item.
Starts with an empty context.
PreCompact, PostCompact hooks
Documented: An official docs page names this item.
Run around a compaction. The trigger field is auto or manual.

Kinds of Compaction​

KindStatusHow it works
Automatic
Documented: An official docs page names this item.
It starts at the compact threshold. The hooks PreCompact and PostCompact get trigger: auto.
Manual
Documented: An official docs page names this item.
It starts with /compact. The trigger is manual.
Reactive
Undocumented: Only the program shows this item. It can change without notice.
The API refuses a request as too long, and Claude Code compacts and tries again. Since 2.1.311, this also covers a standard-window session that goes over 200K tokens and gets "Usage credits required for 1M context" (chunk-8qajn51r.js:6009). It compacts and continues.
Precomputed
Undocumented: Only the program shows this item. It can change without notice.
A summary made ahead of time replaces the conversation.
Larger-model retry
Undocumented: Only the program shows this item. It can change without notice.
Claude Code can retry a failed compaction on a model with a larger window.
Server side
Undocumented: Only the program shows this item. It can change without notice.
The beta context-management-2025-06-27 lets the API edit the context.

Since 2.1.311, when the model's reply to a compaction request has no <summary> block, Claude Code usually asks once more for the summary before it replaces the conversation (chunk-2ht8z368.js:108786). The second request adds a short note that says the reply must hold the summary in <summary> tags (chunk-2ht8z368.js:108553). If the second reply has none either, the compaction fails with no <summary> block in the second reply either (chunk-2ht8z368.js:108779). A gate in the program decides whether the second ask runs, so "usually" is the right word (chunk-2ht8z368.js:108784). Source: the Claude Code changelog and the program.

Auto compaction stops with an error when the context refills within 3 turns of the last compaction, 3 times in a row. The message starts Autocompact is thrashing. Sources: How Claude Code Works: When Context Fills Up and Troubleshooting.

The Summary Prompt​

The compaction request asks the model for a summary in <summary> tags with nine parts. Source: the program (

Undocumented: Only the program shows this item. It can change without notice.
).

  1. Primary Request and Intent
  2. Key Technical Concepts
  3. Files and Code Sections
  4. Errors and Fixes
  5. Problem Solving
  6. All User Messages
  7. Pending Tasks
  8. Current Work
  9. Optional Next Step

The prompt has three forms. One is short ("in 2000 words or fewer"). One asks for an <analysis> first. One covers only the recent messages. The request uses the thinking setting of the session (v2.1.198 or later). See the captured compaction prompt.

What Survives​

Source: Explore the Context Window: What Survives Compaction.

ContentStatusAfter compaction
System prompt and output style
Documented: An official docs page names this item.
They still apply.
Root CLAUDE.md, unscoped rules, and auto memory
Documented: An official docs page names this item.
Claude Code reads them again from disk.
The plan from plan mode
Documented: An official docs page names this item.
Claude Code reads it again from disk.
Rules with paths: and nested CLAUDE.md files
Documented: An official docs page names this item.
They load again when needed.
Files that the session read or edited
Documented: An official docs page names this item.
Claude Code reads up to five again, newest first. A file over 5,000 tokens comes back as a path.
Skills that ran
Documented: An official docs page names this item.
Each keeps 5,000 tokens, up to 25,000 in total. The oldest go first.
Background commands and subagents
Documented: An official docs page names this item.
They keep running.
SessionStart hooks with the compact matcher
Documented: An official docs page names this item.
They run again.

Example​

Your session is long. You start a new task. Run /compact focus on the auth bug fix to keep what matters. Or compact earlier next time by setting a smaller window.

claude --autocompact 500000
~/.claude/settings.json
{
  "$schema": "https://clawdipedia.cc/schemas/claude-code-settings.json",
  "autoCompactWindow": 500000
}

Errors​

Each row is a family of messages. The backticked text is the start that every message in the family shares. A row marked Various gathers the messages of one feature that do not share one start.

Start of MessageStatusWhat It MeansCases
Various
Undocumented: Only the program shows this item. It can change without notice.
Compaction. A compaction did not run or failed.There are no messages to compact, or not enough. The compaction was canceled. Claude Code could not reduce the conversation below the limit. Attached media exceeds size limits. The model policy blocks the swap.