Skip to content
Back to search

sqz

Context compression for AI coding agents: compresses tool output before it enters the model, dedups repeats to 13-token refs. Claude Code, Cursor, Codex, Kiro, Zed, any MCP client. Rust, zero LLM calls.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ojuschugh1/sqz with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ojuschugh1/sqz'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ojuschugh1--sqz/badge.svg)](/listings/ojuschugh1--sqz)

HTML

<a href="/listings/ojuschugh1--sqz"><img src="/api/listings/ojuschugh1--sqz/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**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](https://docs.claude.com/en/docs/claude-code/settings)), 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.

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.

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, nothing uploaded:

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

  Sessions replayed:   24
  Tool outputs:        43
  Tokens (original):   116,598
  Tokens (compressed):  92,560

  Estimated avoidable: 24,038 tokens (20.6%)

  Largest opportunities:

    source                tokens in    avoidable
    web_fetch                 58,102       12,288
    read                      37,085       10,486

It scans `~/.claude/projects` and `~/.kiro/sessions/cli`, or point it anywhere with `--transcripts PATH`. Each session replays against a fresh throwaway cache, so dedup references never pretend to span sessions, and the report says "estimate" because that's what it is: these outputs were not compressed at the time.

**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-trips your config file through a JSON parser to merge the sqz entry, which drops any comments in your `opencode.jsonc` (and the analogous JSON-with-comments files other tools accept). If you've commented your config carefully and want to keep them, install by hand instead.

