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 $5/M input tokens (Opus 4.8), 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.
What's new in v4.5 — model auto-detection & the dollar leaks
The session's REAL model now drives everything, and the three biggest
avoidable dollar leaks get caught live:
- Model auto-detection. The budget hook reads the exact model id from the
session transcript — window size, pricing, the
/cco board, and Read-Cache
staleness thresholds all follow the model the session actually runs on
(Fable 5, Opus, Sonnet, Haiku). Switch /model mid-day; nothing miscalibrates.
config.model is only the fallback. Claude 5 family added to the pricing table.
- Bash & MCP output finally counted. Shell output was the biggest untracked
context consumer. PostToolUse now measures the actual
tool_response size
for every tool instead of stat-based guessing — and any single result ≥10K
tokens gets a one-line fix ("pipe through tail/grep", "read with offset/limit").
- Cache-break guard. Resume after a ≥5-min pause with a warm context and the
hook names what that break just cost (
re-warming 150K of context ≈ $0.86 extra)
— the prompt cache TTL is 5 minutes, and a broken cache re-bills your whole
context at 12.5× the cached rate. Batch pauses; /compact before stepping away.
- Context-rot warning. On 1M-window models a one-shot notice fires at ~350K
context: quality degrades in the ~300-400K "dumb zone" long before the window
fills. Budget-% warnings can't catch this; a quality signal can.
- Observation → rule, automatically. Files read-but-unused in 3+ sessions now
surface in the hook path once per session (when the recurring waste is ≥30K
tokens) with the exact
/cco-shield apply fix — previously you had to run the
CLI to see them.
- CLAUDE.md size nudge. Project + user memory over 200 lines → a one-shot
pointer to
/cco-claudemd. Memory loads into every prompt; it's the most
expensive place for bloat.
- The headline. Session-end summary now leads with the number that matters:
★ CCO saved $654.36 this session — 86% of what it would have cost.
What's new in v4.3 — cache economics & a politer coach
- Real cache-aware pricing. Session cost is now computed at true prompt-cache
rates (cache reads bill at 10%, writes at 125% of input) from exact transcript
usage. The
/cco board gains a Cache line: hit rate, $ saved vs uncached,
and cache breaks — moments a >5-min pause or a mid-session CLAUDE.md edit
went and re-wrote your whole context at the 1.25× rate, with the extra $ shown.
- NEW
/cco-overhead. Every session starts with a fixed payload — system
prompt, tool schemas, MCP servers, agents, CLAUDE.md — paid before you type a
word. This audit measures it from ground truth (first-turn API usage), itemizes
what's measurable locally, and tells you what to trim. Baseline cuts repay in
every session.
- Prompt Coach stops grading conversation. "спасибо, всё ок" is no longer an
F-grade prompt with injected advice to "name the file you want changed". The
coach classifies chat / question / task, coaches only tasks, goes easier on
short follow-ups — and now understands Russian.
/cco-shield apply. Files wasted in 3+ sessions become .contextignore
rules with one command — observation closes into a permanent rule.- Self-calibrating estimates. Real transcript totals teach the token
estimator each codebase's drift (EMA, clamped) — estimates get honest on
their own.
- Delegation advisor. A long read-only exploration streak in the main
context triggers a one-time hint to fan it out to a subagent instead.
What's new in v4.2 — ground truth
- Real token counts. The budget hook now reads exact API usage from the
Claude Code session transcript instead of estimating by character count.
Budget % and the
/cco board show real context usage whenever the transcript
is readable (real numbers drop the ~ prefix); estimation stays as fallback.
- Race-free state. The tracker/budget hooks are serialized (they shared a
notice ledger and clobbered each other), and concurrent session finalization
is guarded by an atomic file lock — no more lost global stats.
- A dozen bug fixes —
$NaN in /cco-digest, 3×-overstated costs in
/cco-export and /cco-claudemd, a benchmark that measured an empty
structure, O(n²) state rewrites, and more. See CHANGELOG.md.
What's new in v4.1 — honest & quiet
v4.1 answers one question: does it really save tokens, or just say it does? It
makes the optimizer honest and stops it from spending the context it's meant
to protect.
- Silent-by-default hooks. A context optimizer that narrates on every tool
call spends the tokens it claims to save. The per-tool-call hooks now stay
quiet unless a message is actionable (e.g. "90% budget → /compact"), capped
at a few advisory lines per session. The self-congratulatory "CCO makes your
budget 1.4x effective" line is gone.
- Honest NET savings.
/cco now reports net = tokens saved by the cache
minus the tokens CCO's own messages injected. Savings are counted by each
file's real size (a re-read of a 30-line file no longer credits "18K saved").
If the optimizer is ever net-negative, the dashboard says so.
- Big-file map-then-load. On the first full read of a very large file
(>1500 lines ≈ 14K+ tokens), the cache returns the file's structural map
once — so Claude reads the section it needs instead of slurping the whole file.
Read it again to load it fully. One-shot, configurable (
bigFileDigest).
What's new in v4.0 — Opus 4.8
v4.0 makes the plugin Opus 4.8-aware, adds a flagship Context Control Center,
and corrects the model facts.
NEW: Context Control Center — everything in one screen (/cco)
/cco is now a single, live dashboard instead of just a heatmap:
CONTEXT CONTROL CENTER opus-4.8 · 1M
────────────────────────────────────────────────────────────
Budget ▓▓▓▓▓▓▓░░░ 142K / 200K (71%) $0.84
Saved +58K tokens by cache → 1.41x effective (12 reads blocked)
Waste ▓▓░░░░░░░░ 18% (3 cold files)
Prompt last grade: B (add a file path to be specific)
────────────────────────────────────────────────────────────
▶ Task #4 refactor login flow · ~31K · $0.155
✓ #3 add OAuth provider · ~22K
────────────────────────────────────────────────────────────
⚡ Free ~22K: drop legacy/old_api.ts, vendor/build.js → /compact
📦 Pack minimal context: /cco-pack "refactor login flow"
One screen ties together budget %, $ spent, tokens saved (effectiveness
multiplier), waste, last prompt grade, the active task's cost, and ready-to-run
actions — all from data the optimizer already tracks. Nothing to configure.
NEW: Organize work by task (/cco-task)
Track tokens and cost per task, not just per session:
$ /cco-task add "refactor login flow" # start a task
$ /cco-pack "refactor login flow" # load only the files it needs
…work…
$ /cco-task done # freezes the task's token/$ total
While a task is active, session tokens are attributed to it, so /cco shows
exactly what each task costs. One active task per project; starting a new one
finalizes the previous one automatically.
NEW: Auto-Optimizer session report
At session end the optimizer prints what it saved you:
CCO saved you 71K tokens this session (~$0.36).
Your 200K budget worked like 271K (1.36x).
Model & correctness updates
- Opus 4.8 is now the default model (
opus-4.8). Opus 4.7 is still fully supported.
- Pricing corrected: Opus 4.7/4.8 are $5/M input, $25/M output — and deliver the
full 1M context window at that standard price. There is no 1M "premium tier" and no
surcharge. The old
opus-4.7-1m $22.50/$112.50 claim was wrong and has been removed;
opus-4.7-1m / opus-4.8-1m / opus-extended remain only as back-compat aliases that now
map to the standard $5/$25 1M Opus.
- Sonnet 4.6 is now 1M context ($3/M input, $15/M output) — previously mislabelled 200K.
Haiku 4.5 stays 200K ($1/$5).
- CI/test fix: hook modules used to read stdin on import, which hung the test suite
(v3.6.0 CI runs timed out at 6h). The stdin-reading
main() is now guarded with
isMainModule(), so importing a hook for unit testing no longer blocks.
What's new in v3.6 — Opus 4.7 update
The most expensive token leak isn't redundant reads — it's weak prompts that send Claude
reading 20 files to guess what you wanted. v3.6 attacks both sides of the problem.
NEW: Prompt Coach — grade and improve every prompt before it runs
A UserPromptSubmit hook scores your prompt on four dimensions and silently injects
suggestions for Claude when the score is below 80:
[prompt-coach] Prompt quality: D (38/100).
Suggestions to make this prompt produce better results:
- Name the specific file(s), function(s), or module(s) you want changed.
- Bound the scope: instead of "all bugs / rewrite everything", pick one concrete failure.
- State the success condition: what tests pass? what error disappears?
Run /cco-coach to grade an arbitrary prompt or see your prompt history (with average score).
Strong prompts produce sharper edits, fewer reads, lower bills. The coach is deterministic
and runs locally — no model call, no telemetry.
NEW: Smart Context Pack — optimal file set for your task
$ /cco-pack "refactor login flow to support OAuth"
SMART CONTEXT PACK
Files proposed: 7
Est. tokens: 18.4K (24% of context budget cap)
1. src/auth/login.ts (relevance 100, ~3.2K tokens)
reason: mentioned in prompt
read: offset=42, limit=120 — around `function handleLogin()`
2. src/auth/oauth.ts (relevance 85, ~2.1K tokens)
reason: modified in git working tree
read: full file
3. src/auth/session.ts (relevance 65, ~1.8K tokens)
reason: historically useful (edited in 8/12 sessions)
read: offset=0, limit=80
...
Mentioned files + git diff + historical patterns + keyword match → ranked, token-budget aware.
Stops at 25% of your effective context. With Opus 4.8's 1M window that's 250K of "safe to load now".
NEW: 1M context support — standard on Opus
/cco-budget model opus-4.8
Opus 4.7/4.8 deliver the full 1M window at the standard $5/$25 price — no premium tier, no
surcharge. Switching models still retunes the entire plugin:
- Read Cache staleness thresholds scale — 100K/40-files/10min instead of 20K/8-files/10min,
so you don't get false re-reads in massive contexts.
- Cost calculation uses each model's real prices — Opus $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5.
- Budget warnings stop firing at 5% of a 1M window — they fire at the percentages of your
effective budget.
NEW: Real cost tracking (input + output)
Old behaviour: counted only input tokens. New: counts input AND output (Edit/Write content)
and uses the model's real prices. Your reported cost is now the cost you actually pay.
NEW: MCP tool tracking
PostToolUse matchers now include mcp__* — Linear, Slack, GitHub, Postgres, etc. show up
in token reports alongside Read/Edit/Write.
NEW: /cco-doctor — health check
✔ versions in sync (plugin.json vs package.json) — v4.2.0
✔ hooks.json is valid JSON — 6 event types wired
✔ data directory writable — ~/.claude-context-optimizer
✔ user config — model=opus-4.8, budget=200.0K, window=1.0M
Catches the "installed but nothing happens" class of issues in under a second.
Features
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
NEW: Project Anatomy — codebase map in one file
Run /cco-anatomy to generate a compact project map. Claude reads one file instead of opening twenty to understand the codebase.
# Project Anatomy: my-app
Generated: 2024-01-15 | 45 files | ~38K tokens if all read
## Structure
| Path | Lines | ~Tokens | Type |
|------|-------|---------|------|
| src/server.ts | 450 | 4.1K | source |
| src/routes/api.ts | 280 | 2.6K | source |
...
## Heaviest files (read these with offset/limit)
1. src/server.ts — 450 lines (~4.1K tokens)
NEW: ContextShield — proactive waste prevention
ContextShield runs as a PreToolUse hook and warns you before loading known-waste files. It checks historical patterns and suggests alternatives in real-time.
[context-shield] README.md went unused in 5 sessions (~12.4K tokens).
Use Grep to find specific content instead of full Read.
[context-shield] utils.js is usually edited with: tracker.js, budget.js.
Consider loading them together.
Run /cco-shield to see protection status and stats.
NEW: CLAUDE.md Analyzer — trim the bloat
Run /cco-claudemd to analyze your CLAUDE.md for token waste: duplicates, verbose patterns, oversized code blocks, excessive whitespace. Get concrete suggestions with estimated savings.
CLAUDE.MD ANALYSIS — /project/CLAUDE.md — 342 lines | ~2.9K tokens
──────────────────────────────────────────────────────────────
⚠ 3 duplicate line(s) found (~25 saveable)
● "please make sure to" found 4x — Simplify to: "Always X" (~12 saveable)
● Code block at line 45 is 38 lines — consider shortening (~233 saveable)
○ 28% empty/separator lines — reduce for token savings (~98 saveable)
POTENTIAL SAVINGS: ~368 tokens
NEW: Confidence Learning — smart pattern scoring
File patterns now have confidence scores (0.0-1.0) based on session count, usefulness consistency, and recency. High-confidence patterns produce stronger recommendations; old unused patterns decay naturally.
HTML Dashboard Export — Chart.js analytics
Run /cco-export html to generate a static HTML dashboard you can open in any browser:
- Waste trend line chart
- Token usage bar chart
- Project breakdown doughnut
- Edits-per-session timeline
Context Control Center — everything in one screen
Run /cco for the live board: budget %, $ spent, tokens saved by the cache (effectiveness
multiplier), waste/cold files, last prompt grade, the active task's cost, and ready-to-run
actions (what to drop → /compact, what to /cco-pack). Drill into the per-file heatmap —
green = useful, red = waste — for detail.
Token ROI Report — full analytics across sessions
Run /cco-report for a comprehensive dashboard: total tokens, waste ratio, cost estimates, trends, and actionable recommendations.
Efficiency Score — gamified optimization
Run /cco-digest for a weekly efficiency grade (S/A/B/C/D/F) with breakdown by precision, edit ratio, search accuracy, and focus.
Token Budget — never overspend
Set a token budget and get real-time warnings as you approach the limit. Auto-compact kicks in at 80%, critical alerts at 90%.
[context-budget] 70% of budget used (~70K/100K) | Est. cost: $1.050 (opus)
[context-budget] ⚡ Auto-compact recommended — 80% budget used.
[context-budget] You can free ~8.2K tokens with /compact:
drop README.md (~2.4K), tsconfig.json (~1.1K), package.json (~320)
Git-Aware Suggestions — smart context loading
Run /cco-git and the plugin analyzes your git diff, finds related test files, configs, and historically useful files — then suggests exactly what to load.
Context Templates — presets for common tasks
Create reusable context sets for different task types:
/cco-templates create bug-fix # Save files you always need for bug fixes
/cco-templates apply bug-fix # Load them instantly next time
Smart Loader Skill — automatic suggestions
The plugin learns from your behavior. When you start a new task, it silently suggests files you'll probably need based on historical patterns. No configuration required.
All Commands
When installed as a plugin, commands are namespaced: /claude-context-optimizer:cco. With --plugin-dir, they're also available as /cco.
| Command | Description |
|---|
/cco | Context Control Center — one screen: budget, $ spent, tokens saved, waste, prompt grade, active task, actions |
/cco-task [add|list|done] | NEW — organize work by task; tracks tokens + $ per task |
/cco-report | Full ROI report — stats, trends, waste analysis, recommendations |
/cco-roi | ROI calculator — $/month savings per model, effective-context multiplier |
/cco-digest [days] | Efficiency digest — score, grade, cost analysis (default: 7 days) |
/cco-budget [status|set|model|auto] | Token budget — configure limits, cost model, auto-compact |
/cco-git | Git-aware suggestions — smart file loading based on diff |
/cco-templates [list|create|apply|delete] | Context templates — reusable file sets for task types |
/cco-export [md|html] | Export reports — Markdown or static HTML dashboard |
/cco-clean | Cleanup — remove old tracking data |
/cco-shield [suggest|apply] | ContextShield status; NEW — turn waste history into .contextignore rules |
/cco-overhead | NEW — audit the fixed baseline every session starts with (system prompt, MCP, agents, CLAUDE.md) |
/cco-claudemd | CLAUDE.md analyzer — find and fix token bloat |
/cco-anatomy | Project anatomy — compact codebase map with file sizes and token estimates |
/cco-replay [N] | Session replay — recent session summaries for quick context recovery |
/cco-coach [prompt] | NEW — Prompt quality score (S/A/B/C/D/F) + concrete suggestions to improve |
/cco-pack [task] | NEW — Build optimal context pack for a task: ranked files with offset/limit |
/cco-doctor | — Plugin health check (versions, hooks, data dir, model config) |
Installation
Option 1 — Marketplace (recommended)
claude plugin marketplace add egorfedorov/claude-context-optimizer
claude plugin install claude-context-optimizer@cco
Then restart Claude Code. This installs the plugin from its self-contained
marketplace manifest — persistent across sessions, with full functionality:
skills, auto-tracking hooks, Read Cache, ContextShield, and budget alerts. No
local paths to configure.
Option 2 — Plugin directory (local dev)
git clone https://github.com/egorfedorov/claude-context-optimizer.git ~/claude-context-optimizer
claude --plugin-dir ~/claude-context-optimizer
To make it persistent, add to ~/.claude/settings.json:
{
"plugins": [
"~/claude-context-optimizer"
]
}
Use this when you want to edit the plugin locally and see changes live.
Option 3 — Skills CLI
npx skills add https://github.com/egorfedorov/claude-context-optimizer
Installs skills globally to ~/.agents/skills/ and symlinks them to Claude Code. Works with Amp, Cline, Codex, Cursor, Gemini CLI, and other compatible agents.
Note: Skills CLI installs skill prompts only. Auto-tracking hooks (Read Cache, ContextShield, budget alerts) require the plugin directory installation (Option 1) to function.
Updating
claude plugin update claude-context-optimizer@cco
Then restart Claude Code to apply the update.
Requirements
- Node.js >= 18
- Claude Code (with plugin/skills support)
- A POSIX shell for hooks (macOS/Linux out of the box; Git Bash or WSL on Windows)
Install & Forget
Once installed, the plugin works automatically — no commands needed:
Before every file re-read (Read Cache):
- Blocks re-reading files that haven't changed since last read in this session
- Allows automatically if the file was modified or a new section is requested
On session start: Weekly savings streak, warnings about consistently wasted files, auto-generated template notifications.
Before every file read (ContextShield): Checks if the file was wasted in 3+ past sessions, suggests Grep alternatives, shows co-occurrence groups.
On every file read: Warns on 3+ reads without edits (suggests offset/limit), tiered warnings for large files (200+ soft, 500+ strong).
On budget thresholds (50%, 70%, 85%, 95%): Usage percentage, cost estimates, and at 85%+ lists specific files to drop with exact token savings.
On session end: Compares waste vs recent average, updates pattern database.
After 5+ sessions: Auto-creates file templates from frequently edited files.
You literally just code. The plugin watches and helps.
How It Works
You use Claude Code normally
│
▼
┌─────────────────────┐
│ PreToolUse Hook │ Read Cache: blocks re-reads of unchanged files.
│ read-cache.js │ ContextShield: warns about historically wasted files.
│ context-shield.js │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ PostToolUse Hook │ Silent. Runs on every Read/Edit/Write/Glob/Grep/Agent.
│ tracker.js │ Records: file path, line count, token estimate, timestamp.
│ budget.js │ Tracks token accumulation, warns at thresholds.
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Session Store │ ~/.claude-context-optimizer/sessions/<id>.json
│ Per-file tracking │ Reads, edits, usefulness score, confidence score.
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ SessionEnd Hook │ Finalizes session. Computes waste. Updates patterns DB.
│ Confidence Learning │ Patterns scored 0.0-1.0, decay over time.
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Reports & Insights │ /cco, /cco-report, /cco-digest, /cco-claudemd
│ HTML Dashboard │ Static Chart.js analytics, open in any browser
│ ContextShield │ Proactive waste prevention before file reads
│ Smart Suggestions │ Confidence-scored recommendations
└─────────────────────┘
What counts as "useful"?
A file is useful if: edited after reading (+3 per edit), read multiple times (+0.5 per re-read, diminishing), or partially read with offset/limit (+1 bonus).
A file is wasted if: usefulness score is zero or negative (read but never edited, no re-reads). Large files (100+ lines) read 3+ times without edits get a penalty.
Token estimation
Tokens are estimated using extension-specific ratios (e.g., 3.8 chars/token for JS/TS, 4.2 for Markdown, 3.2 for JSON) applied to line counts. Not exact, but consistent enough for comparative analysis.
Data Storage
~/.claude-context-optimizer/
├── sessions/ # Per-session tracking data (JSON)
├── budget/ # Per-session budget state
├── templates/ # User-defined context templates
├── exports/ # Exported reports (MD/HTML)
├── read-cache/ # Per-session read cache state
├── prompts/ # Per-session prompt grades (Prompt Coach)
├── config.json # Budget and preference settings
├── tasks.json # Per-task register (tokens/$ per task)
├── patterns.json # Cross-session file usage patterns
└── global-stats.json # Aggregate statistics
Plugin Structure
claude-context-optimizer/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── src/
│ ├── utils.js # Shared: constants, classification, model costs, atomic JSON I/O
│ ├── dashboard.js # NEW — Context Control Center (one-screen board + session summary)
│ ├── tasks.js # NEW — per-task register (tokens/$ per task)
│ ├── read-cache.js # Smart Read Cache (adaptive 1M-aware staleness)
│ ├── contextignore.js # .contextignore: pattern-based file blocking
│ ├── replay.js # Session Replay: recent session summaries
│ ├── anatomy.js # Project Anatomy: compact codebase map generator
│ ├── tracker.js # Core: file & token tracking engine + session summaries
│ ├── context-shield.js # ContextShield: PreToolUse waste prevention
│ ├── claudemd-analyzer.js # CLAUDE.md token bloat analyzer
│ ├── budget.js # Token budget monitor (input + output, model-aware costs)
│ ├── digest.js # Efficiency score & weekly digest
│ ├── git-context.js # Git-aware context suggestions
│ ├── report.js # ROI report generator
│ ├── roi.js # ROI calculator ($/month savings per model)
│ ├── notices.js # Notice ledger — caps the plugin's own context spend
│ ├── file-digest.js # Structural file map (map-then-load for big files)
│ ├── simulate-savings.js # Savings simulator over recorded sessions
│ ├── export.js # Chart.js HTML dashboard exporter
│ ├── prompt-coach.js # UserPromptSubmit hook + CLI: prompt classification & quality scoring
│ ├── smart-pack.js # Optimal file pack builder (git + history + keywords)
│ ├── overhead.js # NEW — session baseline overhead audit (/cco-overhead)
│ └── doctor.js # Health check CLI
├── skills/
│ ├── cco/SKILL.md # /cco — Context Control Center (one-screen board)
│ ├── cco-task/SKILL.md # NEW — /cco-task — per-task tokens/$ tracking
│ ├── cco-report/SKILL.md # /cco-report — full ROI report
│ ├── cco-roi/SKILL.md # /cco-roi — ROI calculator
│ ├── cco-replay/SKILL.md # /cco-replay — session replay
│ ├── cco-digest/SKILL.md # /cco-digest — efficiency digest
│ ├── cco-budget/SKILL.md # /cco-budget — budget manager
│ ├── cco-git/SKILL.md # /cco-git — git suggestions
│ ├── cco-export/SKILL.md # /cco-export — report export
│ ├── cco-templates/SKILL.md # /cco-templates — template manager
│ ├── cco-clean/SKILL.md # /cco-clean — data cleanup
│ ├── cco-shield/SKILL.md # /cco-shield — ContextShield status
│ ├── cco-claudemd/SKILL.md # /cco-claudemd — CLAUDE.md analyzer
│ ├── cco-anatomy/SKILL.md # /cco-anatomy — project anatomy
│ ├── cco-coach/SKILL.md # NEW — /cco-coach prompt quality grader
│ ├── cco-pack/SKILL.md # NEW — /cco-pack smart context pack
│ ├── cco-doctor/SKILL.md # /cco-doctor health check
│ ├── cco-overhead/SKILL.md # NEW — /cco-overhead session baseline audit
│ └── smart-loader/SKILL.md # Auto-suggestion skill (model-invoked)
├── agents/
│ └── context-analyzer.md # Deep analysis agent
├── hooks/
│ └── hooks.json # Hook configuration
├── assets/ # SVG visuals for README
├── docs/
│ └── index.html # Landing page (GitHub Pages)
└── package.json
Privacy
This plugin:
- Tracks only file paths and line counts — never file contents
- Stores everything locally in
~/.claude-context-optimizer/
- Sends zero telemetry — no network calls, no analytics, no tracking
- Can be fully wiped with
/cco-clean --reset-all
Your data never leaves your machine. Period.
FAQ
Q: Does this slow down Claude Code?
A: No. Hook scripts run asynchronously and typically complete in <10ms.
Q: How accurate are the token estimates?
A: They use a ~4 tokens/line heuristic. Not exact, but consistent across sessions for reliable trends.
Q: Can I use this with Claude Sonnet / Haiku / Opus 4.7 / Opus 4.8?
A: Yes. /cco-budget model haiku-4.5 / sonnet-4.6 / opus-4.7 / opus-4.8 — each retunes
context window, prices, and Read Cache staleness thresholds. Opus 4.7/4.8 and Sonnet 4.6 are all
1M context; Haiku 4.5 is 200K. (opus-4.7-1m / opus-4.8-1m still work as back-compat aliases —
1M is standard now, so there's no surcharge.)
Q: Does Prompt Coach call any LLM?
A: No. It uses deterministic local heuristics (regex + scoring). Zero API calls,
zero latency added to your prompt submission, runs in <5ms.
Q: Will this work with subagents?
A: Yes. The PostToolUse hook fires for all tool calls, including those made by subagents.
Q: Does Read Cache break anything?
A: No. It only blocks truly redundant reads — same file, same range, no modifications since last read. If the file changed or you request a different section, the read goes through normally.
Support Development
context-optimizer is 100% free and open source. No paywalls, no premium tiers, no telemetry. If it saves you money on tokens, consider supporting development:
| Chain | Address |
|---|
| BTC | bc1q428exz5t2h9rzk7z5ya70madh0j3rs6h4gfgyd |
| ETH (ERC-20) | 0xB3f0C8e42B7cA9d65920cEfe82e3fef1B5C9d0C9 |
| SOL | 8ctK8nt3CBkPZGfWQXX8TsnqUYUy4JAbT1EMhr8rsQxm |
Contributing
PRs welcome: better token counting (AST-based), VSCode heatmap overlay, team pattern sharing, /cost integration, multi-language CLAUDE.md analysis.
License
MIT — do whatever you want with it.
