Context Management

Claude Code (and Claude models in general) has a limit on how much text it can process in a single conversation. This is called the context window. Understanding and managing this limit determines the quality of long working sessions.

What Is the Context Window?

It is the total amount of text a Claude model can "remember" at once.

┌─────────────────────────────────────────────┐
│  Context window (200K default / 1M extended)│
│                                             │
│  [Conversation] [Code] [File contents]      │
│  [Responses]                                │
└─────────────────────────────────────────────┘

Claude Code's default context window is 200,000 tokens (200K). Opus 4.6 and later and Sonnet 4.6 also support an extended 1,000,000-token (1M) context. Fable 5 and Sonnet 5 use 1M by default — it is not a separate extension option, and on the API, Fable 5, Sonnet 5, Opus 4.8, and 4.7 always run at 1M.

1M extended context — availability by plan

Access to the 1M context differs by model and plan:

• Max / Team / Enterprise: Opus is automatically upgraded to 1M (included in the subscription with no extra setup or cost). However, Sonnet 1M requires Extra Usage
• Pro: 1M for both Opus and Sonnet requires Extra Usage
• API / pay-as-you-go: full 1M access for both Opus and Sonnet
• Fable 5 · Sonnet 5: 1M is the default context (the official 1M plan table only covers Opus and Sonnet up to 4.6, so subscription-plan conditions are separate from the items above)
• 1M is billed at standard model rates with no premium even for tokens beyond 200K. If included in your subscription, it is covered by your subscription limits

To use the 1M context, pick the model in /model or use the [1m] suffix:

# [1m] suffix on a model alias
/model sonnet[1m]

# Also works with the full model name
/model claude-sonnet-4-6[1m]

To fully disable the 1M context, set an environment variable:

export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Roughly, 200K amounts to:

• About 100,000 words of Korean text
• About 150 code files (averaging 50 lines each)
• One typical coding session

What Happens When the Context Fills Up

Once the context passes roughly 70-80% full:

1. Responses slow down — the more text to process, the slower the response
2. Early content starts getting forgotten — accuracy about older parts of the conversation drops
3. Costs rise — more tokens means higher API costs
4. Auto-compaction kicks in — as Claude Code approaches the limit, it removes old tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved, but detailed instructions from early in the conversation may be lost

Checking Context Status

The /context command visualizes current context usage by category. You can also check it in /status.

/context

Estimated usage by category
⛁ System prompt: 7.2k tokens (0.7%)
⛁ System tools: 7.5k tokens (0.7%)
⛁ MCP tools: 834 tokens (0.1%)
⛁ Memory files: 10.4k tokens (1.0%)
⛁ Skills: 4.8k tokens (0.5%)
⛁ Messages: 286.5k tokens (28.7%)
⛶ Free space: 649.7k (65.0%)
⛝ Autocompact buffer: 33k tokens (3.3%)

Beyond per-category token shares, the token counts of individual MCP tools and Skills are shown as separate line items. MCP tools are split into Loaded (currently loaded) and Available (on standby, loaded when called), so you can see the on-demand loading state too.

The context cost of MCP servers and Skills

Merely connecting an MCP server puts its tool definitions into your context. Skills also add their descriptions for each one installed. Use /context to check how many tokens each item takes, turn off unused MCP servers in /mcp, and remove unused Skills or set disable-model-invocation: true on them. If MCP tools exceed 10% of the context, Tool Search activates automatically and loads only the tools you need, on demand.

Context Management Strategies

Strategy 1: Compress with /compact

When a conversation gets long, this keeps the essentials without fully resetting.

/compact

Claude Code analyzes the conversation so far and summarizes the key content:

• Completed work
• Current state
• Next steps
• Important decisions

Focus instructions — the real value of manual compaction

Appending focus instructions after /compact lets you specify which information to prioritize preserving. This is the one thing auto-compaction cannot do. Auto-compaction organizes the conversation by general criteria, while focus instructions explicitly tell it to keep the context you are focused on right now.

/compact focus on the API changes
/compact focus the summary on the code samples and the Stripe webhook handling logic

Focus instructions are a parameter you can only specify when running /compact manually. Use them when you don't want your workflow to lose its thread.

Pin it with a Compact Instructions section in CLAUDE.md

To fix default compaction criteria at the project level, add a Compact Instructions section to CLAUDE.md:

# Compact Instructions

When compacting, focus the summary on test output and code changes.
Prioritize preserving the last 30 minutes of debugging flow over the initial setup steps.

Applies to both manual and automatic compaction

The Compact Instructions section in CLAUDE.md applies not only to manual /compact but also whenever auto-compaction triggers. Set it once and every compaction — whenever it fires — follows these criteria. If focus instructions are "specified on the spot," Compact Instructions is the "project default."

How auto-compaction proceeds

As the context approaches its limit, Claude Code automatically tidies the conversation. Your session won't suddenly break even if you never run /compact manually.