**OpenCode** — two steps:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 708 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <pre>
  3. ███████╗ ██████╗ ███████╗
  4. ██╔════╝██╔═══██╗╚══███╔╝
  5. ███████╗██║ ██║ ███╔╝
  6. ╚════██║██║▄▄ ██║ ███╔╝
  7. ███████║╚██████╔╝███████╗
  8. ╚══════╝ ╚══▀▀═╝ ╚══════╝
  9. </pre>
  10. </p>
  11. <p align="center">
  12. <strong>Pre-injection context compression and session deduplication for AI coding agents</strong>
  13. </p>
  14. <p align="center">
  15. <sub>
  16. <strong>Real session stats:</strong>
  17. 3,003 compressions ·
  18. <strong>178,442 tokens saved</strong> ·
  19. 24.7% avg reduction · up to
  20. <strong>92%</strong> on output the model already has
  21. </sub>
  22. </p>
  23. <p align="center">
  24. <a href="https://thenextgentechinsider.com/pulse/sqz-tool-cuts-llm-token-use-by-92-for-file-heavy-ai-tasks"><img src="https://img.shields.io/badge/%231_Featured-NextGen_Tech_Insider-ff6600?style=for-the-badge&logo=newspaper&logoColor=white" alt="Featured"></a>
  25. <a href="https://hysenlabs.com/en/projects/ojuschugh1-sqz"><img src="https://img.shields.io/badge/Featured-Hysen_Labs-1f6feb?style=for-the-badge&logo=readme&logoColor=white" alt="Featured on Hysen Labs"></a>
  26. </p>
  27. <p align="center">
  28. <a href="https://crates.io/crates/sqz-cli"><img src="https://img.shields.io/crates/v/sqz-cli?logo=rust&logoColor=white&label=crates.io&color=e6522c" alt="Crates.io"></a>
  29. <a href="https://www.npmjs.com/package/sqz-cli"><img src="https://img.shields.io/npm/v/sqz-cli?logo=npm&logoColor=white&label=npm&color=cb3837" alt="npm"></a>
  30. <a href="https://pypi.org/project/sqz/"><img src="https://img.shields.io/pypi/v/sqz?logo=python&logoColor=white&label=PyPI&color=3775a9" alt="PyPI"></a>
  31. <a href="https://marketplace.visualstudio.com/items?itemName=ojuschugh1.sqz"><img src="https://img.shields.io/badge/VS%20Code-Marketplace-007acc?logo=visual-studio-code&logoColor=white" alt="VS Code"></a>
  32. <a href="https://addons.mozilla.org/en-US/firefox/addon/sqz-context-compression/"><img src="https://img.shields.io/badge/Firefox-Add--on-ff7139?logo=firefox-browser&logoColor=white" alt="Firefox"></a>
  33. <a href="https://plugins.jetbrains.com/plugin/31240-sqz--context-intelligence/"><img src="https://img.shields.io/badge/JetBrains-Plugin-000000?logo=jetbrains&logoColor=white" alt="JetBrains"></a>
  34. <a href="https://discord.gg/j8EEyH5dSB"><img src="https://img.shields.io/discord/1493251029075235076?logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord"></a>
  35. <a href="https://github.com/ojuschugh1/homebrew-sqz"><img src="https://img.shields.io/badge/Homebrew-tap-FBB040?logo=homebrew&logoColor=white" alt="Homebrew"></a>
  36. </p>
  37. <p align="center">
  38. <a href="https://ojuschugh1.github.io/sqz/">Docs</a> ·
  39. <a href="#install">Install</a> ·
  40. <a href="#how-it-works">How It Works</a> ·
  41. <a href="#supported-tools">Supported Tools</a> ·
  42. <a href="#compress-any-mcp-server">MCP Proxy</a> ·
  43. <a href="docs/quality-benchmark.md">Benchmark</a> ·
  44. <a href="CHANGELOG.md">Changelog</a> ·
  45. <a href="https://discord.gg/j8EEyH5dSB">Discord</a>
  46. </p>
  47. <!-- i18n:languages -->
  48. [English](README.md) | [简体中文](i18n/README.zh-CN.md) | [日本語](i18n/README.ja.md) | [한국어](i18n/README.ko.md) | [Español](i18n/README.es.md) | [Português (Brasil)](i18n/README.pt-BR.md)
  49. <!-- /i18n:languages -->
  50. ---
  51. 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.
  52. 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.
  53. ```sh
  54. cargo install sqz-cli sqz-mcp # or: brew install ojuschugh1/sqz/sqz · npm i -g sqz-cli · pipx install sqz
  55. sqz init # hooks + MCP server + agent guidance for every client it finds
  56. ```
  57. <p align="center">
  58. <img src="assets/demo.gif" alt="sqz: a 200-line file is served in full, a re-read of lines 41-80 becomes a line-range reference, cargo test output collapses to the failure, and sqz stats shows both" width="800">
  59. </p>
  60. <sub>Real output from the release binary (<code>assets/demo.tape</code>). Regenerate with <code>vhs assets/demo.tape</code>.</sub>
  61. ```
  62. Without sqz: With sqz:
  63. cat auth.py (200 lines): 1,300 tokens 1,300 tokens (source is served in full)
  64. cargo test (1 failure): 366 tokens 185 tokens (failure, assertion, file:line)
  65. sed -n '41,80p' auth.py: 260 tokens 35 tokens (§ref:…:L41-80§ to the read above)
  66. git status, unchanged: 166 tokens 37 tokens (§ref:…§)
  67. ───────────────────────────────────── ─────────────
  68. Total: 2,092 tokens 1,557 tokens (26% saved, nothing dropped)
  69. ```
  70. 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.
  71. > [!NOTE]
  72. > **Name disambiguation:** this repo, [ojuschugh1/sqz](https://github.com/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.
  73. ## Token Savings
  74. > **24.7%** average reduction across 3,003 real compressions ·
  75. > **13-token** refs for output the model already has ·
  76. > **100%** of agent-critical facts kept in the [quality benchmark](docs/quality-benchmark.md) ·
  77. > **0%** on source code, and on stack traces and credential lines
  78. One developer's week, measured from actual `sqz gain` output:
  79. ```
  80. $ sqz gain
  81. sqz token savings (last 7 days)
  82. ──────────────────────────────────────────────────
  83. 04-13 │ │ 2,329 saved
  84. 04-14 │ │ 0 saved
  85. 04-15 │███ │ 12,954 saved
  86. 04-16 │██ │ 9,223 saved
  87. 04-17 │████ │ 14,752 saved
  88. 04-18 │██████████████████████████████│ 105,569 saved
  89. 04-19 │████████ │ 30,882 saved
  90. 04-20 │█ │ 4,334 saved
  91. ──────────────────────────────────────────────────
  92. Total: 3,003 compressions, 178,442 tokens saved (24.7% avg reduction)
  93. ```
  94. ### Per-command compression
  95. Single-command compression (measured via `cargo test -p sqz-engine benchmarks`):
  96. | Content | Before | After | Saved |
  97. |---|---:|---:|---:|
  98. | Repeated log lines | 148 | 39 | **74%** |
  99. | Large JSON array | 259 | 111 | **57%** |
  100. | JSON API response | 64 | 53 | **17%** |
  101. | Git diff | 61 | 54 | **11%** |
  102. | Prose/docs | 124 | 122 | **2%** |
  103. | Stack trace (safe mode) | 82 | 82 | **0%** |
  104. ### Session-level with dedup
  105. Anything the model already has in its context comes back as a reference, unless the output is too small to beat the reference and its note, in which case it is sent again in full. 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):
  106. | Repeat | Without sqz | With sqz | Saved |
  107. |---|---:|---:|---:|
  108. | Unchanged `git status` run again | 166 | 37 | **78%** |
  109. | Lines 41-80 of a 200-line file read earlier | 260 | 35 | **87%** |
  110. | Same `cargo test` output, nothing changed | 366 | 39 | **89%** |
  111. A word on what actually repeats. A user who counted 92 of their own Claude Code sessions ([script](https://gist.github.com/harrison001/76250b61ad665bf9a377e7096dffdbe0)) 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](docs/stop-rereading-files.md)). Sessions with noisy command output and repeated commands see the biggest wins.
  112. ## Install
  113. **Prebuilt binaries** (no compiler required — works on every platform):
  114. ```sh
  115. # macOS / Linux
  116. curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh
  117. # Windows (PowerShell)
  118. irm https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.ps1 | iex
  119. # Any platform via npm
  120. npm install -g sqz-cli
  121. # macOS / Linux via Homebrew
  122. brew tap ojuschugh1/sqz
  123. brew install sqz
  124. ```
  125. **Build from source via Cargo:**
  126. ```sh
  127. cargo install sqz-cli sqz-mcp
  128. ```
  129. `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.
  130. **Build from source** (`cargo install sqz-cli`) works too, but needs a C toolchain:
  131. - Linux: `build-essential` (apt) or equivalent
  132. - macOS: Xcode Command Line Tools (`xcode-select --install`)
  133. - **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.
  134. Then initialize:
  135. ```sh
  136. sqz init --global # hooks apply to every project on this machine
  137. # or
  138. sqz init # hooks apply to just this project (.claude/settings.local.json)
  139. ```
  140. `--global` writes to `~/.claude/settings.json` (the user scope per the
  141. [Anthropic scope table](https://docs.claude.com/en/docs/claude-code/settings)),
  142. so the sqz hook fires in every Claude Code session on this machine. This is
  143. the common case on first install. Your existing `permissions`, `env`,
  144. `statusLine`, and unrelated hooks in `~/.claude/settings.json` are
  145. preserved — sqz merges its entries rather than overwriting.
  146. The entries are its hooks and two allow rules, `Bash(set -o pipefail)` and
  147. `Bash(sqz compress --cmd *)`, which cover only the parts its rewrite adds.
  148. sqz does not approve commands; your own permission rules still decide.
  149. When Claude Code asks before a rewritten command, or denies it, its message
  150. quotes the rewritten command, such as `set -o pipefail; git tag v0 2>&1` for
  151. `git tag v0`.
  152. Plain `sqz init` (project scope) is useful when you want sqz active only
  153. inside one repo. If `~/.claude/settings.json` already has the sqz hooks, it
  154. leaves them out of the project file, since they already run in every project.
  155. After installing, `sqz doctor` checks the whole chain — binary, database,
  156. shell hook, which clients are detected vs actually routed through sqz, and
  157. whether anything was compressed recently — and prints the fix for each gap
  158. it finds. `sqz doctor --fix` applies those fixes. After upgrading sqz, run it
  159. once: it brings hooks and guidance an older version wrote up to date, deletes
  160. cached output current sqz never caches (sqz 2.1.1 and earlier cached short
  161. credential lines), removes hook files current sqz no longer uses and a
  162. project copy of hooks that `~/.claude/settings.json` already has, points
  163. hooks whose sqz binary is gone at the running one, and notes any hook that
  164. still runs a different sqz binary. `sqz uninstall` removes only sqz's own
  165. entries, deletes a file only when nothing else is left in it, and ends by
  166. listing the files it kept.
  167. Without a terminal to answer its prompt it needs `--yes`, like `sqz reset`.
  168. ### See what sqz would have saved, before installing any hook
  169. If you already use Claude Code or Kiro, your transcripts are on disk. Replay
  170. them through the sqz engine and get a counterfactual estimate on your own
  171. sessions, computed locally with nothing uploaded. From the author's last
  172. week of Kiro IDE work, trimmed to the summary:
  173. ```sh
  174. $ sqz discover --replay
  175. sqz discover — counterfactual replay (last 7 days)
  176. ────────────────────────────────────────────────────────
  177. Kiro IDE: 35 sessions, 155 sub-agent runs, advisory
  178. outputs tokens in avoidable
  179. shell 6,297 1,917,662 454,028 23.7%
  180. file reads 4,880 7,854,071 188,239 2.4%
  181. other MCP servers 1,547 6,717,440 4,234,128 63.0%
  182. already through sqz 260 1,393,517 -
  183. out of reach 4,172 1,282,285 -
  184. Avoidable with no help from the agent: 0 tokens
  185. Avoidable if the agent uses every route: 4,876,395 tokens, 25.4% of all tool output
  186. Of that, 3,816,588 is the MCP proxy's lossy first pass.
  187. ```
  188. Each output is replayed the way sqz could actually have reached it on that
  189. client. Kiro can't let sqz rewrite a tool call, so the first total is zero
  190. there; on Claude Code the shell rows split into commands the hook rewrites
  191. on its own and ones it skips. The second total assumes the agent pipes shell
  192. output through `sqz compress`, reads files with the sqz MCP tools (lossless,
  193. so only repeats count) and runs MCP servers behind `sqz-mcp proxy`, and the
  194. report says how much of that is the proxy cutting long strings and arrays on
  195. first pass. Web fetches, edits and sub-agent results are out of reach on every
  196. client and are counted, not replayed.
  197. It scans `~/.claude/projects` and `~/.kiro/sessions` (Kiro CLI and IDE), or
  198. point it anywhere with `--transcripts PATH`. Each transcript replays against a
  199. fresh throwaway cache, so dedup references never pretend to span sessions,
  200. and the report says "estimate" because that's what it is: these outputs were
  201. not compressed at the time.
  202. **Only using one agent?** Pass `--only` (or `--skip`) to limit which
  203. configs are written:
  204. ```sh
  205. sqz init --only opencode # just OpenCode, nothing else
  206. sqz init --only opencode,codex # OpenCode and Codex
  207. sqz init --skip cursor,windsurf # everything except Cursor and Windsurf
  208. ```
  209. Accepted names: `claude`, `cursor`, `windsurf`, `cline`, `gemini`,
  210. `kiro`, `opencode`, `codex`. Aliases (`claude-code`, `gemini-cli`, `roo`,
  211. `kiro-cli`) also work. `--only` and `--skip` can't be combined.
  212. ### Manual installation (preserve comments in your config)
  213. `sqz init` round-trips your config file through a JSON parser to merge
  214. the sqz entry, which drops any comments in your `opencode.jsonc` (and
  215. the analogous JSON-with-comments files other tools accept). If you've
  216. commented your config carefully and want to keep them, install by hand
  217. instead.
  218. **OpenCode** — two steps:
  219. 1. Drop the plugin file in place. `sqz` prints the generated TS to
  220. stdout so you don't have to hand-write the path-escaping logic:
  221. ```sh
  222. mkdir -p ~/.config/opencode/plugins
  223. sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts
  224. ```
  225. 2. Add the MCP entry to your existing `opencode.jsonc` yourself.
  226. Append this block inside the top-level `mcp` object (create the
  227. `mcp` object if it doesn't exist):
  228. ```jsonc
  229. "sqz": {
  230. "type": "local",
  231. "command": ["sqz-mcp", "--transport", "stdio"],
  232. "enabled": true
  233. }
  234. ```
  235. Comments in the rest of your file stay put. OpenCode auto-discovers
  236. the plugin file; no `plugin` array entry needed (adding one causes
  237. double-loading, see issue #10).
  238. The same plugin file loads on OpenCode 1 and 2. OpenCode 2 does not
  239. load the plugin sqz 2.0.0 and earlier wrote, so after upgrading sqz run
  240. `sqz doctor --fix` (or the `print-opencode-plugin` line above again) to
  241. rewrite it.
  242. **Other tools**: Claude Code and Gemini CLI use plain JSON configs
  243. without comment support, Cursor, Windsurf and Cline get markdown rules
  244. files, and Codex gets a TOML entry in `~/.codex/config.toml` that keeps
  245. your comments, so the automated path is non-destructive there. Use
  246. `sqz init --only <tool>` for those. An existing `.gemini/settings.json`
  247. gets sqz's hook merged in; if it has comments or doesn't parse, `sqz init`
  248. leaves it alone and prints the entry to add by hand.
  249. Run `sqz doctor` afterwards to see what was configured for each client
  250. and which integration tier it is on.
  251. ## How It Works
  252. <p align="center">
  253. <img src="assets/sqz-architecture.png" alt="sqz system architecture" width="700" />
  254. </p>
  255. On transparent clients (Claude Code, Gemini CLI, Copilot CLI, OpenCode) sqz installs a hook that rewrites shell commands so their output goes through sqz before it reaches the AI tool. On advisory clients the agent is told to pipe output through `sqz compress` or use the sqz MCP tools. The table below gives each client's tier.
  256. ```
  257. Claude → git status → [sqz hook rewrites] → compressed output
  258. ```
  259. What gets compressed:
  260. - **Shell output**: per-command formatters (git, cargo, npm/pnpm/yarn/bun, pytest, ruff, mypy, go, docker ps/images, kubectl describe/apply, terraform, gradle, maven, xcodebuild, adb logcat, dotnet, grep/rg, tree, curl, and more)
  261. - **JSON**: strips nulls, empty values and trace and request ids, cuts strings over 500 characters, compact encoding, TOON format, and says how to get the original back; `SQZ_LOSSLESS=1` keeps it whole
  262. - **Logs** — collapses repeated lines
  263. - **Test output** — shows failures only (state-machine parsers for Rust, Go, Python, JS, JVM)
  264. What doesn't get compressed:
  265. - Source code: served in full on first read
  266. - Stack traces, SQL migrations, PEM blocks and credential lines: routed to safe mode and passed through unchanged at any size, and never cached; on the shell hook a per-command formatter may still summarize the rest of a test run around them
  267. - Your prompts and the AI's responses — controlled by the AI tool, not sqz
  268. ## Supported Tools
  269. | Tool | Integration | Setup |
  270. |---|---|---|
  271. | Claude Code | PreToolUse + PostToolUse hooks + MCP server (transparent) | `sqz init` |
  272. | Cursor | `.cursor/rules/sqz.mdc` guidance (advisory); MCP server added by hand | `sqz init` |
  273. | Windsurf | `.windsurf/rules/sqz.md` guidance (advisory); MCP server added by hand | `sqz init` |
  274. | Cline | `.clinerules` guidance (advisory); MCP server added by hand | `sqz init` |
  275. | Gemini CLI | BeforeTool hook (transparent) | `sqz init` |
  276. | Kiro | Steering + MCP server (advisory) | `sqz init` |
  277. | OpenCode | TypeScript plugin for OpenCode 1 and 2 + MCP server (transparent) | `sqz init` |
  278. | Codex CLI | AGENTS.md guidance + MCP server (advisory) | `sqz init` |
  279. | Zed | AGENTS.md guidance + MCP server (advisory) | `sqz init` |
  280. | Copilot CLI | preToolUse hook (transparent), when `~/.copilot` exists | `sqz init` |
  281. | Copilot coding agent (CI) | Repo-level hook, self-bootstraps in the cloud sandbox | `sqz init --ci` + commit |
  282. | Any CI pipeline | [setup-sqz action](https://github.com/ojuschugh1/setup-sqz) — compress logs before an LLM step | `uses: ojuschugh1/setup-sqz@v1` |
  283. | Any MCP server | `sqz-mcp proxy` wraps it, compresses its tool results | see below |
  284. | VS Code | [Extension](https://marketplace.visualstudio.com/items?itemName=ojuschugh1.sqz) | Install from Marketplace |
  285. | JetBrains | [Plugin](https://plugins.jetbrains.com/plugin/31240-sqz--context-intelligence/) | Install from Marketplace |
  286. | Chrome | Browser extension | ChatGPT, Claude.ai, Gemini, Grok, Perplexity |
  287. | [Firefox](https://addons.mozilla.org/en-US/firefox/addon/sqz-context-compression/) | Browser extension | Same sites |
  288. Transparent clients have a hook that routes shell commands through sqz on
  289. its own. On advisory clients sqz saves tokens only when the agent pipes
  290. output through `sqz compress` or calls the sqz MCP tools; the client's
  291. built-in shell and file tools bypass it. `sqz doctor` shows each client's
  292. tier.
  293. ## Compress Any MCP Server
  294. `sqz-mcp proxy` sits between your agent and any stdio MCP server and compresses
  295. what flows back: tool results go through the full sqz pipeline (dedup refs on
  296. repeats, safe-mode for stack traces and secrets, error results untouched), and
  297. verbose tool descriptions get compacted so `tools/list` stops eating your
  298. context window. The proxy injects an `sqz_expand` tool so the agent can recover
  299. any cached original byte-exact; results that mention credentials, a stack trace or
  300. a migration are never cached.
  301. Wrap a server by prefixing its command in your MCP config:
  302. ```json
  303. {
  304. "mcpServers": {
  305. "github": {
  306. "command": "sqz-mcp",
  307. "args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
  308. }
  309. }
  310. }
  311. ```
  312. Flags: `--lazy-tools` shortens every tool description to one sentence and
  313. injects an `sqz_tool_help` tool that serves the full original docs on demand
  314. (some MCP servers spend 10-40k tokens on `tools/list` alone); `--no-desc`
  315. keeps descriptions verbatim; `--no-cache` stores nothing, so it sends no
  316. dedup refs and adds no `sqz_expand` tool. Works with
  317. every MCP client (Claude Code, Cursor, Windsurf, Zed, Codex, Kiro, ...)
  318. because the client just sees a normal MCP server. Full guide, including the
  319. server's own `sqz_read_file` / `sqz_grep` / `sqz_list_dir` tools and per-client
  320. config: [MCP context compression](docs/mcp-context-compression.md).
  321. ## CLI
  322. ```sh
  323. sqz init --global # Install hooks for every project on this machine
  324. sqz init # Install hooks for just this project
  325. sqz init --only kiro # Only configure Kiro (skip the rest)
  326. sqz init --only opencode # Only configure OpenCode (skip the rest)
  327. sqz init --skip cursor # Configure every agent except Cursor
  328. sqz init --ci # Also write .github/hooks/sqz.json for Copilot agent CI runs
  329. sqz compress <text> # Compress (or pipe from stdin)
  330. sqz compress --no-cache # Compress without dedup (always full output)
  331. sqz expand <ref> # Recover original content from a §ref:HASH§ token
  332. sqz compact # Evict stale context to free tokens
  333. sqz reset # Clear dedup cache or compression stats
  334. sqz gain # Show daily token savings (bar chart)
  335. sqz gain --project . # Per-project daily gains
  336. sqz gain --days 30 # Last 30 days
  337. sqz stats # Cumulative compression report (includes regret signals)
  338. sqz stats --cost # Estimated $ saved under a prompt-cached billing model
  339. sqz stats --breakdown # Per-command token usage breakdown
  340. sqz stats --project . # Stats for current project only
  341. sqz stats --project list # List all tracked projects
  342. sqz stats --share # Five-line share card sized for a paste into an issue or post
  343. sqz doctor # Verify sqz is installed, wired into your clients, and active
  344. sqz doctor --fix # Apply the fixes doctor prints (run once after upgrading)
  345. sqz uninstall # Remove sqz's hooks, guidance and MCP entries, keep the rest
  346. sqz discover # Find missed savings (incl. your weakest-compressing commands)
  347. sqz discover --replay # Counterfactual replay of your agent transcripts (Claude Code, Kiro)
  348. sqz recall "auth timeout" # Full-text search everything sqz has compressed
  349. sqz resume # Re-inject session context after compaction
  350. sqz vizit # Live terminal dashboard (like htop for AI agents)
  351. sqz hook claude # Process a PreToolUse hook (Claude Code)
  352. sqz hook claude-post # Process a PostToolUse hook (Claude Code)
  353. sqz hook kiro # Legacy; Kiro now uses steering + MCP (sqz init)
  354. sqz print-opencode-plugin # Print OpenCode plugin TS for manual install
  355. sqz proxy --port 8080 # Local endpoint: compresses an API request body and sends it back, no forwarding
  356. ```
  357. ### Dedup Escape Hatch
  358. When sqz sees the same content twice, it returns a compact `§ref:HASH§` token
  359. instead of the full text. Most models handle this fine, but some (e.g., GLM 5.1)
  360. can't parse the ref format and loop. Four ways to work around this:
  361. ```sh
  362. # 1. Recover original content from a ref
  363. sqz expand a1b2c3d4 # prefix match
  364. sqz expand '§ref:a1b2c3d4§' # paste the whole token
  365. # 2. Compress without dedup (per-invocation)
  366. echo "..." | sqz compress --no-cache
  367. # 3. Disable dedup globally (env var)
  368. export SQZ_NO_DEDUP=1
  369. # 3b. Or just shorten the ref freshness window (seconds, default 1800).
  370. # Useful on clients without a compaction hook; 0 disables refs.
  371. export SQZ_REF_TTL_SECS=300
  372. # 4. MCP passthrough tool (returns input byte-exact, zero transforms)
  373. # Available via tools/list when sqz-mcp is running
  374. ```
  375. ### Recall: search everything sqz has seen
  376. Everything that flows through sqz is indexed locally (SQLite FTS5, on your
  377. machine, nothing leaves it). When your agent compacts its context and loses
  378. that error message from an hour ago, search for it instead of re-running
  379. the command:
  380. ```sh
  381. $ sqz recall "connection refused"
  382. 1. [git · 2h ago] … curl: (7) Failed to connect: >>connection refused<< on port 5432 …
  383. full content: sqz expand 3f9a1c05e2d84b17
  384. ```
  385. Agents get the same thing as the `sqz_recall` MCP tool.
  386. ## Track Your Own Savings
  387. Run `sqz gain` in your shell any time to see your own daily breakdown (see the
  388. Token Savings section above for what the output looks like), and `sqz stats`
  389. for the full cumulative report:
  390. ```sh
  391. $ sqz stats
  392. 📊 sqz compression stats
  393. ──────────────────────────────────────────────────
  394. 178,442 tokens saved
  395. ↓ 24.7% average reduction
  396. Compressions 3,003
  397. Tokens in 721,840
  398. Tokens out 543,398
  399. Tokens saved 178,442
  400. Avg reduction 24.7%
  401. 🗄️ Cache
  402. ──────────────────────────────────────────────────
  403. Entries 43
  404. Size 39.1 KB
  405. ```
  406. Add `--breakdown` to see exactly which commands consume the most tokens:
  407. ```sh
  408. $ sqz stats --breakdown
  409. 🔍 Top Token Consumers
  410. ──────────────────────────────────────────────────────────────────────
  411. command calls tokens in out saved
  412. ──────────────────────────────────────────────────────────────────────
  413. dedup 249 45541 3237 93%
  414. stdin 51 30851 24289 21%
  415. auto 132 18288 7740 58%
  416. echo 17 1050 558 47%
  417. ls -la 8 948 948 0%
  418. cargo build 7 170 145 15%
  419. git status 4 56 8 86%
  420. ──────────────────────────────────────────────────────────────────────
  421. ```
  422. `sqz stats` and `sqz gain` count cl100k tokens of what sqz actually printed,
  423. abbreviation legend and expand hint included. A run of one character class
  424. longer than 2 KB, such as a long separator line, is counted in 2 KB slices,
  425. which can be off by about 1% plus 4 tokens.
  426. ### Honest accounting: cost and regret
  427. Token reduction is not automatically billed-cost reduction — with provider
  428. prompt caching, most context re-transmits at a ~90% discount, and compression
  429. that drops something the agent needed costs extra turns instead
  430. ([arXiv:2607.12161](https://arxiv.org/abs/2607.12161)). sqz measures both
  431. sides instead of hand-waving:
  432. - `sqz stats --cost` estimates dollars saved under a prompt-cached billing
  433. model (cache write ×1.25 once, cache read ×0.10 per subsequent turn), with
  434. every assumption printed and overridable (`--price-in`, `--reread-turns`,
  435. `--cache-write-mult`, `--cache-read-mult`). This is the conservative
  436. estimate: without caching the same savings would bill at full input price
  437. on every turn.
  438. - `sqz stats` reports regret signals: quick re-runs (the agent re-produced
  439. byte-identical output within 2 minutes — the repeat bought nothing; the
  440. Claude Code PostToolUse hook never answers with a reference, so its
  441. repeats count as ordinary compressions) and
  442. ref expands (`§ref§` tokens recovered to original bytes). Both are proxies
  443. for "compression dropped something the model needed." If one command
  444. keeps showing up, its formatter needs work — file an issue.
  445. sqz's design already avoids the failure modes that study measured:
  446. compression is deterministic and query-agnostic (never invalidates provider
  447. prompt caches), only new tool output is touched (history is never rewritten),
  448. commands that follow output, run a server or background a job are left alone
  449. (on Claude Code outside bypass mode, the PreToolUse hook leaves pipelines,
  450. loops and heredocs as written and the PostToolUse hook compresses their
  451. output after a successful run), grouped lists and pipelines (Gemini CLI,
  452. Copilot CLI, Claude Code in bypass mode) skip the per-command formatters,
  453. and the 16-token net-win gate skips compressions that wouldn't pay for their
  454. own markers. A command is also left as written when its rewrite could run a
  455. different set of commands than the original. In `ls ${DEST:?}; echo next`,
  456. piping `ls` on its own would let `echo next` run after the failed expansion
  457. stopped the shell, and where a list goes through sqz as one group, a failed
  458. `cd` in `cd build && make; make test` would skip the group instead of only
  459. `make`.
  460. <img width="3456" height="1918" alt="image" src="https://github.com/user-attachments/assets/d308bc60-81f3-4935-9728-b30534e5b5e5" />
  461. **Per-project filtering:**
  462. ```sh
  463. sqz stats --project . # stats for current project only
  464. sqz stats --project list # list all tracked projects
  465. sqz gain --project . # daily gains for current project
  466. sqz gain --days 30 # last 30 days instead of 7
  467. sqz gain --days 30 --project . # combine both
  468. ```
  469. Stats are stored locally in SQLite under `~/.sqz/sessions.db` — nothing leaves your machine.
  470. ## How Compression Works
  471. 1. **Per-command formatters** for the commands below:
  472. | Ecosystem | Commands |
  473. |---|---|
  474. | Git | status, log, diff, show, stash, remote, fetch, push, pull, add, commit |
  475. | Rust | cargo build/test/clippy/check/nextest |
  476. | JavaScript | npm/pnpm/yarn/bun install/audit/outdated (test and run when they fail), tsc, eslint, biome |
  477. | Python | pytest, ruff, mypy, pip |
  478. | Go | go test (incl. `-json` stream), go build, go vet, golangci-lint |
  479. | Cloud | terraform plan/apply/destroy/refresh/init |
  480. | Containers | docker/podman ps/images, kubectl describe/apply |
  481. | JVM | gradle build/test, maven |
  482. | Mobile | xcodebuild (build + test), adb logcat |
  483. | .NET | dotnet build/publish/test |
  484. | System | grep/rg, tree, curl/wget |
  485. Other commands, including kubectl get and logs, gh, aws, gcloud, ls and find, go through the generic compression pipeline.
  486. 2. **Table compactor** — aligned-column output from tools without a dedicated formatter (`ps aux`, `netstat`, database CLIs) collapses its padding runs to two-space separators. The detector is strict — indented lines, code, YAML, and JSON never match.
  487. 3. **Structural summaries**: the engine has an API that reduces a code file to imports, function signatures and a call graph. The hook and MCP paths do not use it; they serve source in full.
  488. 4. **Dedup cache**: SHA-256 content hash, persistent across sessions. Byte-identical output the model already has = 13-token reference, unless the output is too small to beat the reference and its note. A line range of a file the model already has in full (`sed -n '40,80p'`, `sqz_read_file` with `offset`/`limit`) = `§ref:HASH:L40-80§`. A re-read after a small edit = the changed lines with one unchanged line on each side, through the sqz MCP tools (the shell hook sends the edited file again); edits spread through the file come back in full. References are only served while the original is still in context (30-minute window, tunable via `SQZ_REF_TTL_SECS`, reset on compaction).
  489. 5. **JSON pipeline**: drop `trace_id`, `debug_info` and `metadata.internal_id` → strip nulls → flatten nested objects into dotted keys → cut strings over 500 characters to their first 500 characters followed by `...` → collapse arrays over 32,000 characters to their leading items → drop bookkeeping fields (`__v`, `etag`, `request_id`, `x_request_id`, `correlation_id`) and fields whose value is an empty string, array or object, at any depth → TOON encoding (lossless compact format). On the shell hook, compressed JSON ends with a `[full output: sqz expand <prefix>]` line, and `sqz expand` returns the original byte-exact; the MCP `compress` tool points at its `expand` tool the same way. To keep output as it came instead, apart from ANSI codes, set `SQZ_LOSSLESS=1` in the environment or pass `sqz compress --lossless`: no formatter or lossy stage runs, and repeats still come back as a `§ref:HASH§`.
  490. 6. **Safe mode**: stack traces (a trace header followed by its frames), SQL DDL at the start of a line, PEM blocks and credential lines (`key=value` or `key: value` with a secret-looking key), with or without ANSI colors, skip the pipeline and pass through unchanged at any size, with only ANSI codes stripped, and are never cached. On the shell hook a per-command formatter still runs first. Its summary is used only when it keeps every line of each paragraph that holds one of them unchanged, so it may summarize the rest of a test run around a trace; otherwise the whole output passes through. Output that only mentions a password, key, trace or migration outside those structures is compressed as usual but is not cached either, so anything a lossy stage drops from it cannot be expanded.
  491. If a stage panics, `sqz compress` prints the input unchanged with one line on stderr and keeps the command's exit status, and the Claude Code PostToolUse hook leaves the result as it was.
  492. Measured quality, including what each stage drops and what it never touches: [quality benchmark](docs/quality-benchmark.md). For the full technical details, see [docs/](docs/README.md).
  493. ## Configuration
  494. ```toml
  495. # ~/.sqz/presets/default.toml
  496. [preset]
  497. name = "default"
  498. version = "1.0"
  499. [compression.condense]
  500. enabled = true
  501. max_repeated_lines = 3
  502. [compression.strip_nulls]
  503. enabled = true
  504. [budget]
  505. warning_threshold = 0.70
  506. default_window_size = 200000
  507. ```
  508. ### Per-project database
  509. Everything sqz persists (stats, dedup cache, sessions) lives in one SQLite
  510. file, `~/.sqz/sessions.db` by default. Set `SQZ_DB_PATH` to keep it
  511. per-project instead:
  512. ```sh
  513. # e.g. in the project's .envrc (direnv)
  514. export SQZ_DB_PATH="$PWD/.sqz/sessions.db"
  515. ```
  516. Every surface honors it — the shell hook, `sqz stats`/`gain`/`expand`, and
  517. the MCP server (set it under `env` in your MCP config). Prefer absolute
  518. paths: relative values resolve against whatever directory the process runs
  519. from. The parent directory is created if missing (mode 0700, like `~/.sqz`).
  520. ## Privacy
  521. - Zero telemetry — no data transmitted, no crash reports
  522. - Fully offline — works in air-gapped environments
  523. - All processing local
  524. ## Development
  525. ```sh
  526. git clone https://github.com/ojuschugh1/sqz.git
  527. cd sqz
  528. cargo test --workspace
  529. cargo build --release
  530. ```
  531. ## License
  532. sqz is licensed under either of the [Apache License, Version 2.0](LICENSE-APACHE), or the [MIT license](LICENSE-MIT), at your option.
  533. Copyright 2026 Ojus Chugh
  534. Releases up to and including 2.0.0 were published under the [Elastic License 2.0](https://github.com/ojuschugh1/sqz/blob/v2.0.0/LICENSE).
  535. Contributions are accepted under the [Contributor License Agreement](CLA.md).
  536. ## Links
  537. - [Documentation index](docs/README.md)
  538. - [How to stop AI coding agents from re-reading the same files](docs/stop-rereading-files.md)
  539. - [MCP context compression](docs/mcp-context-compression.md)
  540. - [Quality benchmark: compression ratio vs information preservation](docs/quality-benchmark.md)
  541. - [Context rot vs context compression](docs/context-rot.md)
  542. - [Choosing a context compression approach](docs/comparison.md)
  543. - [White Paper: Pre-Injection Context Compression](docs/whitepaper.md)
  544. - [Token Savings Benchmark](docs/benchmark.md)
  545. - [Discord](https://discord.gg/j8EEyH5dSB)
  546. - [Changelog](CHANGELOG.md)
  547. - MCP Registry name: `mcp-name: io.github.ojuschugh1/sqz`
  548. ## Star History
  549. If sqz saved you tokens today, a star helps other people find it. `sqz stats --share` prints your own numbers if you want to show them.
  550. <a href="https://star-history.dera.page/#ojuschugh1/sqz&Date">
  551. <picture>
  552. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=ojuschugh1/sqz&type=Date&theme=dark" />
  553. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=ojuschugh1/sqz&type=Date" />
  554. <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=ojuschugh1/sqz&type=Date" width="600" />
  555. </picture>
  556. </a>
  557. ## Contributors
  558. Thanks to everyone who has contributed code, fixes, and ideas to sqz:
  559. <a href="https://github.com/ojuschugh1/sqz/graphs/contributors">
  560. <img src="https://contrib.rocks/image?repo=ojuschugh1/sqz" alt="sqz contributors" />
  561. </a>
  562. And to everyone who filed the detailed bug reports behind our fixes. Precise repros make this project better with every release. Want to join them? PRs are reviewed fast: see the [open issues](https://github.com/ojuschugh1/sqz/issues) to get started.
  563. <sub>Contributor grid made with [contrib.rocks](https://contrib.rocks).</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.