token-saver

Token-Saver

Keep the signal. Stop rereading the same failures.

Token-Saver compresses the terminal output your AI coding assistant reads — git diff, pytest, npm install, terraform plan, kubectl, docker — to leave more room for the code, instructions, and next decision. Compression runs locally, without another model call or an output upload.

New in v3: Delta. Run your tests, edit, run again: see which failures are new, changed, or unchanged. Fresh diagnostics keep their full details; repeated ones can become a short inventory, with details available on demand. Delta is an experimental, opt-in feature in 3.0.0 for supported pytest and Ruff commands in Claude Code.

36 specialized processors cover git, pytest, jest, cargo, go, docker, kubernetes, terraform, pulumi, helm, ansible, aws, gcloud, and more. Their rules reduce progress logs and boilerplate, with failure fixtures and optional quality contracts checking important diagnostics.

Ordinary compression supports Claude Code and Antigravity CLI. It runs automatically after installation. Results depend on the command and output; already concise or unsupported output may stay unchanged.

Why developers use Token-Saver:

• 💸 Less output to process — many benchmark scenarios save 60-99% of estimated output tokens; billing impact depends on your usage and provider.
• 🔁 See what changed — opt-in Delta compares repeated pytest/Ruff runs and keeps retained details one command away.
• 🪟 Bigger effective context — fit more real work into the same context window.
• 🎯 Tested preservation — failure fixtures check important diagnostics; add quality contracts for your own workflows.
• 🔌 Install once, forget it — works automatically in the background, no prompts to change.
• 🛡️ Local compression — pure regex/parsing with no network calls in the compression path.

---

Table of Contents

• Before & After
• Quick Start
• Why Token-Saver Exists
• Who It's For
• What Gets Compressed — Real Examples
• How It Compares
• How It Works
• Precision Guarantees
• Installation
• CLI Reference
• Delta: Changes Between Runs
• Compression Quality Gates
• Processors
• Configuration
• Tuning Recipes
• Custom Processors
• Savings Tracking
• Security & Privacy
• Performance
• FAQ
• Troubleshooting
• Known Limitations
• Project Structure
• Tests
• Contributing

---

Before & After

Command	Raw Output	Compressed	Savings
git diff (5 files, 20 context lines each)	2,270 tokens	546 tokens	76%
git diff --stat (25 files)	526 tokens	21 tokens	96%
git log --oneline (50 entries)	568 tokens	117 tokens	79%
pytest (500 tests, 2 failures)	6,744 tokens	307 tokens	95%
pytest (200 passed, 30 warnings)	3,543 tokens	80 tokens	98%
jest (50 suites, all passing)	570 tokens	32 tokens	94%
npm install (220 packages)	3,843 tokens	4 tokens	99.9%
pip install -r requirements.txt (30 packages)	1,797 tokens	88 tokens	95%
cargo build (120 crates)	934 tokens	21 tokens	98%
docker build (20 steps)	1,682 tokens	207 tokens	88%
curl download (100 progress lines)	2,122 tokens	0 tokens	100%
ruff check (110 violations, 4 rules)	1,475 tokens	186 tokens	87%
eslint (55 violations, 2 rules)	1,292 tokens	144 tokens	89%
tree (350+ lines)	1,840 tokens	136 tokens	93%
find . -name '*.py' (205 results)	1,294 tokens	217 tokens	75%

These are locked to tests/compression_baselines.json and gated by CI (tests/test_compression_ratchet.py) — if a change makes any of them compress worse, the build fails. Run python3 scripts/audit_compression.py to see the full scenario set, or token-saver benchmark '<command>' to measure savings on your own workloads.

Not every command compresses, and that's deliberate. cat large_file.py, git status -s, and tsc with 7 type errors all sit in the same baseline file at 0% — they're already dense, or the model needs them verbatim. Token-Saver returns the original bytes rather than shaving a few tokens at the cost of correctness.

Quick Start

/plugin marketplace add ppgranger/token-saver
/plugin install token-saver