Auto-compaction proceeds in three stages:

1. Remove old tool outputs first — file read results, command output, and so on
2. Summarize the conversation if needed — if stage 1 isn't enough, the whole conversation is compressed
3. Preserve requests and key code — user requests and important code snippets are kept (though detailed early instructions may be lost)

Auto-compaction thrashing error

If a single file or tool output is so large that the context immediately fills up again even after summarizing, Claude Code stops with an error after a few attempts instead of looping compaction forever. This is called a thrashing error.

How to recover:

• Remove the large file/output causing the problem, or delegate it to a subagent
• Start fresh with /clear and pull only the essential context back in from CLAUDE.md

Official docs: Auto-compaction stops with a thrashing error

Strategy 2: Start Fresh with /clear

Use this when starting a completely different task.

# Payment module finished
/clear
# Now start the notification system
claude
> Implement the notification system: email + push notifications.

If your project context lives in CLAUDE.md, the important information persists even after /clear. And if you reset by accident, /rewind can restore the conversation from before the /clear (v2.1.191+).

Strategy 3: Split Work into Small Pieces

Multiple short sessions beat one long session.

❌ Inefficient:
"Build the entire payment system in one go
 (Stripe integration, webhooks, refunds, subscriptions, coupons, receipt emails...)"

✅ Efficient:
Session 1: "Set up basic Stripe payment integration"
Session 2: "Add webhook handling logic"
Session 3: "Implement the refund feature"

When each session ends, commit the code to git and start a new session with /clear.

Strategy 4: Reference Files Directly

Don't paste long file contents into the conversation — let Claude Code read the files itself.

❌ Inefficient:
> Review this code: [pasting 500 lines of code into the chat]

✅ Efficient:
> Review the src/payment/stripe.ts file

When Claude Code reads files directly, it uses context more efficiently.

Strategy 5: Store Important Information in CLAUDE.md

Put information that must survive across sessions into CLAUDE.md.

# CLAUDE.md

## Current Progress (updated 2026-02-20)
- ✅ Auth module complete
- 🔄 Payment module in progress (Stripe webhook handling remaining)
- ⬜ Notification system not started

## Key Decisions
- Retry failed payments up to 3 times (exponential backoff)
- Refunds only within 72 hours

This information persists even when you start a new session.

Strategy 6: Separate Context with Skills and Subagents

Skills load on demand. At session start Claude only includes each skill's description in the context and loads the actual body only when the skill is invoked. For manual-invocation-only skills, setting disable-model-invocation: true keeps even the description out of the context.

[Loaded at session start]
├── Full CLAUDE.md contents
├── MCP server tool definitions (thousands of tokens per server)
├── Skill descriptions only (a few dozen tokens each)
└── System tool definitions (fixed)

[Loaded only when invoked]
├── Full Skill body (only the ones invoked)
└── Subagent result summaries

Subagents have independent contexts. They don't consume the main conversation's context and return only a summary when their work completes. Delegating high-output tasks like running tests or searching documentation to subagents protects your main context.

Watch the context cost of MCP servers

Merely connecting an MCP server means its tool definitions are included in the context on every request. Even a few connected servers can take up substantial context. Check per-server cost with /mcp and remove servers you rarely use. If MCP tools exceed 10% of the context, Tool Search activates automatically and loads only the tools you need, on demand.

Working with Large Codebases

In large projects with thousands of files, loading everything into the context is impossible.

Narrow the Scope

# Start from a specific module, not the whole project
cd src/modules/payment
claude
> Review the payment logic in this directory

Explicitly Add Only Relevant Files

> /add src/payment/stripe.ts
> /add src/payment/types.ts
> Based on these two files, add the refund logic

Grasp Interfaces/Types First

> Read only the type definitions in the types/ directory first.
  Open implementation files later, only as needed.

Estimating Context Costs

Use this as a reference when planning long sessions.

Task size	Estimated tokens	Estimated cost (Sonnet)
Writing a simple function	~5K	~$0.01
Implementing a component	~20K	~$0.04
Implementing a full feature	~80K	~$0.16
Implementing a full module	~200K	~$0.40

tip

If a long session is on the schedule, check costs periodically with /status. If you're spending more than expected, more specific requests can bring costs down.

Rolling Back with Checkpoints

When work heads in the wrong direction, press Esc+Esc or run /rewind to return to a previous state. Claude Code automatically creates a checkpoint before each prompt. See Checkpointing for details.

Practical Pattern: Managing a Long Session

9 AM: start claude
> Today's goal: finish the payment module

... 2 hours of work ...

> /status   (check: 45% of context used)

... 1 more hour of work ...

> /compact  (compress context from 70% → 30%)

... wrap-up work ...

> Today's work is done. Update CLAUDE.md so I can continue tomorrow.

This way you can keep quality high while working all day.