⚡ ContextZip

CLI output eats your AI context window. ContextZip compresses it 40-97% (61% avg across 102 tests).
npx contextzip

_{For: Claude Code / Cursor / Copilot CLI users hitting token limits.
Not for: projects where you need raw command output (use contextzip proxy <cmd> instead).}

🌐 Languages

한국어 • 日本語 • 中文 • Español • Português • हिन्दी • Français • Deutsch • Русский • Türkçe • Tiếng Việt

---

---

⬇️ Install

npx contextzip

Restart Claude Code. Every command is now compressed. Zero config. macOS · Linux · Windows

Tip

Need raw output? Use contextzip proxy <command> to bypass all filters. Missing jq? Install it: brew install jq (macOS) or apt install jq (Linux). Required for the Claude Code hook.

Other install methods

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/jee599/contextzip/main/install.sh | bash
brew install jee599/tap/contextzip

# Windows (PowerShell)
npx contextzip

# Rust developers
cargo install --git https://github.com/jee599/contextzip

---

👀 See the Difference

💥 Node.js Error — 30 lines → 3 lines (92% saved)

❌ Before TypeError: Cannot read properties of undefined (reading 'id') at getUserProfile (users.ts:47) at processAuth (auth.ts:12) at Layer.handle (node_modules/ express/lib/router/layer.js:95) ... 25 more node_modules lines

✅ After TypeError: Cannot read properties of undefined (reading 'id') → users.ts:47 getUserProfile() → auth.ts:12 processAuth() (+ 27 framework frames hidden) 💾 saved 92%

📦 npm install — 150 lines → 3 lines (95% saved)

❌ Before npm warn deprecated inflight@1.0.6 npm warn deprecated rimraf@3.0.2 ... 45 more deprecated warnings added 847 packages, audited 848 8 vulnerabilities (2 moderate, 6 high) ... 20 more lines

✅ After ✓ 847 packages (32s) ⚠ 8 vulnerabilities (6 high, 2 mod) ⚠ bcrypt@3.0.0: CVE-2023-31484 💾 saved 95%

🐳 Docker Build — 50 lines → 1 line (96% saved)

❌ Before Step 1/12 : FROM node:20-alpine ---> abc123def456 Step 2/12 : WORKDIR /app ---> Using cache ... 8 more steps with hashes Successfully tagged my-app:latest

✅ After ✓ built my-app:latest (12 steps, 8 cached) 💾 saved 96%

Note

Currently supports legacy Docker builder output (Step N/M format). Docker BuildKit format passes through uncompressed.

🔨 TypeScript Build — 40 errors grouped (81% saved)

❌ Before src/api/users.ts:47:5 - error TS2322: Type 'string' not assignable to 'number' ... 36 more identical errors Found 40 errors in 8 files.

✅ After TS2322: 'string' → 'number' (×40) users.ts :47, :83 orders.ts :12, :45 ... +6 files 💾 saved 81%

🆕 v0.2 — Session History Compression (the one nobody else does)

Live stdout compression is table stakes. The bigger problem: your past Claude Code session JSONL under ~/.claude/projects/ accumulates 85.8% tool inputs/results (measured across 6,850 messages). ContextZip is the first tool to compact that archive.

Before — 55 MB session, 2,475 records Read /src/main.rs × 14 calls Read /Cargo.toml × 9 calls Bash "npm install" ANSI noise + repeats Bash "cargo test" repeated lines ... 152 more repeated reads ... 43 more noisy Bash results

After — contextzip compact + apply ✓ ReadDedup 153 hits → references ✓ BashHistoryCompact 44 hits → filtered 57.3 MB → 53.5 MB (6.7% saved) .bak preserved → safe rollback via expand

contextzip compact <session-id>   # writes a reversible .compressed sidecar
contextzip apply   <session-id>   # atomic swap; original kept as .bak
contextzip expand  <session-id>   # roll back; sidecar preserved

More examples: Rust panic, Python, Web page, ANSI, Docker failure, Java/Go

🐍 Python Traceback (72% saved) — Framework frames (flask, importlib) hidden, your code + error message kept.

🦀 Rust Panic (2-7% saved) — std::panicking, tokio::runtime frames hidden, your crate frames kept.

🌐 Web Page (73% saved) — Nav, footer, sidebar, cookie banner, social links stripped. <main>/<article> content kept.

🎨 ANSI/Spinners (83% saved) — Escape codes, spinner frames, intermediate progress bars removed. Final states kept.

🐳 Docker failure — Failed step + 2 prior steps + error message + exit code always preserved.

☕ Java — Removes java.lang.reflect, sun.reflect, org.springframework, org.apache frames.

🐹 Go — Removes runtime/, runtime.gopanic, runtime.main frames.

---

