CCR — Cool Cost Reduction

60–95% token savings on Claude Code, Cursor, Gemini CLI, Cline, and VS Code Copilot tool outputs. CCR sits between the agent and your tools, compressing what the model reads without changing what you ask it to do.

Token Savings

Numbers from ccr/tests/handler_benchmarks.rs. Run cargo test -p ccr benchmark -- --nocapture to reproduce, or ccr gain to see your own live data.

How It Works

Claude runs: cargo build
    ↓ PreToolUse hook rewrites to: ccr run cargo build
    ↓ ccr executes cargo, filters output through Cargo handler
    ↓ Claude reads: errors + warning count only (~87% fewer tokens)

Claude runs: Read file.rs  (large file)
    ↓ PostToolUse hook: BERT pipeline using current task as query
    ↓ Claude reads: compressed file content focused on what's relevant

Claude runs: git status  (seen recently)
    ↓ Pre-run cache hit (same HEAD+staged+unstaged hash)
    ↓ Claude reads: [PC: cached from 2m ago — ~1.8k tokens saved]

After ccr init, this is fully automatic — no changes to how you use your agent. CCR is local-only and never sends data anywhere.

Installation

Homebrew (macOS — recommended)

brew tap AssafWoo/ccr
brew install ccr

post_install automatically runs ccr init (Claude Code) and ccr init --agent cursor (Cursor, if installed).

Script (Linux / any platform)

curl -fsSL https://raw.githubusercontent.com/AssafWoo/homebrew-ccr/main/install.sh | bash

Installs Rust if needed, builds from source, and runs ccr init.

First run: CCR downloads the BERT model (~90 MB, all-MiniLM-L6-v2) from HuggingFace and caches it at ~/.cache/huggingface/. Subsequent runs are instant.

FAQ

Does CCR degrade Claude's output quality?
No. CCR only removes noise — build logs, module graphs, passing test lines, progress bars. Errors, file paths, and summaries are always kept.

What about tools CCR doesn't know?
BERT semantic routing matches against all known handlers. If confidence is high enough the closest handler applies; otherwise output passes through unchanged. CCR never silently drops output.

How do I verify it's working?
ccr gain after a session. To inspect what the model received from a specific command: ccr proxy git log --oneline -20.

Does CCR send any data outside my machine?
Never. All processing is fully local. BERT runs on-device.

Commands

ccr init

ccr init                              # Claude Code (default)
ccr init --agent cursor               # Cursor
ccr init --agent gemini               # Gemini CLI
ccr init --agent cline                # Cline (.clinerules in project dir)
ccr init --agent copilot              # VS Code Copilot

ccr init --uninstall                  # remove (add --agent <x> for specific agent)

Safe to re-run — replaces existing CCR entries without touching other hooks. Writes an SHA-256 integrity baseline (see ccr verify).

ccr gain

ccr gain                    # overall summary
ccr gain --breakdown        # per-command table
ccr gain --history          # last 14 days
ccr gain --history --days 7

CCR Token Savings
═════════════════════════════════════════════════
  Runs:           315  (avg 280ms)
  Tokens saved:   32.9k / 71.1k  (46.3%)  ███████████░░░░░░░░░░░░░
  Cost saved:     ~$0.099  (at $3.00/1M)
  Today:          142 runs · 6.8k saved · 23.9%
  Top command:    (pipeline)  65.2%  ·  25.8k saved

Analytics stored in SQLite (~/.local/share/ccr/analytics.db). Existing analytics.jsonl files are migrated automatically on first run.

Pricing uses cost_per_million_tokens from ccr.toml if set, otherwise ANTHROPIC_MODEL env var (Opus 4.6: $15, Sonnet 4.6: $3, Haiku 4.5: $0.80), otherwise $3.00.

Other commands

ccr verify                            # check hook integrity for all installed agents
ccr discover                          # scan Claude history for commands that ran without CCR
ccr noise                             # show learned noise patterns; --reset to clear
ccr expand ZI_3                       # print original lines from a collapsed block
ccr expand --list                     # list all available IDs in this session
ccr read-file src/main.rs --level auto  # apply read-level filter and print savings
ccr compress --scan-session           # compress current conversation context
ccr filter --command cargo            # filter stdin as if it were cargo output
ccr run git status                    # run through CCR handler manually
ccr proxy git status                  # run raw (no filtering), record analytics baseline

Handlers

48 handlers (60+ command aliases) in ccr/src/handlers/. Lookup cascade:

1. User filters — .ccr/filters.toml or ~/.config/ccr/filters.toml
2. Exact match — direct command name
3. Static alias table — versioned binaries, wrappers, common aliases
4. BERT routing — unknown commands matched by embedding similarity

Pipeline Architecture

