sqz

███████╗ ██████╗ ███████╗ ██╔════╝██╔═══██╗╚══███╔╝ ███████╗██║ ██║ ███╔╝ ╚════██║██║▄▄ ██║ ███╔╝ ███████║╚██████╔╝███████╗ ╚══════╝ ╚══▀▀═╝ ╚══════╝

Pre-injection context compression and session deduplication for AI coding agents

Real session stats: 3,003 compressions · 178,442 tokens saved · 24.7% avg reduction · up to 92% on output the model already has

Docs · Install · How It Works · Supported Tools · MCP Proxy · Benchmark · Changelog · Discord

English | 简体中文 | 日本語 | 한국어 | Español | Português (Brasil)

---

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 passes through unchanged, and so do stack traces, migrations and credential lines.

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 (200 lines): 1,300 tokens 1,300 tokens (source is served in full) cargo test (1 failure): 366 tokens 185 tokens (failure, assertion, file:line) sed -n '41,80p' auth.py: 260 tokens 35 tokens (§ref:…:L41-80§ to the read above) git status, unchanged: 166 tokens 37 tokens (§ref:…§) ───────────────────────────────────── ───────────── Total: 2,092 tokens 1,557 tokens (26% saved, nothing dropped)

Single Rust binary, deterministic, no LLM calls, works offline. Every compressed result can be recovered byte-exact with sqz expand, except output that mentions credentials, a stack trace or a migration, which sqz never caches.

[!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% on source code, and on stack traces and credential lines

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/, in cl100k tokens of everything the agent sees (the reference plus sqz's one-line note on stderr):

A word on what actually repeats. A user who counted 92 of their own Claude Code sessions (script) found identical whole-file re-reads in 1 of 542 reads, and line-range re-reads in 8.4% 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. The entries are its hooks and two allow rules, Bash(set -o pipefail) and Bash(sqz compress --cmd *), which cover only the parts its rewrite adds. sqz does not approve commands; your own permission rules still decide. When Claude Code asks before a rewritten command, or denies it, its message quotes the rewritten command, such as set -o pipefail; git tag v0 2>&1 for git tag v0.

Plain sqz init (project scope) is useful when you want sqz active only inside one repo. If ~/.claude/settings.json already has the sqz hooks, it leaves them out of the project file, since they already run in every project.

After installing, sqz doctor checks the whole chain — binary, database, shell hook, which clients are detected vs actually routed through sqz, and whether anything was compressed recently — and prints the fix for each gap it finds. sqz doctor --fix applies those fixes. After upgrading sqz, run it once: it brings hooks and guidance an older version wrote up to date, removes hook files current sqz no longer uses and a project copy of hooks that ~/.claude/settings.json already has, points hooks whose sqz binary is gone at the running one, and notes any hook that still runs a different sqz binary. sqz uninstall removes only sqz's own entries, deletes a file only when nothing else is left in it, and ends by listing the files it kept. Without a terminal to answer its prompt it needs --yes, like sqz reset.

See what sqz would have saved, before installing any hook

If you already use Claude Code or Kiro, your transcripts are on disk. Replay them through the sqz engine and get a counterfactual estimate on your own sessions, computed locally with nothing uploaded. From the author's last week of Kiro IDE work, trimmed to the summary:

$ sqz discover --replay

sqz discover — counterfactual replay (last 7 days) ────────────────────────────────────────────────────────

Kiro IDE: 35 sessions, 155 sub-agent runs, advisory

outputs tokens in avoidable shell 6,297 1,917,662 454,028