![\"Featured\"](\"https://img.shields.io/badge/%231_Featured-NextGen_Tech_Insider-ff6600?style=for-the-badge&logo=newspaper&logoColor=white\"){kind=icon}
\n\n
\n ███████╗ ██████╗ ███████╗\n ██╔════╝██╔═══██╗╚══███╔╝\n ███████╗██║ ██║ ███╔╝\n ╚════██║██║▄▄ ██║ ███╔╝\n ███████║╚██████╔╝███████╗\n ╚══════╝ ╚══▀▀═╝ ╚══════╝\n\n\n\n
\n Compress LLM context to save tokens and reduce costs\n
\n\n\n \n Real session stats:\n 3,003 compressions ·\n 178,442 tokens saved ·\n 24.7% avg reduction · up to\n 92% with dedup\n \n
\n\n\n
\n ![\"Crates.io\"](\"https://img.shields.io/crates/v/sqz-cli?logo=rust&logoColor=white&label=crates.io&color=e6522c\")
![\"npm\"](\"https://img.shields.io/npm/v/sqz-cli?logo=npm&logoColor=white&label=npm&color=cb3837\")
![\"PyPI\"](\"https://img.shields.io/pypi/v/sqz?logo=python&logoColor=white&label=PyPI&color=3775a9\")
![\"VS](\"https://img.shields.io/badge/VS%20Code-Marketplace-007acc?logo=visual-studio-code&logoColor=white\"){kind=icon}
![\"Firefox\"](\"https://img.shields.io/badge/Firefox-Add--on-ff7139?logo=firefox-browser&logoColor=white\"){kind=icon}
![\"JetBrains\"](\"https://img.shields.io/badge/JetBrains-Plugin-000000?logo=jetbrains&logoColor=white\"){kind=icon}
![\"Discord\"](\"https://img.shields.io/discord/1493251029075235076?logo=discord&logoColor=white&label=Discord&color=5865F2\")
![\"Homebrew\"](\"https://img.shields.io/badge/Homebrew-tap-FBB040?logo=homebrew&logoColor=white\"){kind=icon}
\n Install ·\n How It Works ·\n Supported Tools ·\n Changelog ·\n Discord\n
\n\n\n[English](https://github.com/ojuschugh1/sqz/blob/main/README.md) | [简体中文](https://github.com/ojuschugh1/sqz/blob/main/i18n/README.zh-CN.md) | [日本語](https://github.com/ojuschugh1/sqz/blob/main/i18n/README.ja.md) | [한국어](https://github.com/ojuschugh1/sqz/blob/main/i18n/README.ko.md) | [Español](https://github.com/ojuschugh1/sqz/blob/main/i18n/README.es.md) | [Português (Brasil)](https://github.com/ojuschugh1/sqz/blob/main/i18n/README.pt-BR.md)\n\n\n---\n\nsqz compresses command output before it reaches your LLM. Single Rust binary, zero config.\n\nPer-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.\n\n```\nWithout sqz: With sqz:\n\ncat auth.py (200 lines): 1,300 tokens 1,300 tokens (source is served in full)\ncargo test (1 failure): 366 tokens 185 tokens (failure, assertion, file:line)\nsed -n '41,80p' auth.py: 260 tokens 35 tokens (§ref:…:L41-80§ to the read above)\ngit status, unchanged: 166 tokens 37 tokens (§ref:…§)\n───────────────────────────────────── ─────────────\nTotal: 2,092 tokens 1,557 tokens (26% saved, nothing dropped)\n```\n\n## Token Savings\n\n> **24.7%** average reduction across 3,003 real compressions ·\n> **13-token** refs for output the model already has ·\n> **100%** of agent-critical facts kept in the [quality benchmark](https://github.com/ojuschugh1/sqz/blob/main/docs/quality-benchmark.md) ·\n> **0%** on source code, and on stack traces and credential lines\n\nOne developer's week, measured from actual `sqz gain` output:\n\n```\n$ sqz gain\nsqz token savings (last 7 days)\n──────────────────────────────────────────────────\n 04-13 │ │ 2,329 saved\n 04-14 │ │ 0 saved\n 04-15 │███ │ 12,954 saved\n 04-16 │██ │ 9,223 saved\n 04-17 │████ │ 14,752 saved\n 04-18 │██████████████████████████████│ 105,569 saved\n 04-19 │████████ │ 30,882 saved\n 04-20 │█ │ 4,334 saved\n──────────────────────────────────────────────────\n Total: 3,003 compressions, 178,442 tokens saved (24.7% avg reduction)\n```\n\n### Per-command compression\n\nSingle-command compression (measured via `cargo test -p sqz-engine benchmarks`):\n\n| Content | Before | After | Saved |\n|---|---:|---:|---:|\n| Repeated log lines | 148 | 39 | **74%** |\n| Large JSON array | 259 | 111 | **57%** |\n| JSON API response | 64 | 53 | **17%** |\n| Git diff | 61 | 54 | **11%** |\n| Prose/docs | 124 | 122 | **2%** |\n| Stack trace (safe mode) | 82 | 82 | **0%** |\n\n### Session-level with dedup\n\nAnything 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):\n\n| Repeat | Without sqz | With sqz | Saved |\n|---|---:|---:|---:|\n| Unchanged `git status` run again | 166 | 37 | **78%** |\n| Lines 41-80 of a 200-line file read earlier | 260 | 35 | **87%** |\n| Same `cargo test` output, nothing changed | 366 | 39 | **89%** |\n\nSingle-command compression in the first table above ranges from 0% (stack trace) to 74% (repeated log lines) depending on content. Your mileage will vary with how repetitive your tool calls are: sessions with noisy command output and repeated commands see the biggest wins.\n\n## Install\n\n**Prebuilt binaries** (no compiler required — works on every platform):\n\n```sh\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.ps1 | iex\n\n# Any platform via npm\nnpm install -g sqz-cli\n\n# macOS / Linux via Homebrew\nbrew tap ojuschugh1/sqz\nbrew install sqz\n```\n\n**Build from source via Cargo:**\n\n```sh\ncargo install sqz-cli sqz-mcp\n```\n\n`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.\n\n**Build from source** (`cargo install sqz-cli`) works too, but needs a C toolchain:\n\n- Linux: `build-essential` (apt) or equivalent\n- macOS: Xcode Command Line Tools (`xcode-select --install`)\n- **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.\n\nThen initialize:\n\n```sh\nsqz init --global # hooks apply to every project on this machine\n# or\nsqz init # hooks apply to just this project (.claude/settings.local.json)\n```\n\n`--global` writes to `~/.claude/settings.json` (the user scope per the\n[Anthropic scope table](https://docs.claude.com/en/docs/claude-code/settings)),\nso the sqz hook fires in every Claude Code session on this machine. This is\nthe common case on first install. Your existing `permissions`, `env`,\n`statusLine`, and unrelated hooks in `~/.claude/settings.json` are\npreserved — sqz merges its entries rather than overwriting.\nThe entries are its hooks and two allow rules, `Bash(set -o pipefail)` and\n`Bash(sqz compress --cmd *)`, which cover only the parts its rewrite adds.\nsqz does not approve commands; your own permission rules still decide.\nWhen Claude Code asks before a rewritten command, or denies it, its message\nquotes the rewritten command, such as `set -o pipefail; git tag v0 2>&1` for\n`git tag v0`.\n\nPlain `sqz init` (project scope) is useful when you want sqz active only\ninside one repo. If `~/.claude/settings.json` already has the sqz hooks, it\nleaves them out of the project file, since they already run in every project.\n\n**Only using one agent?** Pass `--only` (or `--skip`) to limit which\nconfigs are written:\n\n```sh\nsqz init --only opencode # just OpenCode, nothing else\nsqz init --only opencode,codex # OpenCode and Codex\nsqz init --skip cursor,windsurf # everything except Cursor and Windsurf\n```\n\nAccepted names: `claude`, `cursor`, `windsurf`, `cline`, `gemini`,\n`kiro`, `opencode`, `codex`. Aliases (`claude-code`, `gemini-cli`, `roo`,\n`kiro-cli`) also work. `--only` and `--skip` can't be combined.\n\n### Manual installation (preserve comments in your config)\n\n`sqz init` round-trips your config file through a JSON parser to merge\nthe sqz entry, which drops any comments in your `opencode.jsonc` (and\nthe analogous JSON-with-comments files other tools accept). If you've\ncommented your config carefully and want to keep them, install by hand\ninstead.\n\n**OpenCode** — two steps:\n\n1. Drop the plugin file in place. `sqz` prints the generated TS to\n stdout so you don't have to hand-write the path-escaping logic:\n\n ```sh\n mkdir -p ~/.config/opencode/plugins\n sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts\n ```\n\n2. Add the MCP entry to your existing `opencode.jsonc` yourself.\n Append this block inside the top-level `mcp` object (create the\n `mcp` object if it doesn't exist):\n\n ```jsonc\n \"sqz\": {\n \"type\": \"local\",\n \"command\": [\"sqz-mcp\", \"--transport\", \"stdio\"],\n \"enabled\": true\n }\n ```\n\nComments in the rest of your file stay put. OpenCode auto-discovers\nthe plugin file; no `plugin` array entry needed (adding one causes\ndouble-loading, see issue #10).\n\nThe same plugin file loads on OpenCode 1 and 2. OpenCode 2 does not\nload the plugin sqz 2.0.0 and earlier wrote, so after upgrading sqz run\n`sqz doctor --fix` (or the `print-opencode-plugin` line above again) to\nrewrite it.\n\n**Other tools**: Claude Code and Gemini CLI use plain JSON configs\nwithout comment support, Cursor, Windsurf and Cline get markdown rules\nfiles, and Codex gets a TOML entry in `~/.codex/config.toml` that keeps\nyour comments, so the automated path is non-destructive there. Use\n`sqz init --only