Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

sqz: context compression for AI coding agents

sqz compresses tool output before it enters the model’s context window. It runs as a shell hook on Claude Code, Gemini CLI, Copilot CLI and OpenCode, as agent guidance on Kiro, Codex, Zed, Cursor, Windsurf and Cline, as an MCP server, and as a proxy in front of any other MCP server. Deterministic Rust, no LLM calls, offline, and every compressed result can be recovered byte-exact unless it mentions credentials, a stack trace or a migration, which sqz never caches.

cargo install sqz-cli sqz-mcp     # or: brew install ojuschugh1/sqz/sqz · npm i -g sqz-cli · pipx install sqz
sqz init                          # installs a hook or agent guidance, and the MCP server where it can, for each client it finds

Then work as usual. sqz stats --breakdown shows what it saved, per command, from your own sessions. sqz doctor verifies the whole chain: binary, database, shell hook, which clients are actually routed through sqz, and whether anything was compressed recently.

Not installed yet? If you already use Claude Code or Kiro, sqz discover --replay replays your existing transcripts through the engine and reports, per client, what sqz could have saved: what a hook saves with no help from the agent, and what needs the agent to route output through sqz. It’s a counterfactual estimate on your own sessions, computed locally.

Where the tokens actually go

Across 3,003 real compressions sqz saved 178,442 tokens, a 24.7% average reduction. That number is deliberately not the headline, because most of the tools in this space are graded on ratio alone, and a compressor that hits 90% by dropping the line the agent needed has made the session more expensive.

What the data shows instead:

  • Command output dominates. Build logs, test runs, git status, package installs. A 366-token cargo test with one failure becomes the failure, the assertion and the file:line, 185 tokens including sqz’s own stderr line (cl100k). Commands such as git, cargo, npm, pytest, go, docker ps and terraform have purpose-built formatters; other output goes through a generic pipeline that folds repeated lines, leaves source code alone, and passes stack traces, migrations and credential lines through unchanged.
  • Identical file re-reads are rare. Measured on 92 Claude Code sessions by a user who counted: 1 in 542 reads. What repeats is unchanged command output (a 13-token §ref§), line ranges of a file already read in full (a §ref:HASH:L40-80§), and files re-read after a small edit (a line-level delta through the sqz MCP tools).
  • Over-compression is tracked, not hidden. sqz stats reports how often the agent re-ran a command whose output had not changed, or asked for an original back. Those regret signals sit next to the savings so you can discount the number yourself.

Guides

Measurements

Integrations

Reference