(Also available on Anthropic's official community marketplace — see Installation for both options.)

That's the whole setup. Ask Claude to run anything — "run the tests", "show me the diff", "what changed in the last 10 commits" — and the output is compressed before it reaches the model. Then:

token-saver stats

Want to see it work before installing it?

git clone https://github.com/ppgranger/token-saver.git && cd token-saver
python3 bin/token-saver benchmark 'git log --oneline -50'
python3 bin/token-saver benchmark 'git diff' --show-removed
python3 bin/token-saver explain 'docker compose logs | grep error'

Why Token-Saver Exists

Verbose tool output competes with your code and instructions for context. A pytest run with 200 passing tests or an install with hundreds of progress lines often repeats information that can be represented much more compactly. After an edit, another run can repeat the same failures too.

Token-Saver reduces that repetition using local parsing. Delta extends this to consecutive runs, while keeping a current diagnostic inventory and retrievable details. Whether this improves task completion, response time, or billing needs measurement in the agent workflow that uses it.

There are three common ways to attack this:

1. Summarize with another LLM. Accurate-ish, but it costs a second inference per command, adds seconds of latency, and is non-deterministic — the same pytest run can be summarized two different ways.
2. Truncate blindly. Free and instant, but it's exactly how you lose the one stack-trace line that mattered.
3. Parse the format you already know. git diff has a grammar. pytest has a summary line. npm install has a progress phase and a result phase. Format-aware parsing can remove repetitive output while retaining tested diagnostics, deterministically and without another model call.

Token-Saver is the third approach, applied to 36 command families. It sits between the CLI and your AI assistant, applying format-specific rules whose preservation behavior you can test against your own captured output.

Who It's For

• Developers paying per token on Claude Code, whether via API credits or a plan with usage limits. Tool output is often the largest single category of input tokens in an agentic session.
• Teams running agents in CI, where a long pipeline command (terraform plan, pytest, gradle build) is piped straight into a model.
• Anyone hitting context limits mid-task — the "conversation is too long" wall usually arrives right after a big npm install or a wide git diff.
• Monorepo and infrastructure work, where a single terraform plan or kubectl describe is thousands of tokens of mostly-unchanged resource attributes.
• Privacy-sensitive environments that can't route output through a second model or a hosted service. Token-Saver is pure local Python with no network calls in the compression path.

It's probably not for you if your agent mostly reads and writes source files and rarely runs shell commands — file reads go through Claude Code's own Read tool, which Token-Saver doesn't intercept.

What Gets Compressed — Real Examples

Everything below is actual Token-Saver output, produced by the same scenario corpus the CI ratchet uses.

pytest — 533 lines → 26 lines (95%)

Passing tests collapse to a count. Every failure keeps its full traceback, assertion diff, file, and line number.

[500 tests passed]
=================================== FAILURES ===================================
__________________________ test_compression_ratio ______________________________

    def test_compression_ratio():
        engine = CompressionEngine()
        result = engine.compress('git status', large_output)
>       assert len(result[0]) < len(large_output) * 0.5
E       AssertionError: assert 1500 < 1000
...
FAILED tests/test_engine.py::test_compression_ratio - AssertionError: assert 1500 < 1000
FAILED tests/test_processors.py::test_diff_context_trim - AssertionError: assert 42 < 10
========================= 2 failed, 510 passed ==

ruff check — 111 lines → 18 lines (87%)

Violations are grouped by rule with a count and a couple of concrete examples, so the model learns the pattern to fix instead of reading 45 near-identical lines.

110 issues across 4 rules:
  E501: 45 occurrences in 45 files
    src/module/e501_00.py:10:5: E501 Line too long
    src/module/e501_01.py:11:6: E501 Line too long
    ... (43 more)
  F401: 30 occurrences in 30 files
    src/module/f401_00.py:10:5: F401 imported but unused
    ... (28 more)
Found 110 errors.

npm install — 526 lines → 1 line (99.9%)

Build succeeded.

Nothing actionable was lost: the raw output was 220 added <pkg>@<ver> lines and a progress bar. Had the install failed, the error and the failing package would survive verbatim — see Precision Guarantees.

cargo build — 122 lines → 2 lines (98%)

[121 crates compiled]
    Finished dev [unoptimized + debuginfo] target(s) in 45.23s

git diff — context trimmed, changes untouched (76%)

Unified diffs keep every +/- line and every @@ hunk header, with surrounding unchanged context trimmed to max_diff_context_lines (default 3):

diff --git a/src/module_0.py b/src/module_0.py
@@ -10,30 +10,32 @@ def some_function_0():
     # This is context line 9 that hasn't changed and takes up tokens
-    old_value = compute_something(0)
-    return old_value
+    new_value = compute_something_better(0)
+    cached = cache.get(new_value)
+    if cached:
+        return cached
+    return new_value
     # This is trailing context line 0 that is unchanged and wastes tokens

tree — 312 lines → 28 lines (93%)

The directory shape is preserved down to the truncation point, with an explicit marker and the original totals, so the model knows what it isn't seeing:

.
├── src/
│   ├── engine.py
│   ├── config.py
│   ├── processors/
│   │   ├── git.py
...
... (287 lines truncated)
20 directories, 310 files

env / printenv — secrets redacted before the model sees them

Variables whose names look sensitive (SECRET, PASSWORD, CREDENTIAL, API_KEY, GITHUB_TOKEN, and bare KEY/TOKEN/AUTH/PWD at letter boundaries — so PATH, AUTHOR, and MONKEY are left alone) have their values replaced. Token-Saver returns this redacted output even when it isn't smaller than the input: a redacted result is never traded back for the raw one to satisfy a compression threshold.