Context Window Mastery

Context is Claude Code's most precious resource. Every file you read, every command you run, every message you send consumes tokens from a finite budget. When the context window fills up, performance degrades—Claude starts missing details, repeating mistakes, and losing track of what matters.

This lesson teaches you to manage context like a professional: visualize usage, compact strategically, structure sessions for longevity, and switch models when needed.

Why Context Management Matters

Claude's context window fills up faster than you think. Every interaction adds to the total:

• File reads: A 500-line file consumes ~2,000 tokens
• Command output: git diff on a large changeset can be 10,000+ tokens
• Messages: Your questions and Claude's responses add up quickly
• Tool calls: Every function call and response is recorded

The critical insight: Claude Code's performance is directly tied to context quality. A clean, focused context produces better results than a cluttered one—even if there's technically space remaining.

When context fills with irrelevant information from earlier tasks, Claude struggles to:

• Find the relevant details for the current task
• Remember recent decisions and patterns
• Maintain consistency across responses
• Execute complex multi-step operations

If Claude suddenly starts making uncharacteristic mistakes, the context is probably too noisy.

Visualizing Context Usage

The /context command shows you exactly what's consuming your context window:

/context

You'll see a colored grid representing context usage:

• Green blocks: Low usage (0-60%)
• Yellow blocks: Medium usage (60-80%)
• Red blocks: High usage (80-95%)
• Dark red blocks: Critical usage (95-100%)

The visualization breaks down usage by category:

• System prompts and instructions
• User messages
• Assistant responses
• Tool calls and outputs
• File contents

Pro tip: Check /context at the start of complex tasks. If you're already at 70%+ usage, consider compacting or starting fresh.

Monitoring with Status Line

Configure your status line to always display context usage:

/statusline

This shows a persistent status bar with:

• Current model (sonnet, opus, etc.)
• Token usage (e.g., "45K/200K tokens")
• Estimated cost for the session
• Context percentage

The status line updates in real-time, letting you catch context bloat before it becomes a problem.

Auto-Compaction: Automatic Context Management

When context usage reaches approximately 95%, Claude Code automatically triggers auto-compaction. This process:

1. Analyzes the conversation: Identifies what's still relevant
2. Summarizes key information: Code patterns, file states, decisions made
3. Discards old noise: Removes superseded information and completed tasks
4. Preserves context continuity: Ensures Claude remembers what matters

Auto-compaction is intelligent—it doesn't just truncate old messages. It creates a semantic summary that maintains context quality while freeing up space.

Customizing Auto-Compaction Threshold

If you want auto-compaction to trigger earlier (e.g., at 80% instead of 95%), set an environment variable:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

When to lower the threshold:

• Working on complex, multi-file refactoring tasks
• Planning to read many large files
• Long debugging sessions where you need maximum clarity

When to keep it default:

• Short, focused tasks
• When context contains critical details you don't want summarized

Manual Compaction: Compacting on Your Terms

Don't wait for auto-compaction. Use /compact to manually compress context whenever it makes sense:

/compact

This triggers immediate compaction with Claude's default summarization.

Compaction with Instructions

Guide Claude's compaction by specifying what to focus on:

/compact Focus on the API refactoring decisions and the new authentication flow

/compact Preserve all function signatures and interface definitions, discard debugging output

/compact Keep only the final implementation, remove all exploration and failed attempts

Effective compaction instructions:

• Be specific: "Preserve Redux action creators" beats "keep the important stuff"
• Identify what to discard: "Remove all test output" is clearer than "clean things up"
• Highlight critical context: "Remember the user wants TypeScript strict mode enabled"

Partial Compaction with Rewind

Sometimes you don't want to compact the entire session—just a messy middle section. Use rewind compaction:

1. Press Esc twice to enter command mode
2. Type /rewind and select a message in the conversation history
3. Choose "Summarize from here"

This compacts everything from that point forward while preserving earlier context unchanged.

Example scenario: You spent 30 messages debugging a red herring, then found the real issue. Rewind to just before the wild goose chase and compact from there.

The /clear Habit: Starting Fresh

The single most effective context management habit is clearing between tasks:

/clear

This wipes the entire conversation history, giving you a clean slate.

When to use /clear:

• Switching to a completely different task
• Finished one feature and starting another
• After extended debugging sessions
• When Claude's responses become inconsistent

Why it works: Each task has its own context requirements. Carrying over context from unrelated work just adds noise. A fresh context is faster and more focused.

Best practice: Name your session with /rename before clearing, so you can resume if needed:

/rename "API authentication refactor"
/clear

Now you can start the next task with full context capacity.

Session Structuring for Longevity

Design your workflow to minimize context accumulation:

One Task Per Session

Whenever possible, dedicate a session to a single task:

• Session 1: Add new API endpoint
• Session 2: Update client to use new endpoint
• Session 3: Write integration tests

