Context Token Flow
Relevant source files
The following files were used as context for generating this wiki page:
Context Token Flow describes the systematic process by which Claude Code loads and manages information within the context window for every message. This flow is categorized into sequential phases, starting from fixed system overhead to variable user configurations and conversation history. Understanding this architecture is critical for implementing effective Token Optimization Plan strategies. Sources: skills/token-optimizer/references/token-flow-architecture.md:1-5
The Loading Hierarchy
Claude Code follows a 13-level priority hierarchy when loading context. This sequence ensures that core system functionalities are available before applying user-defined rules and session-specific data. Sources: skills/token-optimizer/references/token-flow-architecture.md:214-230
The diagram above illustrates the sequential loading process where initial phases constitute the irreducible floor (~15,000 tokens), while subsequent phases are the primary targets for optimization. Sources: skills/token-optimizer/references/token-flow-architecture.md:10-85, skills/token-optimizer/references/token-flow-architecture.md:275-276
Phase 1: Core System (Fixed Overhead)
The core system constitutes a fixed floor of approximately 15,000 tokens. This includes the base system prompt (~3,000 tokens) and over 18 built-in tool definitions (~12,000 tokens) such as Read, Write, Edit, and Bash. These load with every message and cannot be directly optimized. Sources: skills/token-optimizer/references/token-flow-architecture.md:13-25
Phase 2: MCP Tools (Deferred Loading)
Model Context Protocol (MCP) tools are managed via Tool Search. Since January 2026, Tool Search is active by default, deferring full tool definitions until use. This reduces MCP overhead by ~85%. Sources: skills/token-optimizer/references/token-flow-architecture.md:28-44
| Component | Token Cost (With Tool Search) | Pre-Tool Search Cost |
|---|---|---|
| ToolSearch Base | ~500 tokens | N/A |
| Deferred Tool | ~15 tokens (name only) | 300-850 tokens (full def) |
| Total (50 tools) | ~1,250 tokens | 25,000 - 42,500 tokens |
Sources: skills/token-optimizer/references/token-flow-architecture.md:30-44
Phase 3: Skills and Commands
Skills and Commands use a progressive loading pattern. At startup, only the frontmatter (description and name) is loaded to populate the menu. The full body content loads only upon invocation. Sources: skills/token-optimizer/references/token-flow-architecture.md:46-56, skills/token-optimizer/references/token-flow-architecture.md:113-132
- Skills: ~100 tokens each (frontmatter)
- Commands: ~50 tokens each (frontmatter)
Phase 4: User Configuration (Always Loaded)
This phase includes global and project-specific files that load with every message. These are the primary targets for the Token Optimizer. Sources: skills/token-optimizer/references/token-flow-architecture.md:58-70
- Global CLAUDE.md: ~2,000 - 5,000 tokens (Target: <4,500 tokens).
- MEMORY.md: ~1,500 - 3,000 tokens (Subject to a 200-line auto-load cap).
- Project CLAUDE.md: ~10 - 1,500 tokens.
Subagent Context Inheritance
When a subagent is dispatched via the Task tool, it inherits the FULL system prompt of the orchestrator. This creates a multiplication effect in multi-agent workflows. Sources: skills/token-optimizer/references/token-flow-architecture.md:154-173
Anthropic data indicates that agent teams use approximately 7x more tokens than standard sessions due to this inheritance. Sources: skills/token-optimizer/references/token-flow-architecture.md:170-173
Context Window Lifecycle
As a conversation progresses, the context window fills until it reaches the auto-compaction threshold. Performance typically degrades before this threshold is met. Sources: skills/token-optimizer/references/token-flow-architecture.md:183-195
Quality Degradation Thresholds
| Fill Level | Impact |
|---|---|
| 0 - 30% | Peak performance |
| 50 - 70% | Minor degradation; manual /compact recommended |
| 70 - 85% | Noticeable corner-cutting |
| 85% + | Hallucinations and context drift |
Sources: skills/token-optimizer/references/token-flow-architecture.md:197-204
Prompt Caching Architecture
Claude Code utilizes prompt caching to reduce costs and latency. Caching follows a specific order: tools first, then system prompt, then chronological messages. Sources: skills/token-optimizer/references/token-flow-architecture.md:237-241
- Cache Reads: 90% cheaper than base input.
- Minimum Cacheable Size: 1,024 tokens (Sonnet/Opus) or 2,048 tokens (Haiku).
- TTL: 5 minutes (Pro/API) or 1 hour (Max plan).
Cache Breakpoints
Certain actions mid-session will invalidate the cache prefix, forcing a full context re-process:
- Adding or removing MCP tools mid-session.
- Switching models mid-session (caches are per model).
- Editing
CLAUDE.mdmid-session.
Sources: skills/token-optimizer/references/token-flow-architecture.md:250-256
Optimization Targets and Controls
Users can control context flow by optimizing specific components through manual intervention or the /token-optimizer skill. Sources: skills/token-optimizer/references/token-flow-architecture.md:89-111
| Target | Impact | Optimization Method |
|---|---|---|
| CLAUDE.md | High | Tiered architecture; move content to skills. |
| MEMORY.md | High | Dedup against CLAUDE.md; stay under 200-line cap. |
| Skills/Commands | Medium | Archive unused items outside the skills/ directory. |
| System Reminders | Partial | Use permissions.deny rules to exclude noisy files. |
Sources: skills/token-optimizer/references/token-flow-architecture.md:92-111, skills/token-optimizer/references/optimization-checklist.md:56-78
Tiered Content Architecture
To maintain a stable cache prefix, CLAUDE.md should be restructured into tiers:
- Tier 1 (Always Loaded): Identity, critical rules, and key paths (~300 lines).
- Tier 2 (On-Demand): Workflows and tool configs moved to skills.
- Tier 3 (Explicit Reference): Full guides and templates stored as reference files.
Sources: skills/token-optimizer/references/implementation-playbook.md:14-23
Conclusion
Context Token Flow management is a balance between maintaining necessary system awareness and preserving context window space for actual work. By utilizing Tool Search for MCP, tiered architectures for configuration files, and smart model routing for subagents, developers can significantly recover context window budget and maintain peak model performance. Sources: skills/token-optimizer/references/token-flow-architecture.md:280-315