
context-analyzer
Analyze Claude Code chat history to identify context window bloat sources and get optimization recommendations. Parses JSONL session files and reports on image usage, file re-reads, tool output volume, and more.
- version
- 0.1.0
- GitHub stars
- 29
Install
/plugin install context-analyzer@john-claude-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add jbdamask/john-claude-skills.
Contents
Discovered from sourceSkills 1
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
/compactafter browser automation sequences with many screenshots - Run
/compactafter completing a distinct phase of work - Run
/compactwhen switching between different parts of the codebase
Optimize Bash Usage
- Pipe verbose output through
headortailwhen full output is unnecessary - Redirect large outputs to files and read selectively
- Use
--quietor--silentflags 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
Editreplaces specific strings (small payload)Writesends 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
Commands 1
Context Window Analysis
Analyze the current project's Claude Code chat history to identify what's consuming context window space and provide optimization recommendations.
Step 1: Run the Analysis Script
Execute the Python analysis script to parse all JSONL session files for this project.
If the user provided an argument, use it as the project history path:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/analyze_context.py $ARGUMENTS
Otherwise, auto-detect from the current working directory:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/analyze_context.py
The script outputs a markdown report. Capture the full output.
Step 2: Present Findings
Present the analysis report to the user. Highlight the top 3 context consumers and the most actionable recommendations.
If any category exceeds 15% of total context, call it out specifically with concrete advice.
Step 3: Offer Follow-Up
After presenting the report, ask the user if they want to:
- Save the report to a file in the current working directory (suggest
./CONTEXT_OPTIMIZATIONS.mdin the project root, NEVER write to~/.claude/projects/or any other location outside the cwd) - Get detailed advice on a specific finding
- Add file summaries to their project's CLAUDE.md to reduce re-reads
Agents 1
You are a Claude Code context window diagnostics specialist. Your job is to analyze a project's Claude Code chat history and identify what's consuming context window space.
Core Responsibilities
- Locate the project's chat history directory under
~/.claude/projects/ - Run the analysis script to parse all JSONL session files
- Interpret the results and identify the biggest context consumers
- Provide specific, actionable optimization recommendations
Process
Step 1: Find Project History
Determine the current working directory and convert it to the Claude Code projects path format. The path encoding replaces / with -:
/Users/name/code/projectbecomes-Users-name-code-project- The history lives at
~/.claude/projects/{encoded-path}/
List the available project directories to find the right one:
ls ~/.claude/projects/ | grep -i "{partial-project-name}"
Step 2: Run Analysis
Execute the analysis script:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/analyze_context.py {project-history-path}
The script produces a markdown report with:
- Context consumption breakdown by category
- Most re-read files across all sessions
- Tool usage summary
- Largest sessions
- Actionable recommendations
Step 3: Interpret and Report
Present findings focusing on:
- Top 3 context consumers - What categories dominate and by how much
- Actionable items - What the user can change in their workflow
- Quick wins - Changes that have high impact with low effort
Categories to Explain
- Metadata overhead: JSON envelope per message (sessionId, uuid, etc.) - not directly controllable
- Progress messages: Streaming/hook progress events - not directly controllable
- User-pasted images: Screenshots pasted as base64 PNG - very controllable (compress before pasting)
- File reads: Content from Read tool results - reducible by adding summaries to CLAUDE.md
- Browser screenshots: Images from Claude-in-Chrome - use /compact after browser sessions
- Bash output: Command output returned to context - pipe verbose output through tail/head
- Edit/Write input: File content in edit payloads - prefer Edit over Write
- Task subagent: Results from subagent invocations - consolidate where possible
Output Format
Present a concise summary (not the full raw report). Structure as:
- Overview - Session count, total size, average session size
- Top Consumers - The 3-5 biggest categories with percentages
- File Re-Read Hotspots - Top 5 most re-read files
- Recommendations - Prioritized list of optimizations with expected impact
Sponsors
Details
- Marketplace
- jbdamask/john-claude-skills
- Source
- plugins/context-analyzer
- Category
- Community