claude-context-optimizer

Stop burning tokens on files Claude never uses.

---

The Problem

The average Claude Code session wastes 30-50% of tokens on files that are read but never actually used. Every Read call consumes context — whether the file was relevant or not.

• A 200-line config file? 800 tokens gone.
• A README you glanced at once? 2,400 tokens burned.
• That package.json Claude reads "just in case"? 120 tokens, every time.

At $15/M tokens (Opus), a developer spending $100/month is lighting $30-50 on fire on irrelevant context.

The Solution

context-optimizer silently tracks every file read, edit, and search. It learns which files are actually useful and which are waste. Over time, it builds a profile of your coding patterns and tells you exactly where your tokens go — and how to stop wasting them.

---

Features

NEW: Smart Read Cache — block redundant reads automatically

The #1 token waste in Claude Code: re-reading the same file multiple times per session. Read Cache runs as a PreToolUse hook and blocks redundant reads when the file hasn't changed.

💾 [read-cache] tracker.js is already in context (983 lines, ~9.3K tokens saved).
   File unchanged — no need to re-read! Tip: use offset/limit to read a different section.

• First read: always allowed
• File modified since last read: allowed (detects via mtime)
• Different section (offset/limit): allowed if not already covered
• Agent subprocess reads: tracked separately — won't block reads in the main conversation
• Same file, same range, unchanged: blocked — saves 100% of those tokens

Typical savings: 30-60% fewer tokens per session from read deduplication alone.

NEW: .contextignore — block files you never need

Create a .contextignore file in your project root (like .gitignore) to permanently block wasteful reads. No more loading lockfiles, build output, or generated code.

# .contextignore
package-lock.json
yarn.lock
*.min.js
*.min.css
dist/**
node_modules/**
*.sql

🚫 [contextignore] package-lock.json matches pattern "package-lock.json" in .contextignore.
   Use Grep to search inside, or remove the pattern from .contextignore to allow reading.

• Project-level: .contextignore in your repo root
• Global rules: ~/.claude/.contextignore for patterns across all projects
• Supports globs: *.lock, dist/**, *.min.js, *.generated.*
• Copy .contextignore.example from the plugin to get started

NEW: Auto-Compact — automatic context cleanup

When your context budget reaches 80%, the plugin automatically tells Claude to run /compact instead of just showing a warning. At 90%, it becomes urgent.

[context-budget] ⚡ Auto-compact recommended — 80% budget used.
   Run /compact now to free ~12.5K tokens and keep the session efficient.
[context-budget] 🔴 Critical: 90% budget used (~90K/100K tokens).
   Run /compact immediately or the session will lose older context.

• Toggle with /cco-budget auto on or /cco-budget auto off
• Configurable thresholds in budget-config.json
• Smart rate-limiting — won't spam every single tool call

NEW: Session Replay — pick up where you left off

Every session automatically generates a summary saved to disk. Start your next session by running /cco-replay to see what was done before — no need to re-read files or guess context.

╔══════════════════════════════════════════════════════════════╗
║                    RECENT SESSION SUMMARIES                  ║
╚══════════════════════════════════════════════════════════════╝

[1] Session Mar 24 14:30 (12 min)
    Edited: src/read-cache.js, src/utils.js, README.md (3 files)
    Context: 45K tokens, 12 files read, 28% waste

[2] Session Mar 24 10:15 (25 min)
    Edited: src/tracker.js, src/budget.js (2 files)
    Context: 82K tokens, 18 files read, 15% waste