Claude Context Optimizer

Claude Context Optimizer (CCO) is a Claude Code plugin that tracks every file read, edit, and search during a session, scores which files were actually useful, and intervenes to reduce wasted context. It runs as a set of hooks: a PreToolUse Read Cache blocks re-reads of files that have not changed since they were last loaded, a ContextShield warns before loading files that went unused in past sessions, a PostToolUse tracker records per-file token estimates, and a SessionEnd hook computes waste and updates a pattern database.

A file counts as useful if it is edited after reading, re-read, or read partially with offset and limit; a file read but never acted on counts as waste. Patterns carry confidence scores (0.0 to 1.0) based on session count, consistency, and recency, and files wasted in 3 or more sessions can be turned into .contextignore rules. The budget hook reads exact API usage and the model ID from the session transcript, so context-window size, pricing, and cache-staleness thresholds follow the model the session runs on; prompt-cache reads and writes are priced at their own rates, and cache breaks after a pause longer than 5 minutes are reported with their cost.

Beyond the hooks, /cco opens a Context Control Center showing budget, spend, tokens saved, waste, prompt grade, and the active task. Further commands audit the fixed per-session overhead (system prompt, MCP servers, agents, CLAUDE.md), analyze CLAUDE.md for duplicates and oversized blocks, build a ranked file pack for a task, grade prompts, and export Markdown or HTML dashboards. Requires Node.js 18 or later and a POSIX shell for hooks (Git Bash or WSL on Windows).

Features

• Read Cache: blocks same-range re-reads of unchanged files; returns a structural map on the first full read of files over 1,500 lines
• .contextignore: project-level and global glob rules that block reads of lockfiles, build output, and generated code
• ContextShield: pre-read warnings for historically wasted files, co-occurrence hints, and /cco-shield apply to convert waste history into rules
• Model-aware budget: exact transcript token counts, per-model window and pricing, auto-compact prompts at 80% and 90%, and a context-rot notice near 350K on 1M-window models
• Cache economics: hit rate, savings versus uncached, and cache-break costs on the /cco board
• Tool cost learning: /cco-tools budgets MCP and Agent calls from observed result sizes after three calls
• Team pattern sharing: /cco-patterns export/import exchanges relative-path digests, stored as a separate prior rather than merged counts
• Prompt Coach: grades task prompts (S to F) and suggests rewrites; skips conversational messages; supports Russian
• Analysis commands: /cco-overhead, /cco-claudemd, /cco-anatomy, /cco-pack, /cco-git, /cco-replay, /cco-report, /cco-digest
• Tunable thresholds: /cco-config exposes 11 range-validated knobs such as rereadWarnAt, bigFileLines, and staleTimeMs
• Windows support: path encoding, CRLF .contextignore parsing, and backslash globs handled since v4.7