0. Hard input ceiling (200k chars — truncates before any stage)
1. Strip ANSI codes
2. Normalize whitespace
3. Global regex pre-filter (progress bars, spinners, download lines, decorators)
4. NDJSON streaming compaction (go test -json, jest JSON reporter)
5. Command-specific pattern filter
6. If over summarize_threshold_lines:
   6a. BERT noise pre-filter
   6b. Entropy-adaptive BERT summarization (up to 7 passes)
7. Hard output cap (50k chars)

Outputs under 15 tokens skip the pipeline entirely. Step 6b falls back to head+tail if BERT is unavailable.

Pre-run cache (fires before execution): git, kubectl, docker, and terraform commands are hashed against live state. A hit skips execution entirely and returns the cached output with a [PC: cached from Xm ago] marker.

Configuration

Config loaded from: ./ccr.toml → ~/.config/ccr/config.toml → embedded default.

[global]
summarize_threshold_lines = 50
head_lines = 30
tail_lines = 30
strip_ansi = true
normalize_whitespace = true
deduplicate_lines = true
input_char_ceiling = 200000
output_char_cap = 50000
# cost_per_million_tokens = 15.0

[tee]
enabled = true
mode = "aggressive"   # "aggressive" | "always" | "never"

[read]
mode = "auto"   # "passthrough" | "auto" | "strip" | "aggressive"

[commands.git]
patterns = [
  { regex = "^(Counting|Compressing|Receiving|Resolving) objects:.*", action = "Remove" },
]

[commands.cargo]
patterns = [
  { regex = "^\\s+Compiling \\S+ v[\\d.]+", action = "Collapse" },
  { regex = "^\\s+Downloaded \\S+ v[\\d.]+", action = "Remove"   },
]

Pattern actions: Remove, Collapse, ReplaceWith = "text", TruncateLinesAt = N, HeadLines = N, TailLines = N, MatchOutput = "msg", OnEmpty = "msg".

User-Defined Filters

Place filters.toml at .ccr/filters.toml (project-local) or ~/.config/ccr/filters.toml (global). Project-local overrides global for the same key. Runs before any built-in handler.

[commands.myapp]
patterns = [
  { regex = "^DEBUG:",            action = "Remove" },
  { regex = "^\\S+\\.ts\\(",     action = "TruncateLinesAt", max_chars = 120 },
]
on_empty = "(no relevant output)"

[commands.myapp.match_output]
pattern        = "Server started"
message        = "ok — server ready"
unless_pattern = "error"

Session Intelligence

State tracked via CCR_SESSION_ID=$PPID, stored at ~/.local/share/ccr/sessions/<id>.json.

• Result cache — post-pipeline bytes frozen per input hash; returned identically on repeat calls to prevent prompt cache busts.
• Semantic delta — repeated commands emit only new/changed lines: [Δ from turn N: +M new, K repeated — ~T tokens saved].
• Cross-turn dedup — identical outputs (cosine > 0.92) collapse to [same output as turn 4 (3m ago) — 1.2k tokens saved].
• Elastic context — pipeline pressure scales with session size. At >80% pressure: [⚠ context near full — run ccr compress --scan-session].
• Intent-aware query — reads the agent's last message from the live session JSONL and uses it as the BERT query.

Hook Architecture

All agents share the same binary and compression pipeline.

PreToolUse: known handler → rewrites to ccr run <cmd>; unknown → no-op; already wrapped → no double-wrap; compound commands → each segment rewritten independently.

PostToolUse: Bash → full pipeline; Read → BERT + session dedup; Glob → grouped by directory; Grep → compact paths.

Hook integrity: ccr init writes SHA-256 baselines (chmod 0o444). CCR verifies at every invocation and exits 1 with a warning if tampered. ccr verify checks all installed agents.

Crate Overview

ccr/        CLI binary — handlers, hooks, session state, commands
ccr-core/   Core library (no I/O) — pipeline, BERT summarizer, config, analytics
ccr-sdk/    Conversation compression — tiered compressor, deduplicator, Ollama
ccr-eval/   Evaluation suite — fixtures against Claude API
config/     Embedded default filter patterns

Uninstall

ccr init --uninstall                        # Claude Code
ccr init --agent cursor --uninstall         # Cursor
ccr init --agent gemini --uninstall         # Gemini CLI
ccr init --agent cline --uninstall          # Cline
ccr init --agent copilot --uninstall        # VS Code Copilot

brew uninstall ccr && brew untap AssafWoo/ccr   # Homebrew
# or: cargo uninstall ccr

rm -rf ~/.local/share/ccr                   # analytics + sessions
rm -rf ~/.cache/huggingface/hub/models--sentence-transformers--all-MiniLM-L6-v2

Contributing

Open an issue or PR on GitHub. To add a handler: implement the Handler trait and register it in ccr/src/handlers/mod.rs — see git.rs as a template.

License

MIT — see LICENSE.