This approach:

• Keeps context focused and relevant
• Makes it easier to resume later
• Reduces cognitive load (you're only thinking about one thing)

Naming Sessions

Give sessions descriptive names with /rename:

/rename "Fix user authentication bug"

/rename "Refactor database queries - performance"

/rename "Add dark mode toggle to settings"

Named sessions are easier to resume and identify in your history.

Resuming Sessions

Resume a previous session with:

claude-code --continue

This restores the last session's context.

To resume a specific named session:

claude-code --resume "Fix user authentication bug"

Pro tip: Resume sessions only when context is still relevant. If the codebase has changed significantly since the session, start fresh instead.

Model Switching: Right Tool for the Task

Different models have different context capabilities and performance characteristics. Use /model to switch:

/model

Available Models

Strategic Model Switching

Start with Sonnet for most tasks. It's fast, capable, and cost-effective.

Switch to Opus when:

• Designing complex system architecture
• Debugging subtle, multi-layered issues
• Making critical refactoring decisions
• Planning large-scale changes

Switch to Haiku when:

• Making simple text edits
• Running quick grep/search operations
• Generating boilerplate code
• Processing straightforward requests

Switch to Sonnet[1m] when:

• Working in massive codebases (100+ files)
• Conducting long research sessions
• Building context over many files
• Avoiding frequent compaction

Use OpusPlan when:

• You need Opus-level reasoning for planning
• But want Sonnet speed for implementation
• Working on complex features with clear execution steps

Example workflow:

# Start with Opus for architectural planning
/model opus
"Design the new microservice architecture"

# Switch to Sonnet for implementation
/model sonnet
"Implement the API gateway service"

# Switch to Haiku for test boilerplate
/model haiku
"Generate unit test stubs for all API endpoints"

Context Isolation with Subagents

When you need to investigate something without polluting your main context, use subagents:

/agent researcher

The subagent runs in an isolated context. All its file reads, command outputs, and explorations stay in its own context window.

Example scenario:

You're refactoring a component but want to research how a library works:

# Main session (working on refactoring)
"Let me spin up a subagent to research the React Query API"

/agent researcher
"Read the React Query documentation and find examples of pagination"

# Researcher subagent explores docs, reads multiple files
# None of this pollutes your main context

# Researcher reports back
"Based on my research, here's how to implement pagination..."

# You continue refactoring with a clean, focused context

When to use subagents:

• Researching unfamiliar libraries
• Investigating multiple potential solutions
• Exploring large codebases
• Running experiments that might not work out

The subagent consumes its own context budget, keeping your main session lean.

Monitoring Costs and Token Usage

Track your session's resource consumption with /cost:

/cost

This displays:

• Total tokens used (input + output)
• Breakdown by message type
• Estimated cost in USD
• Average tokens per message

Use /cost to:

• Identify unexpectedly expensive sessions
• Compare costs across different models
• Justify budget for Claude Code usage
• Optimize workflows for efficiency

Example output:

Session Statistics:
- Input tokens: 45,203
- Output tokens: 23,891
- Total tokens: 69,094
- Estimated cost: $2.14
- Messages: 28
- Avg tokens/message: 2,467

Context Management Checklist

Apply these practices to every Claude Code session:

Before starting:

• Check current context with /context
• Clear old sessions with /clear if switching tasks
• Configure status line with /statusline for visibility
• Choose the right model with /model

During work:

• Monitor status line for context usage
• Use /compact [instructions] when approaching 70-80%
• Delegate investigations to subagents with /agent
• Keep focus narrow (one task at a time)

After completing a task:

• Name the session with /rename if resumable
• Run /cost to track usage
• Use /clear before starting the next unrelated task
• Consider which context is worth preserving

When performance degrades:

• Check /context for bloat
• Compact with specific instructions
• Consider starting fresh with /clear
• Switch to a larger context model if needed

Common Context Pitfalls

Pitfall 1: Reading unnecessary files

Don't ask Claude to read entire directories "just in case." Read only what's needed for the current task.

Pitfall 2: Keeping debug output

After fixing a bug, compact to discard the debugging transcript. It's just noise for future tasks.

Pitfall 3: Mixing unrelated tasks

Jumping between features in one session creates context pollution. Use /clear between tasks.

Pitfall 4: Ignoring context warnings

When Claude says "the context is getting full," listen. Compact or clear immediately.

Pitfall 5: Over-relying on auto-compaction

Auto-compaction is a safety net, not a strategy. Manually compact when you control the focus.

Next Steps

You've mastered context management—the foundation for long, productive Claude Code sessions. In the next lesson, we'll explore advanced agent workflows, where you'll learn to orchestrate teams of agents for complex, multi-faceted projects.

Resources:

• Claude Code documentation: Context management guide
• /help context for command reference
• /help model for model selection details