.contextignore

August 10, 2026 · View on GitHub

Stop burning tokens on weak prompts and redundant reads.
_{Model-aware for the whole Claude lineup — Fable 5, Opus, Sonnet, Haiku — detected per session, zero config.}

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.

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.

How it works

What's new in v4.9 — the optimizer learns, and the team shares

Your tools now price themselves. MCP and Agent costs were constants someone picked once — mcp__* ≈ 200 tokens in, Agent ≈ 500. Real results vary by orders of magnitude: a "list all issues" query and a one-row lookup are the same tool name and nowhere near the same cost. On MCP-heavy sessions the budget meter was guessing at its own biggest line item.

CCO already measured every tool result; now it remembers. After three calls a tool is budgeted from what it actually costs you:

/cco-tools
  tool                          calls      avg      max    total
   mcp__linear__list_issues        41    38.2K   112.0K     1.5M   ← where your budget really goes
   Bash                           380      133      342    50.5K
  · mcp__github__get_pr             2     4.1K     6.0K     8.2K   ← still on the constant

Pair it with /cco-overhead mcp: that finds servers you never call, this prices the ones you do. (#38)

Patterns travel with the repo. What CCO learns — which files are usually waste, usually useful, edited together — was locked to one machine. A teammate's fresh clone started blind and re-learned the same lessons by wasting the same tokens.

/cco-patterns export     # → .cco/patterns.digest.json — commit it
/cco-patterns import     # teammate, day one on a fresh clone

The digest carries relative paths and counts only — no file contents, no absolute paths, no home directory. Anything that can't be expressed relative to the project root is dropped, and the file is audited before writing and on import; a digest with absolute paths is rejected, not sanitized.

Imported data is stored as a separate prior and never merged into your own counts. That's deliberate: confidence means "how many sessions I observed this in", and folding someone else's sessions into it would make your own numbers a lie. The import fills in only where you have no evidence of your own. (#37)

This repo ships its own .cco/patterns.digest.json — clone it and /cco-patterns import to see the feature work on real data.

What's new in v4.8 — the metric gets honest, the knobs come out

Token estimates are per-language now. The headline "tokens saved" number was computed from one constant — 35 chars per line, for every file type. So I measured 6,344 real source files instead of guessing. .svg averages 100.5 chars/line (nearly 3x under-counted before), .css 25.3 and .txt 27.8 (over-counted), .ts 44. Notably the measurement contradicted my own priors: .json is 38.8, not the ~20 I expected. (#35)
/cco-config — 11 hardcoded knobs, now tunable. Re-read warning points, Read-Cache staleness, prompt-coach length bands, /cco-pack budget cap. Every value range-validated: a typo is ignored in favour of the default and flagged, never silently applied. (#39)
The decision logic is under test. The formatters had coverage; the code that decides what actually reaches your context didn't. Budget gating, cache-break detection, Read-Cache staleness and session waste classification are now pure, exported, and covered — 238 tests, up from 183. (#36)
Version drift can't ship again. marketplace.json quietly sat two releases behind; CI now fails on any mismatch.

What's new in v4.7 — Windows works

CCO quietly assumed POSIX paths. On Windows that broke four things at once, and none of them looked broken — they just reported less:

/cco-overhead said "no session transcripts found" even with transcripts right there. The cwd → folder encoding dropped \, : and spaces, so it looked in ~\.claude\projects\C:\Program Files\Git instead of …\projects\C--Program-Files-Git. Fixed — which also restores the CLAUDE.md/memory itemization that had been collapsing into "system prompt & tools (unattributed)". (#46)
.contextignore was inert on Windows. CRLF files left a \r on every pattern, so not one of them matched. Every lockfile you thought you'd excluded was still being counted. (#33)
Globs now understand \ — C:\proj\dist\a.js matches dist/**.
Project-root detection and path display are separator-aware, so reports stop leaking raw C:\… paths.

Plus a CONTRIBUTING.md with the platform rules, so this doesn't regress. 183 tests, green on Node 18/20/22.

Hooks still need a POSIX shell (Git Bash or WSL) — native Windows hooks are tracked on the roadmap.

What's new in v4.5 — model auto-detection & the dollar leaks

CCO session summary — real numbers from a real session
_{A real session's end-of-day summary. Measured, not marketing.}

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 \times -\text{overstated} \text{costs} \text{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.

Context Control Center

Token ROI Report — full analytics across sessions

Run /cco-report for a comprehensive dashboard: total tokens, waste ratio, cost estimates, trends, and actionable recommendations.

Token ROI Report

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.

Efficiency Score

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`	NEW — Plugin health check (versions, hooks, data dir, model config)
`/cco-config [show\|get\|set\|reset]`	NEW — tune the behavior thresholds below without editing source
`/cco-patterns [export\|import\|show]`	NEW — share learned file patterns with your team via a committed digest
`/cco-tools [show\|reset]`	NEW — what your tools really cost, learned from observed results

Tunable thresholds (`/cco-config`)

Stored under thresholds in ~/.claude-context-optimizer/config.json. Every value is range-validated; an out-of-range or misspelled entry is ignored in favour of the default and flagged with ! in /cco-config show, so a typo can never make a hook behave wildly.

Key	Default	What it changes
`rereadWarnAt`	3	reads of an unedited file before the first re-read warning
`rereadEscalateAt`	5	reads before the "put it in CLAUDE.md" escalation
`bigFileLines`	500	full-read line count that triggers the offset/limit warning
`mediumFileLines`	200	full-read line count that triggers the soft hint
`staleTokenRatio`	0.10	share of budget loaded after a file before Read Cache re-allows it
`staleFiles`	8	other files loaded after a file before it counts as evicted (at 200K)
`staleTimeMs`	600000	ms since last read before a cached file counts as stale
`promptMinWords`	8	word count below which the coach calls a prompt too vague
`promptIdealMaxWords`	200	upper bound of the coach's "ideal length" band
`promptTooLongWords`	500	word count above which the ask is considered buried
`packBudgetPercent`	25	max share of the budget `/cco-pack` may consume

/cco-config                          # table of all values, * = set by you
/cco-config set rereadWarnAt 5       # fewer re-read warnings
/cco-config set staleTimeMs 300000   # Read Cache re-allows after 5 min, not 10
/cco-config reset staleTimeMs        # back to the default

CCO_STALE_TIME_MS in the environment still overrides staleTimeMs, for a one-off experiment without changing 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), VS Code heatmap overlay, /cost integration, multi-language CLAUDE.md analysis, Windows-native hooks. See ROADMAP.md for what's planned and CONTRIBUTING.md for how to start.

Credits

GitHub's contributors graph only counts commits, so the people who found the bugs don't appear in it. They should. Every entry below changed the tool:

	Found	Shipped
@GesPacClinica	#1 — the very first issue: a clean install on fresh Linux Mint crashed Node on every hook, because `npx skills add` puts `CLAUDE_PLUGIN_ROOT` somewhere with no `src/`	`fd5dc7e` — every hook now tests for the file before running it
@zwrose	#29 — `/cco-report` crashed outright, and its cost table printed `$NaN`	sent the fix themselves, as a PR
@Reapper-Stack	#46 — on Windows every transcript lookup pointed at a malformed path, so `/cco-overhead` always claimed "no transcripts found" — reported with the root cause	v4.7.0 Windows-correct paths
@harvest316	#53 — `/cco-overhead mcp` told fresh installs to delete MCP servers it had never actually watched; the cold-start guard counted sessions, not evidence — reported with the root cause, the on-disk verification, and the fix	v4.9.1

A report that names the root cause is worth more than one that just names the symptom — #46 and #53 both arrived that way, and #29 arrived as the patch itself.

Found something? Open an issue — you'll end up on this list.

License

MIT — do whatever you want with it.

_{Built with frustration at wasted tokens and love for efficiency.}
_{If we saved you money, return the favor.}