Inside Claude Code's Context Window: Token Economics & Compaction
In traditional API-based chat interfaces, token usage is linear: sending a short question costs a fraction of a cent. In agentic coding assistants like Claude Code, however, every turn re-evaluates the system prompt, project configuration (CLAUDE.md), auto-memory files, full conversation transcripts, and accumulated file read outputs. In long-running development sessions, unmanaged context growth leads to latency degradation, higher token costs, and context thrashing.
This article breaks down the token mechanics inside Claude Code's context window. We trace a real engineering scenario — investigating ORDER-812: Out-of-order event sequence in event-sourcing consumer inside an orders-service repository — to demonstrate how tokens accumulate, when automatic context compaction triggers, why mid-session edits to CLAUDE.md invalidate prompt caches, and how to use /compact and /context effectively. For broader agent architecture and session management, see How Claude Code Works and Managing Sessions in Claude Code.
Anatomy of the Agent Context Window
When Claude Code prepares an API call for the model, it constructs a multi-layered context payload. This payload consists of static instructions (system prompts, project rules from CLAUDE.md, global rules), dynamic environment metadata, loaded skills, auto-memory files, and the complete transcript of previous user inputs, assistant outputs, and tool execution results.
In orders-service, as the agent reads src/events/consumer.ts (1,200 lines) and greps through 50 log files, each tool execution injects raw token payloads directly into the transcript buffer. Understanding how this buffer is partitioned prevents unexpected token limit exhaustion.
| Category | Contents | Mutability | Cache Behavior |
|---|---|---|---|
| Static Prefix | System prompt, CLAUDE.md, Skill schemas | Immutable during turn sequence | Cached (High hit rate) |
| Transcript History | User prompts & tool execution results | Appends every turn | Progressive cache append |
| Active Tool Buffers | File views, grep outputs, command stdout | Transient per tool call | Uncached on first read |
| Reserve Headroom | Token allocation reserved for completion output | Fixed allocation buffer | N/A |
Quick reference
- System prompts and project rules form the static prefix at the head of the context window.
- Large file reads and extensive terminal outputs consume the largest share of transcript tokens.
- The model's maximum output completion budget (e.g., 8k-16k tokens) is reserved separately from input context.
Remember this
The context window is a dynamic buffer where file reads and command outputs compete with conversation history for total capacity.
Automatic Compaction & Summary Generation
When an active session approaches ~85% of total context window capacity (or hits token thresholds), Claude Code triggers Automatic Context Compaction. Rather than failing or dropping context abruptly, the harness spawns an internal summarization turn.
During compaction, the agent condenses prior tool outputs, file reads, and multi-turn reasoning into a structured session summary containing: key architectural findings, files modified, pending tasks, and active hypotheses. The raw transcript history is then pruned, resetting context consumption while preserving critical task continuity.
Quick reference
- Manual compaction can be triggered at any time using the
/compactcommand in the CLI. - Compaction replaces hundreds of raw tool response turns with a single consolidated markdown summary block.
- Key file paths and active git diffs are explicitly preserved across compaction boundaries.
Remember this
Context compaction prunes raw execution history into a structured recap, restoring token headroom without losing critical problem context.
Prompt Caching: Prefix Matching & Invalidation Triggers
Prompt Caching is the core mechanism that keeps multi-turn agent interactions fast and affordable. Anthropic's prompt caching operates on exact prefix matching: as long as the initial portion of the context window (system prompt, CLAUDE.md, early transcript) remains byte-for-byte identical, the API reuses pre-computed KV-cache states.
However, editing CLAUDE.md mid-session or changing tool definitions alters the static prefix. This invalidates the cached prefix, causing the subsequent turn to perform a full uncached read.
1<!-- Keep static project rules at the TOP of CLAUDE.md for optimal caching -->2# Orders Service Development Rules3 4## Build & Test Commands5- Build: npm run build6- Test: npm test7- Single Test: npx jest src/events/consumer.test.ts8 9## Code Style & Architecture10- Use explicit error types defined in src/errors/11- Never swallow event processing exceptions in worker loopsQuick reference
- Cache hits reduce input token costs by up to 90% and dramatically lower turn response times.
- Edits to system instructions mid-session force a cache write miss on the immediately following turn.
- Model switches (e.g. toggling from Sonnet to Opus) invalidate existing prompt caches because cache states are model-specific.
Remember this
To maximize cache hit rates, avoid editing project configuration mid-session and maintain stable tool definitions.
Practical Token Cost Reduction Strategies
To prevent runaway token expenditure in large development teams, enforce these practical context management habits:
1. Use Scoped Tool Queries: Instead of viewing entire 5,000-line files, use line-range parameters or targeted grep calls.
2. Clear Stale Sessions: Run /clear or branch new worktrees when switching between unrelated bug tickets.
3. Inspect Active Window State: Use /context to view token distribution and identify bloated transcript sections.
4. Use Ignore Rules: Use .claudeignore to exclude massive log directories, build artifacts, and vendor files from agent searches.
Quick reference
- Unscoped
grepqueries across node_modules or dist folders can inject millions of unnecessary tokens into context. - Running
/contextperiodically highlights which files contribute most to token usage. - Using
.claudeignorekeeps auto-generated assets and lockfiles out of the search index.
Remember this
Proactive context hygiene — using scoped queries, ignore rules, and session clearing — dramatically reduces API token costs.
Hands-on Practice: Diagnose & Compact a Bloated Context
Practice optimizing context window usage with this guided exercise:
1. Setup: Open a terminal in your project repository and launch Claude Code.
2. Simulate Growth: Instruct the agent to read 3 large source files and run a test suite.
3. Inspect Context: Run /context to check total tokens consumed and inspect the breakdown.
4. Trigger Compaction: Run /compact "Focus exclusively on fixing test failures in consumer.test.ts".
5. Verify Pass Criterion: Run /context again and confirm that total token count has decreased by at least 50% while preserving the core task prompt.
Quick reference
- Confirm that the post-compaction context still retains file paths relevant to your active task.
- Verify that the
/contextcommand reflects a reduced input token count after compaction finishes. - Observe the reduction in latency on the next turn following successful compaction.
Remember this
Mastering /context and /compact empowers developers to maintain high performance in long-running coding sessions.
Key takeaway
Understanding the token economics and compaction mechanics inside Claude Code's context window is essential for building sustainable AI development workflows. By structuring CLAUDE.md to maximize prompt cache hits, establishing clean .claudeignore rules, and triggering /compact when context buffers grow large, software teams can maintain rapid turn responses and control token costs in long-running coding sessions.
Practice (20 min): Open Claude Code in a repository and instruct the agent to read 3 large source files and run a test suite. Run /context to inspect total token allocation. Trigger manual compaction with /compact "Focus on fixing consumer.test.ts", then verify via /context that context token consumption decreases by at least 50% while retaining critical task state.
Related Articles
Explore this topic