Sqz: Squeeze Context for AI Coding Agents
Pre-injection compression for AI agents: 24.7% fewer tokens, 92% on repeats. Rust, offline, zero LLM calls.
Your AI coding agent is not burning tokens on reasoning. It burns them on cargo test output, git status spam, and reading the same file five times.
That is the problem sqz ↗ solves. A single Rust binary that compresses tool output before it enters the model context. No LLM calls, fully offline, byte-exact reversible with sqz expand.
Real session stats from the repo: 3,003 compressions, 178,442 tokens saved, 24.7% average reduction, up to 92-96% on output the model already has.
Why This Matters#
Every agent turn re-sends history. A 1,200-token test log is not paid once — it is paid every turn after that until compaction. Add prompt caching and the math gets subtle, but the direction is clear: noisy tool output shortens sessions, increases cost, and pushes out useful reasoning.
[!NOTE] Token reduction ≠ billed-cost reduction 1:1. With provider prompt caching, repeated context bills at ~90% discount.
sqz stats --costmodels this honestly instead of hand-waving.
ELI5 mental model: your agent packs a suitcase (context window) for every trip. Right now it stuffs in dirty laundry — full passing tests, unchanged git status, repeated file reads. sqz is the friend who folds, removes duplicates, and leaves a sticky note: “blue shirt already in bag, see pocket 3”.
What Gets Compressed, What Does Not#
Compressed:
- Shell output — 45+ formatters across 12 ecosystems: git, cargo, npm/pnpm/yarn/bun, pytest, ruff, mypy, go test (incl.
-jsonstream), docker/podman, kubectl, aws, terraform, gcloud, gradle, maven, xcodebuild, adb logcat, dotnet, gh, grep/rg, tree, curl, and more - JSON — strip nulls, drop debug fields, flatten, collapse arrays, TOON encoding
- Logs — collapse repeated lines (
max_repeated_lines = 3by default) - Test output — failures only via state-machine parsers for Rust, Go, Python, JS, JVM
Never touched:
- Source code, stack traces, error messages, secrets → safe mode, 0% compression
- Your prompts and model responses → owned by the agent framework, not sqz
[!TIP] Every compressed result is recoverable byte-exact:
sqz expand <ref>.
The Numbers#
Single-command compression (cargo test -p sqz-engine benchmarks):
| Content | Before | After | Saved |
|---|---|---|---|
| Repeated log lines | 148 | 62 | 58% |
| Large JSON array | 259 | 142 | 45% |
| JSON API response | 64 | 53 | 17% |
| Git diff | 61 | 54 | 12% |
| Prose/docs | 124 | 121 | 2% |
| Stack trace (safe mode) | 82 | 82 | 0% |
Session-level with dedup (where sqz wins big):
| Repeat | Without sqz | With sqz | Saved |
|---|---|---|---|
Unchanged git status rerun | 155 | 13 | 92% |
| Lines 41-80 of 200-line file read earlier | 305 | 16 | 95% |
Same cargo test, nothing changed | 303 | 13 | 96% |
Demo from README:
cat auth.py (500 lines): 4,000 tokens 4,000 tokens (source served in full)
cargo test (1 failure): 1,200 tokens 120 tokens (failure + assertion + file:line)
sed -n '40,80p' auth.py: 330 tokens 18 tokens (§ref:…:L40-80§)
git status, unchanged: 160 tokens 13 tokens (§ref:…§)
───────────────────────────────────── ─────────────
Total: 5,690 tokens 4,151 tokens (27% saved, nothing dropped)textOne nuance the author calls out: whole-file re-reads are rarer than lore suggests (1 in 542 reads in one user’s 92-session count). Real repeats are unchanged command output, line ranges, and re-reads after small edits — each gets its own reference type.
Install in 2 Minutes#
# macOS / Linux (prebuilt, no compiler)
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh
# Any platform via npm
npm install -g sqz-cli
# macOS via Homebrew
brew tap ojuschugh1/sqz
brew install sqz
# From source
cargo install sqz-cli sqz-mcpbashThen:
sqz init --global # every project on machine (~/.claude/settings.json merge)
# or
sqz init # this project only
sqz init --only opencode,codex # limit clients
sqz init --skip cursor,windsurf # everything except these
sqz doctor # verify chain: binary, DB, hooks, recent compressionsbash[!WARNING]
sqz initround-tripsopencode.jsoncthrough a JSON parser and drops comments. To preserve comments, install manually:sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts, then add thesqz-mcpentry by hand.
Try Before You Hook: Counterfactual Replay#
Already use Claude Code or Kiro? Replay existing transcripts locally, nothing uploaded:
sqz discover --replay
# Sessions replayed: 24
# Tool outputs: 43
# Tokens (original): 116,598 → compressed: 92,560
# Estimated avoidable: 24,038 tokens (20.6%)bashEach session replays against a fresh throwaway cache, so cross-session dedup never inflates numbers.
CLI Cheat Sheet#
sqz compress "some text" # or pipe stdin
sqz compress --no-cache # skip dedup, full output
sqz expand a1b2c3d4 # prefix match, or paste full §ref:…§
sqz gain # daily bar chart, last 7 days
sqz gain --days 30 --project . # last 30 days, current project
sqz stats # cumulative + regret signals
sqz stats --cost # $ under prompt-cached billing model
sqz stats --breakdown # top token consumers per command
sqz recall "connection refused" # FTS5 search over everything compressed
sqz resume # re-inject context after compaction
sqz compact # proactive eviction: --strategy keep_recent|keep_relevant|keep_errors
sqz vizit # htop-like live dashboard
sqz discover # weakest-compressing commandsbashDedup escape hatch (some models like GLM 5.1 loop on §ref§):
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1 # disable globally
export SQZ_REF_TTL_SECS=300 # shorten ref window (default 1800, 0 = off)bashHow Compression Works: 6 Stages#
- Per-command formatters — purpose-built per tool.
cargo testkeeps failing test + assertion +file:line.git statusbecomes compact summary. Unknown commands fall through to generic pipeline — nothing left uncompressed. - Table compactor — collapses padding runs in
ps aux,netstat, DB CLIs to two-space separators. Strict detector: indented lines, code, YAML, JSON never match. - Structural summaries — code → imports + signatures + call graph (~70% reduction). Architecture, not implementation noise.
- Dedup cache — SHA-256 hash, persistent in SQLite. Byte-identical → 13-token
§ref:HASH§. Line range of known file →§ref:HASH:L40-80§. Re-read after small edit → only changed lines. Refs live 30 min (SQZ_REF_TTL_SECS), reset on compaction. - JSON pipeline — strip nulls → project debug fields → flatten → collapse arrays → TOON (lossless compact format).
- Safe mode — entropy analysis detects stack traces, secrets, migrations → 0% compression, passthrough.
Sub-millisecond latency (p99 < 5ms to 100KB), ~0.1ms SQLite lookup. Negligible vs LLM inference.
Supported Tools#
| Tool | Integration | Setup |
|---|---|---|
| Claude Code / Cursor / Windsurf / Cline | PreToolUse hook (transparent) | sqz init |
| Gemini CLI | BeforeTool hook | sqz init |
| Kiro | Steering + MCP | sqz init |
| OpenCode | TypeScript plugin | sqz init |
| Codex / Zed | AGENTS.md + MCP | sqz init |
| Copilot CLI | preToolUse hook | sqz init |
| Copilot coding agent (CI) | repo hook, self-bootstraps | sqz init --ci + commit |
| Any MCP server | sqz-mcp proxy -- <server> | compresses tool results + tools/list |
| VS Code / JetBrains / Chrome / Firefox | Extensions | Marketplaces |
MCP proxy example — wraps any stdio server:
{
"mcpServers": {
"github": {
"command": "sqz-mcp",
"args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}jsonFlags: --lazy-tools (one-sentence descs + sqz_tool_help on demand — some servers burn 10-40k tokens on tools/list alone), --no-desc, --no-cache. Proxy injects sqz_expand so agent recovers originals byte-exact.
Honest Accounting: Cost and Regret#
Two signals most compression tools ignore:
sqz stats --cost— dollars under prompt-cached billing (cache write ×1.25 once, cache read ×0.10 per turn). Assumptions printed, overridable via--price-in,--reread-turns,--cache-write-mult,--cache-read-mult. Conservative by design.- Regret signals in
sqz stats— quick re-runs (byte-identical output reproduced within 2 min = repeat bought nothing) and ref expands (§ref§recovered to bytes = model needed full content). If one command keeps appearing, its formatter needs work — file an issue.
Design avoids known failure modes from arXiv:2607.12161 ↗: deterministic + query-agnostic (never invalidates provider prompt caches), only new tool output touched (history never rewritten), piped/redirected commands never intercepted, 16-token net-win gate skips compressions that would not pay for markers.
Practical Example: Wire Into a Session#
# 1. check what you would have saved
sqz discover --replay
# 2. install globally
sqz init --global
sqz doctor
# 3. work normally, then track
sqz gain
sqz stats --breakdown
# 4. recall beats re-running
sqz recall "Failed to connect"
sqz expand 3f9a1c05e2d84b17bashPer-project DB isolation with direnv:
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"bashAll surfaces honor it: shell hook, stats/gain/expand, MCP server (env in MCP config). Parent dir created mode 0700.
Configuration#
[preset]
name = "default"
version = "1.0"
[compression.condense]
enabled = true
max_repeated_lines = 3
[compression.strip_nulls]
enabled = true
[budget]
warning_threshold = 0.70
default_window_size = 200000tomlPrivacy#
Zero telemetry, no crash reports, fully offline, air-gap capable. Stats in ~/.sqz/sessions.db (SQLite FTS5). Nothing leaves machine.
When Not to Use sqz#
- You need verbatim logs for audit — use
--no-cacheor safe-mode paths, orexpandafter. - Your model cannot parse
§ref§tokens — disable dedup (SQZ_NO_DEDUP=1). - Tiny outputs under net-win gate — sqz already skips these (16-token threshold).
Conclusion#
sqz sits at the right boundary: tool execution, not prompt rewriting, not model-specific adapters. One sqz init covers every agent framework, deterministic Rust core keeps p99 under 5ms, and dedup turns repeats into 13-token refs.
Start with sqz discover --replay — if your own transcripts show 20%+ avoidable tokens, install the hook.