| name | Context Optimization |
| description | This skill should be used when the user asks about "context window optimization", "reduce context usage", "context is filling up", "running out of context", "context bloat", "optimize my sessions", "why is context so large", or when providing advice on how to keep Claude Code sessions efficient. Provides knowledge about what consumes context and strategies to minimize waste. |
| version | 0.1.0 |
Context Optimization for Claude Code
Overview
Claude Code sessions have a finite context window. Understanding what consumes context and how to minimize waste keeps sessions productive longer. This skill provides patterns and strategies for context-efficient workflows.
What Consumes Context
Every interaction in a Claude Code session adds to context. The main consumers, ranked by typical impact:
1. Message Metadata Overhead (30-40%)
Every message carries a JSON envelope with sessionId, uuid, cwd, gitBranch, version, and other fields. This is not directly controllable but is the largest single category.
2. Progress/Streaming Messages (20-30%)
Hook progress events and streaming data accumulate significantly in long sessions. Not directly controllable.
3. User-Pasted Images (10-20%)
Screenshots pasted into chat are encoded as base64 PNG, inflating size ~33% over raw bytes. A single full-screen PNG screenshot can consume 500 KB to 2 MB of context.
4. File Read Results (5-10%)
Every Read tool invocation returns the full file content into context. Re-reading the same file multiple times multiplies its impact.
5. Browser Screenshots (3-5%)
Claude-in-Chrome screenshots are JPEG (~50-80 KB each) but accumulate in browser-heavy sessions.
6. Edit/Write Payloads (2-3%)
File content included in Edit and Write operations.
7. Bash Output (1-3%)
Command output returned to context. Usually small per-call but adds up with heavy Bash usage.
Optimization Strategies
Compress Screenshots Before Pasting
- Resize to ~800px wide before pasting
- Use JPEG format instead of PNG where possible
- Consider using Claude-in-Chrome's screenshot tool (produces ~50-70 KB JPEG) instead of pasting full-screen PNGs (500 KB-2 MB)
- On macOS, use Preview or a keyboard shortcut to downscale clipboard images
Reduce File Re-Reads
- Add structural summaries of frequently-referenced files to the project's
CLAUDE.md
- For infrastructure files (CloudFormation, Terraform, etc.), document resource names and relationships in
CLAUDE.md
- Keep documentation files (DEVLOG.md, CHANGELOG.md) concise; archive old content
Use /compact Proactively
- Run
/compact after browser automation sequences with many screenshots
- Run
/compact after completing a distinct phase of work
- Run
/compact when switching between different parts of the codebase
Optimize Bash Usage
- Pipe verbose output through
head or tail when full output is unnecessary
- Redirect large outputs to files and read selectively
- Use
--quiet or --silent flags where available
Use .claudeignore
- Add build artifacts, node_modules, and generated files
- Add large data files that should not be searched
- Add log files and temporary outputs
Prefer Edit Over Write
Edit replaces specific strings (small payload)Write sends the entire file content (large payload)- For modifications to existing files, Edit is more context-efficient
Consolidate Subagent Usage
- Each Task/subagent invocation adds its result to context
- Combine related queries into a single subagent call when possible
- Use targeted prompts that return concise results
Diagnosing Context Issues
To analyze what's consuming context in a specific project, run:
/context-analyzer:analyze-context
This parses the project's JSONL chat history files in ~/.claude/projects/ and produces a detailed breakdown with per-category sizes, most re-read files, and targeted recommendations.
For programmatic access, the analysis script supports JSON output:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/analyze_context.py --json
Common Anti-Patterns
Re-Reading the Same File Every Turn
Problem: Claude reads types.ts or api.ts every time it needs to reference types.
Fix: Add key type definitions or API surface to CLAUDE.md.
Pasting Full-Screen Screenshots
Problem: Each PNG screenshot is 500 KB-2 MB in base64.
Fix: Crop to the relevant area and resize before pasting.
Long Browser Automation Sequences Without Compacting
Problem: 20+ screenshots from scroll-screenshot-click sequences fill context.
Fix: Run /compact after browser testing. Use read_page (accessibility tree) instead of screenshots when visual verification isn't needed.
Verbose Build/Test Output
Problem: Full test suite output or build logs dumped to context.
Fix: Pipe through tail -20 or grep for failures only.
Large Documentation Files Read on Every Session
Problem: DEVLOG.md or similar grows over time and is read at session start.
Fix: Keep it under 5 KB or move to Claude Code memory (~/.claude/projects/.../memory/).
Additional Resources
For detailed analysis methodology and report interpretation, see:
references/analysis-methodology.md — How the analysis script categorizes context consumption
