Claude Context Optimizer is a Claude Code plugin that tracks what each session reads, edits and searches, estimates the tokens each file costs, and uses that record to cut context waste. It runs as hooks: a PreToolUse hook blocks a repeat read of an unchanged file that is already in context and warns before loading files that went unused in past sessions, a PostToolUse hook records every Read, Edit, Write, Glob, Grep and Agent call, and a SessionEnd hook computes the session's waste and updates a patterns database.
A file counts as useful when it is edited after being read, re-read, or read in part with an offset and limit, and as waste when it is read but never acted on. Patterns carry a confidence score (0.0–1.0) from session count, consistency and recency, and decay over time. Read-only sessions (review, explanation, Q&A) record no waste. Tokens are estimated from extension-specific character ratios, and session cost is priced per model from the usage numbers in Claude Code's own transcript, with the active model (Opus, Sonnet, Fable, Haiku) detected per session.
Everything is stored locally as JSON. File paths and line counts are tracked, never file contents, and the plugin makes no network calls. Behavior thresholds are range-validated and tunable from a config command, and learned file patterns can be exported as a committed digest so a team shares them.
Features
- Read cache: blocks a repeat read of the same file and range when the file is unchanged, allows modified files and uncovered sections, and tracks agent subprocess reads separately
- Context ignore list: a gitignore-style file in the project root that blocks reads of lockfiles, build output and generated code outright
- ContextShield: warns before loading files that went unused in past sessions, suggests Grep instead of a full read, and can turn waste history into ignore rules
- Token budget and auto-compact: warnings as a budget fills, with a compact recommendation at 80% and a critical alert at 90%, rate-limited so it does not fire on every tool call
- Context Control Center: one screen with budget used, dollars spent, tokens saved, waste and cold files, the last prompt grade, the active task's cost and a per-file heatmap
- Prompt Coach: grades each prompt (S to F) and suggests concrete improvements before it runs
- Smart Context Pack: ranks the files for a stated task and proposes offset and limit ranges to read
- Task tracking: groups work by task and attributes tokens and cost to each, with state that survives a compact
- Session replay and project anatomy: a saved summary of each session for the next one, and a compact codebase map with sizes and token estimates per file
- Reports: a cross-session ROI report, a weekly efficiency grade, a per-model savings calculator, an audit of the fixed per-session baseline (system prompt, MCP, agents, CLAUDE.md) and a static HTML dashboard export
- CLAUDE.md analyzer: finds duplicate lines, verbose patterns, oversized code blocks and excess whitespace, with estimated savings
- Git-aware suggestions and templates: suggests files from the current diff plus related tests and configs, and saves reusable context sets per task type
