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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add jbdamask/john-claude-skills.

Contents

Discovered from source

Skills 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 /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

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.md in 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

  1. Locate the project's chat history directory under ~/.claude/projects/
  2. Run the analysis script to parse all JSONL session files
  3. Interpret the results and identify the biggest context consumers
  4. 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/project becomes -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:

  1. Top 3 context consumers - What categories dominate and by how much
  2. Actionable items - What the user can change in their workflow
  3. 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:

  1. Overview - Session count, total size, average session size
  2. Top Consumers - The 3-5 biggest categories with percentages
  3. File Re-Read Hotspots - Top 5 most re-read files
  4. Recommendations - Prioritized list of optimizations with expected impact

Sponsors

Details

Marketplace
jbdamask/john-claude-skills
Source
plugins/context-analyzer
Category
Community

More from jbdamask/john-claude-skills

All 4