📊 The Numbers Don't Lie

102 real-world tests. No cherry-picking.

Category	Tests	Avg Savings	🏆 Best	💀 Worst
🐳 Docker build	10	88%	97%	77%
🎨 ANSI/spinners	15	83%	98%	0%
💥 Error traces	20	59%	97%	-12%
🔨 Build errors	15	56%	90%	-10%
🌐 Web pages	15	43%	64%	5%
💻 CLI commands	12	42%	99%	-56%
📦 Package install	15	39%	99%	2%

Weighted total: 61% savings → 326K chars in, 127K chars out

Why some rows show negative savings

Negative = output grew. Happens on tiny inputs where the filter's metadata costs more than it saves. We put the worst numbers in the table because hiding them would be dishonest. Full benchmark →

---

🆚 Why Not Just RTK?

Built on RTK (28k⭐). All 34 RTK commands included. Plus:

	RTK	ContextZip
CLI compression (git, test, ls)	✅	✅
Error stacktraces (Node/Python/Rust/Go/Java)	❌	✅
Web page content extraction	❌	✅
ANSI / spinner / decoration removal	🟡	✅
Build error grouping (tsc/eslint/cargo)	🟡	✅
Package install noise (npm/pip/cargo)	❌	✅
Docker build compression	🟡	✅
Per-command savings display	❌	✅
Session-history compression (planned)	❌	🚧
2026 toolchain coverage (uv/helm/biome/tf, planned)	❌	🚧

---

🗺️ What's Next

The session-history compressor (compact / apply / expand) shipped in v0.2 — see the demo above. Other in-flight tracks: AWS 8→25 subcommand expansion, more compact axes (WritePlaceholder, EditDelta), DSL polish.

Full design: docs/superpowers/specs/2026-04-17-contextzip-advancement-design.md. Short version: ROADMAP.md.

Other v0.2 tracks (full design here):

• Upstream catch-up — rtk v0.31~0.36 fixes (git/aws/clippy/runner)
• New filters — uv (Python), gradle/mvn (JVM), mise, helm, terraform, biome
• Stability — test coverage for env_cmd / verify_cmd / wget_cmd
• DSL polish — env var substitution + per-platform filters

Short version in ROADMAP.md.

---

🛡️ Nothing Important Gets Lost

🔴 Error messages	ALWAYS preserved
📍 File:line in build errors	NEVER removed
🔒 Security warnings (CVE, GHSA)	ALWAYS kept
🐳 Docker failure context	ALWAYS preserved
⏎ Exit codes	ALWAYS propagated

Important

ContextZip only removes confirmed noise. When in doubt → passthrough.

🏎️ How It Works

  ┌─────────────────────────────────────────────┐
  │  Claude Code runs: git status               │
  │                         ↓                   │
  │  Hook rewrites → contextzip git status      │
  │                         ↓                   │
  │  ┌──────────────────────────────────────┐   │
  │  │ [1] ANSI preprocessor    strip junk  │   │
  │  │ [2] Command router    40+ filters    │   │
  │  │ [3] Error post-proc   compress stack │   │
  │  │ [4] SQLite tracker    record savings │   │
  │  └──────────────────────────────────────┘   │
  │                         ↓                   │
  │  Compressed output → Claude's context       │
  │  💾 contextzip: 200 → 40 tokens (80%)       │
  └─────────────────────────────────────────────┘

🔧 Commands

# Automatic (hook rewrites — no prefix needed):
git status    npm install    cargo test    docker build .

# Manual:
contextzip web https://docs.example.com    # page → content only
contextzip err node server.js              # error-focused output

# Analytics:
contextzip gain                  # dashboard
contextzip gain --by-feature     # per-filter stats
contextzip gain --graph          # daily chart

# Manage:
contextzip init --show    contextzip update    contextzip uninstall

📈 Track Everything

$ contextzip gain
📊 ContextZip Token Savings
════════════════════════════════════════
Total commands:    2,927
Tokens saved:      10.3M (89.2%)

$ contextzip gain --by-feature
Feature        Commands  Saved     Avg%
cli (RTK)      2,100     6.8M     78%
error          89        1.2M     93%
web            43        0.9M     73%
build          112       0.4M     81%

---

🤝 Contribute

git clone https://github.com/jee599/contextzip.git && cd contextzip
cargo test         # 1,112 tests
cargo clippy       # lint

Working on a track from the roadmap? Open an issue first so we can confirm scope and avoid double work.

📡 Telemetry

ContextZip collects anonymous usage statistics (command count, savings percentage) to improve the tool. No personal data or command content is transmitted.

Disable: export CONTEXTZIP_TELEMETRY_DISABLED=1

📜 License

MIT — Fork of RTK by rtk-ai.

---

⚡ Less noise. More code. Ship faster.