context-budgeting

Context Budget Mastery

Master the art of managing Claude Code's context window for maximum productivity.

Goal

Help users understand exactly where context is consumed, plan sessions that avoid hitting limits, and recover gracefully when context gets tight.

Context Window Sizes

Model	Context Window	Practical Limit
Opus 4.6	200,000 tokens	~180,000 usable
Sonnet 4.6	200,000 tokens	~180,000 usable
Haiku 4.5	200,000 tokens	~180,000 usable

The ~20k overhead comes from system prompt, tool definitions, and framework messages that are always present.

Token Arithmetic

What consumes context

Every request to Claude includes ALL of the following:

Component	Loaded When	Typical Size	Cached?
System prompt	Every turn	3-5k tokens	Yes (after turn 1)
CLAUDE.md (all levels)	Every turn	2-20k tokens	Yes (after turn 1)
Rules (unconditional)	Every turn	1-10k tokens	Yes (after turn 1)
Rules (path-scoped)	When matching files opened	0-5k tokens	Partially
Skill descriptions	Every turn	1-5k tokens	Yes
MCP tool schemas	Every turn	2-15k tokens	Yes
Conversation history	Every turn (grows)	5-150k tokens	Partially
Tool results (latest)	Current turn	0-10k tokens	No

The growth problem

Context grows with every turn because conversation history accumulates:

• Turn 1: ~30k (system + CLAUDE.md + rules + skills + MCP + message)
• Turn 5: ~50k (+ 4 turns of Q&A and tool calls)
• Turn 15: ~100k (+ tool outputs, file reads)
• Turn 30: ~180k (approaching limit — auto-compact triggers)

Fixed vs. variable budget

Fixed overhead (always loaded):
  System prompt           ≈  4,000 tokens
  CLAUDE.md files         ≈  5,000 tokens (varies)
  Unconditional rules     ≈  3,000 tokens (varies)
  Skill descriptions      ≈  2,000 tokens (varies)
  MCP tool schemas        ≈  5,000 tokens (varies)
  ─────────────────────────────────────────────────
  Total fixed overhead    ≈ 19,000 tokens

Variable (grows with session):
  Conversation history    =  grows per turn
  Tool results            =  per tool call
  Loaded skill bodies     =  when skills activated
  Path-scoped rules       =  when matching files read

Your effective working budget = 200,000 - fixed overhead - safety margin

Anchor Budget Math

What are anchors?

Anchors are pieces of context you want to survive /compact. Without anchoring, compaction summarizes everything, potentially losing critical state.

Calculating anchor budget

Rule of thumb: anchors should consume < 10% of your context window.

Context window:           200,000 tokens
Target anchor budget:      20,000 tokens (10%)
Available for conversation: 180,000 - fixed overhead

What to anchor

Priority anchoring targets:

1. Current task definition and constraints
2. Key decisions made during the session
3. File paths and line numbers of changes in progress
4. Error messages being investigated
5. Architecture notes discovered during exploration

What NOT to anchor

• File contents (can be re-read)
• Full conversation history (that's what compact summarizes)
• Tool output (can be regenerated)
• Generic instructions (already in CLAUDE.md)

Compact Strategies

When to compact

Signal	Action
Auto-compact triggers (system message)	Let it happen, but consider manual compact first
Context utilization > 70%	Good time for proactive compact
Shifting to a new sub-task	Compact to clear old context
After a long research phase	Compact before implementation
After reading many files	Compact to summarize findings

Focus strings

When compacting, provide a focus to guide summarization:

/compact Focus on the auth middleware refactor: keep the API contract, test failures, and migration plan

Good focus strings:

• Name the specific task
• List what must survive
• Mention key file paths

Bad focus strings:

• Empty (default summarization may miss important details)
• Too broad ("keep everything important")
• Too narrow ("only keep line 42 of auth.ts")

What survives compact automatically

• CLAUDE.md content (re-read from disk)
• Rules files (re-read from disk)
• Skill descriptions (re-injected)
• MCP tool schemas (re-injected)
• Auto-memory notes (persisted to disk)

What does NOT survive compact

• Conversation details (summarized, not preserved verbatim)
• Tool outputs (lost unless anchored)
• In-progress reasoning (summarized)
• File contents you read (must re-read)

Progressive Loading

The 82% savings pattern

Skills use progressive loading:

• At startup: only frontmatter (name, description, triggers) loaded — ~50 tokens per skill
• When activated: full skill body loaded — ~500-2000 tokens per skill

With 30 skills:

• All loaded: 30 × 1000 = 30,000 tokens
• Progressive: 30 × 50 + 3 active × 1000 = 4,500 tokens (85% savings)

Applying progressive loading to your content

1. Keep CLAUDE.md focused on routing and short rules
2. Move reference material to skills (loaded on demand)
3. Use path-scoped rules (loaded only for matching files)
4. Use @path imports for large documents (loaded but can be excluded)

Large Codebase Patterns

When a repo is too big for one session

Signs you need to partition:

• Reading more than 30-40 files per session
• Context fills up before implementation starts
• Frequent auto-compaction interrupts

Partitioning strategies

1. Module-by-module: tackle one module per session
2. Research then implement: research session → notes → implementation session
3. Subagent delegation: main context stays clean, subagents explore
4. Multi-session plan: plan in session 1, implement in session 2-N

Using subagents for context isolation

Main context: task planning, implementation
  └── Subagent 1: research existing patterns (Haiku)
  └── Subagent 2: explore test coverage (Haiku)
  └── Subagent 3: review dependencies (Haiku)

Each subagent gets its own 200k context window. Only summaries return to main context.

Anti-Patterns

Anti-Pattern	Problem	Fix
CLAUDE.md > 500 lines	Eats working budget every turn	Split into rules and skills
10+ unconditional rules	High fixed overhead	Path-scope where possible
All skills model-invocable	Description tokens add up	Use disable-model-invocation: true for manual-only skills
Too many MCP servers	Schema tokens accumulate	Disconnect unused servers (/mcp)
No compaction strategy	Hit limit unpredictably	Compact proactively at 70%
Reading entire large files	Each read adds thousands of tokens	Use Grep to find specific content
Ignoring auto-memory	Re-discovering the same facts each session	Let auto-memory persist findings

Quick Reference

Context health check

/cost           → see current token usage
/compact        → manually compact context
/memory         → see what CLAUDE.md/rules are loaded
/mcp            → see MCP server token costs
/model          → check/change current model

Rule of thumb targets

Metric	Target
Fixed overhead	< 25k tokens (12.5% of 200k)
Working budget	> 150k tokens
Compact trigger	70% utilization
Anchor budget	< 20k tokens
Skills active at once	≤ 5
MCP servers connected	≤ 5