sqz

AI coding agents spend most of their input tokens on tool output: build logs, test runs, git status, the same file read again after every edit. All of it goes into the context window raw, and it is re-sent on every turn after that.

sqz compresses tool output before it enters the context. Per-command formatters keep what an agent acts on (the failing test, the assertion, the file:line) and drop what it does not. Anything the model already has in context comes back as a short reference instead of the content. Source code, stack traces and secrets pass through untouched.

cargo install sqz-cli sqz-mcp     # or: brew install ojuschugh1/sqz/sqz · npm i -g sqz-cli · pipx install sqz
sqz init                          # hooks + MCP server + agent guidance for every client it finds

Real output from the release binary (assets/demo.tape). Regenerate with vhs assets/demo.tape.

Without sqz:                              With sqz:

cat auth.py (500 lines):   4,000 tokens    4,000 tokens  (source is 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§ to the read above)
git status, unchanged:       160 tokens       13 tokens  (§ref:…§)
─────────────────────────────────────      ─────────────
Total:                     5,690 tokens    4,151 tokens  (27% saved, nothing dropped)

Single Rust binary, deterministic, no LLM calls, works offline. Every compressed result can be recovered byte-exact with sqz expand.

[!NOTE] Name disambiguation: this repo, ojuschugh1/sqz, is an independent project and is not affiliated with any other similarly named or working tool or other compression projects that shorten "squeeze". If you installed sqz / sqz-cli / sqz-mcp from crates.io, npm, PyPI, or Homebrew, it comes from this repository.

Token Savings

24.7% average reduction across 3,003 real compressions · 13-token refs for output the model already has · 100% of agent-critical facts kept in the quality benchmark · 0% by construction on source code, stack traces and secrets

One developer's week, measured from actual sqz gain output:

$ sqz gain
sqz token savings (last 7 days)
──────────────────────────────────────────────────
  04-13 │                              │   2,329 saved
  04-14 │                              │       0 saved
  04-15 │███                           │  12,954 saved
  04-16 │██                            │   9,223 saved
  04-17 │████                          │  14,752 saved
  04-18 │██████████████████████████████│ 105,569 saved
  04-19 │████████                      │  30,882 saved
  04-20 │█                             │   4,334 saved
──────────────────────────────────────────────────
  Total: 3,003 compressions, 178,442 tokens saved (24.7% avg reduction)

Per-command compression

Single-command compression (measured via cargo test -p sqz-engine benchmarks):

Session-level with dedup

Anything the model already has in its context comes back as a reference. Measured with the release binary against a throwaway database, using the fixtures in sqz/tests/quality_bench.rs and demo/:

A word on what actually repeats. A user who counted 92 of their own Claude Code sessions found identical whole-file re-reads in 1 of 542 reads, and line-range re-reads in 8.5% of them. So sqz does not lead with "the same file read five times": the repeats that happen in practice are unchanged command output, line ranges of a file already read, and files re-read after a small edit, and each has its own reference type (details). Sessions with noisy command output and repeated commands see the biggest wins.

Install

Prebuilt binaries (no compiler required — works on every platform):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.ps1 | iex

# Any platform via npm
npm install -g sqz-cli

# macOS / Linux via Homebrew
brew tap ojuschugh1/sqz
brew install sqz

Build from source via Cargo:

cargo install sqz-cli sqz-mcp

sqz-cli provides the sqz binary; sqz-mcp provides the MCP server. sqz-engine is a library dependency — it compiles automatically and does not need to be installed separately.

Build from source (cargo install sqz-cli) works too, but needs a C toolchain:

• Linux: build-essential (apt) or equivalent
• macOS: Xcode Command Line Tools (xcode-select --install)
• Windows: Visual Studio Build Tools with the "Desktop development with C++" workload. Without these, cargo install fails with linker link.exe not found. If you don't already have them, use the PowerShell or npm install above instead.

Then initialize:

sqz init --global     # hooks apply to every project on this machine
# or
sqz init              # hooks apply to just this project (.claude/settings.local.json)

--global writes to ~/.claude/settings.json (the user scope per the Anthropic scope table), so the sqz hook fires in every Claude Code session on this machine. This is the common case on first install. Your existing permissions, env, statusLine, and unrelated hooks in ~/.claude/settings.json are preserved — sqz merges its entries rather than overwriting.

Plain sqz init (project scope) is useful when you want sqz active only inside one repo.

Only using one agent? Pass --only (or --skip) to limit which configs are written:

sqz init --only opencode              # just OpenCode, nothing else
sqz init --only opencode,codex        # OpenCode and Codex
sqz init --skip cursor,windsurf       # everything except Cursor and Windsurf

Accepted names: claude, cursor, windsurf, cline, gemini, kiro, opencode, codex. Aliases (claude-code, gemini-cli, roo, kiro-cli) also work. --only and --skip can't be combined.

Manual installation (preserve comments in your config)

sqz init round-trip