Context Management

Your 50-turn session suddenly produces garbage output. Claude isn’t broken — it hit the 200K token context window and started compacting older messages to make room. The context you thought was permanent just got summarized into a few sentences.

200,000 tokens sounds enormous until you realize that your system prompt, CLAUDE.md files, MCP tool descriptions, conversation history, and extended thinking are all competing for the same window. Managing context is about deciding what stays, what gets compressed, and what you pay for every turn.

Effort Levels

The --effort flag controls how deeply Claude reasons before responding. Lower effort means fewer thinking tokens and faster answers, but also less thorough analysis for complex tasks.

You can set effort via the CLI flag, an environment variable, or in your CLAUDE.md:

# CLI flag
claude -p "Refactor auth.py" --effort medium

# Environment variable
export CLAUDE_EFFORT=medium

# Or in CLAUDE.md
# Settings
effort: medium

For cost-sensitive CI pipelines, combine effort with MAX_THINKING_TOKENS to get full reasoning within a hard ceiling:

MAX_THINKING_TOKENS=8000 claude -p "Refactor auth.py" --effort high

This gives high-quality reasoning but prevents runaway thinking token spend. At Opus pricing ($75/M output tokens), an uncapped complex prompt can burn 20K+ thinking tokens — $1.50 in a single response just for thinking.

Context Consumers

Every piece of information in Claude’s context window costs tokens. Use the /context command inside an interactive session to see a live breakdown.

MCP tool descriptions deserve special attention. Each tool description consumes 200-500 tokens. With 80+ tools across multiple MCP servers, you can lose 40K-50K tokens before you even start working. Audit with /context, disable unused servers in .claude/settings.json, and use ToolSearch deferred loading to load tool schemas on demand rather than upfront:

# Trigger deferred loading when MCP tools exceed 5% of context
ENABLE_TOOL_SEARCH=auto:5 claude

The /compact Command

When your context is filling up, the /compact command summarizes the conversation so far and replaces the full history with a compressed version. The key advantage over waiting for auto-compaction is control: you tell Claude what to preserve.

You can also embed compaction instructions directly in your CLAUDE.md so they apply automatically every time compaction occurs, whether manual or automatic:

# Compact instructions
When you are using compact, please focus on test output and code changes

Three ways to manage context bloat, each for a different situation:

Auto-Compaction

Auto-compaction triggers at approximately 80-90% context window utilization. When it fires, Claude summarizes the entire conversation, replaces the full history with that summary, re-reads CLAUDE.md from disk, and condenses tool results to their essentials. You do not control what gets prioritized — the model decides.

The problem with auto-compaction is that it is reactive. By the time it triggers, subtle early details may already be compressed beyond recovery. A design decision rationale from turn 3 might become a single sentence by turn 40. The proactive strategy is to run /compact manually at around 60% utilization with explicit focus instructions, so you decide what survives rather than leaving it to the automatic trigger.

For tasks that require reading many files or producing verbose output, consider delegating to a subagent using the Task tool. Subagents run in their own context windows, keeping the main conversation lean while still doing thorough analysis.

Cache Economics

Claude Code automatically caches system prompts and CLAUDE.md content. Understanding the two cache tiers is the difference between a $50 session and a $10 session.

The first call in a session writes the system prompt (~14K tokens) to cache at 1.25-2.0x the base rate. Every subsequent call within 5 minutes reads that cached content at 0.1x the base rate. After 5 minutes of inactivity, the ephemeral cache expires and the next call pays the full write cost again.

For a 100-turn Opus session, the savings are dramatic: without caching, 100 turns of 15K input tokens at $15/M costs roughly $22.50 in input tokens alone. With caching, 1 write plus 99 reads comes to about $2.51 — an 89% reduction on input tokens. Real-world total session costs drop from $50-100 to $10-19.

These two payloads were identical prompts (“What is 2+2?”) run 30 seconds apart. The effort low run cost 3.8x more than effort high — but not because of effort level. The entire cost difference comes from cache state. The first call had a cache miss (9104 creation tokens), while the second hit a warm cache (14253 read tokens). On subsequent runs with a warm cache, costs converge regardless of effort. For trivial prompts, effort level does not change the answer or the cost.

Context Management Playbook

A practical cadence for keeping context healthy in long sessions:

Proactive /compact at 60% utilization. Do not wait for auto-compaction at 80-90%. By that point, subtle early context (design rationales, rejected approaches, variable naming decisions) may already be degraded. Run /compact with explicit focus instructions: /compact Focus on the API contract changes and migration decisions.

MCP overhead audit. Each MCP server adds 200-500 tokens of tool descriptions to every turn, even when idle. With 20 servers, that is 4,000-10,000 tokens of overhead per turn, silently shrinking your effective context. Run /context periodically to check. Disable servers you are not actively using.

Monorepo CLAUDE.md splitting. A single 47K-word CLAUDE.md dramatically degrades performance. Split into subdirectory-specific files — community reports show splitting from 47K to 9K words across multiple files improves response quality and reduces startup overhead.

Delegate to subagents. For tasks requiring reading many files or producing verbose output, use the Agent tool. Subagents run in their own 200K context windows, keeping the main conversation lean while still doing thorough analysis. The result summary returns to the main context, not the full working state.

/clear warning. The /clear command permanently deletes all session history with no recovery mechanism. Unlike /compact, which preserves a summary, /clear wipes everything and re-reads only CLAUDE.md. Use it only when starting a completely new task.