Pre-injection context compression for coding agents. Zero LLM calls, zero telemetry, offline-safe.
MCP Server: io.github.ojuschugh1/sqz
The io.github.ojuschugh1/sqz MCP server provides pre-injection context compression for coding agents. It operates with “Zero LLM calls” and “zero telemetry” and is described as “offline-safe,” with the goal of reducing token usage and related cost.
🛠️ Key Features
Pre-injection context compression for coding agents
Zero LLM calls
Zero telemetry
Offline-safe operation
Token reduction metrics reported (e.g., 3,003 compressions; 178,442 tokens saved; 24.7% avg reduction; up to 92% with dedup)
🚀 Use Cases
Compressing LLM context before injection to save tokens
Reducing context size for agent workflows
Token optimization for coding agents
⚡ Developer Benefits
Lower token usage via compression
Reported token savings and reduction rates (including dedup up to 92%)
Integration in agentic-ai toolchains across token-focused workflows
⚠️ Limitations
No additional functional details are provided beyond compression, token savings, zero-telemetry, zero-LLM-calls, and offline-safe claims.
sqz compresses command output before it reaches your LLM. Single Rust binary, zero config.
The real win is dedup: when the same file gets read 5 times in a session, sqz sends it once and returns a 13-token reference for every repeat (how that works, and its limits).
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 ·
92% saved on repeated file reads ·
86% on shell/git output ·
13-token refs for cached content
One developer's week, measured from actual sqz gain output:
Single-command compression (measured via cargo test -p sqz-engine benchmarks):
Content
Before
After
Saved
Repeated log lines
148
62
58%
Large JSON array
259
142
45%
JSON API response
64
53
17%
Git diff
61
54
12%
Prose/docs
124
121
2%
Stack trace (safe mode)
82
82
0%
Session-level with dedup
Where the real savings live — the cache sends each file once, repeats cost 13 tokens:
Scenario
Without sqz
With sqz
Saved
Same file read 5×
10,000
826
92%
Same JSON response 3×
192
79
59%
Test-fix-test cycle (3 runs)
15,000
5,186
65%
Single-command compression ranges from 2–58% depending on content. Repeated reads drop to 13 tokens each. Your mileage will vary with how repetitive your tool calls are — agentic sessions with many file re-reads see the biggest wins.
Install
Prebuilt binaries (no compiler required — works on every platform):
sh
# 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:
sh
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:
sh
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:
sh
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:
Drop the plugin file in place. sqz prints the generated TS to
stdout so you don't have to hand-write the path-escaping logic:
Add the MCP entry to your existing opencode.jsonc yourself.
Append this block inside the top-level mcp object (create the
mcp object if it doesn't exist):
Comments in the rest of your file stay put. OpenCode auto-discovers
the plugin file; no plugin array entry needed (adding one causes
double-loading, see issue #10).
Other tools — Claude Code, Cursor, Windsurf, Cline, Gemini CLI,
and Codex use plain JSON configs without comment support, so the
automated path is non-destructive there. Use sqz init --only <tool>
for those.
That's it. Shell hooks installed, AI tool hooks configured.
How It Works
sqz installs a PreToolUse hook that intercepts bash commands before your AI tool runs them. The output gets compressed transparently — the AI tool never knows.
code
Claude → git status → [sqz hook rewrites] → compressed output (85% smaller)
sqz-mcp proxy sits between your agent and any stdio MCP server and compresses
what flows back: tool results go through the full sqz pipeline (dedup refs on
repeats, safe-mode for stack traces and secrets, error results untouched), and
verbose tool descriptions get compacted so tools/list stops eating your
context window. Everything stays reversible — the proxy injects an sqz_expand
tool so the agent can recover any original byte-exact.
Wrap a server by prefixing its command in your MCP config:
Flags: --lazy-tools shortens every tool description to one sentence and
injects an sqz_tool_help tool that serves the full original docs on demand
(some MCP servers spend 10-40k tokens on tools/list alone); --no-desc
keeps descriptions verbatim; --no-cache disables dedup refs. Works with
every MCP client (Claude Code, Cursor, Windsurf, Zed, Codex, Kiro, ...)
because the client just sees a normal MCP server. Full guide, including the
server's own sqz_read_file / sqz_grep / sqz_list_dir tools and per-client
config: MCP context compression.
CLI
sh
sqz init --global # Install hooks for every project on this machine
sqz init # Install hooks for just this project
sqz init --only kiro # Only configure Kiro (skip the rest)
sqz init --only opencode # Only configure OpenCode (skip the rest)
sqz init --skip cursor # Configure every agent except Cursor
sqz init --ci # Also write .github/hooks/sqz.json for Copilot agent CI runs
sqz compress <text> # Compress (or pipe from stdin)
sqz compress --no-cache # Compress without dedup (always full output)
sqz expand <ref> # Recover original content from a §ref:HASH§ token
sqz compact # Evict stale context to free tokens
sqz reset # Clear dedup cache or compression stats
sqz gain # Show daily token savings (bar chart)
sqz gain --project . # Per-project daily gains
sqz gain --days 30 # Last 30 days
sqz stats # Cumulative compression report (includes regret signals)
sqz stats --cost # Estimated $ saved under a prompt-cached billing model
sqz stats --breakdown # Per-command token usage breakdown
sqz stats --project . # Stats for current project only
sqz stats --project list # List all tracked projects
sqz discover # Find missed savings (incl. your weakest-compressing commands)
sqz recall "auth timeout"# Full-text search everything sqz has compressed
sqz resume # Re-inject session context after compaction
sqz vizit # Live terminal dashboard (like htop for AI agents)
sqz hook claude # Process a PreToolUse hook (Claude Code)
sqz hook kiro # Legacy; Kiro now uses steering + MCP (sqz init)
sqz print-opencode-plugin # Print OpenCode plugin TS for manual install
sqz proxy --port 8080 # API proxy (compresses full request payloads)
Dedup Escape Hatch
When sqz sees the same content twice, it returns a compact §ref:HASH§ token
instead of the full text. Most models handle this fine, but some (e.g., GLM 5.1)
can't parse the ref format and loop. Four ways to work around this:
sh
# 1. Recover original content from a ref
sqz expand a1b2c3d4 # prefix match
sqz expand'§ref:a1b2c3d4§'# paste the whole token# 2. Compress without dedup (per-invocation)echo"..." | sqz compress --no-cache
# 3. Disable dedup globally (env var)export SQZ_NO_DEDUP=1
# 4. MCP passthrough tool (returns input byte-exact, zero transforms)# Available via tools/list when sqz-mcp is running
Recall: search everything sqz has seen
Everything that flows through sqz is indexed locally (SQLite FTS5, on your
machine, nothing leaves it). When your agent compacts its context and loses
that error message from an hour ago, search for it instead of re-running
the command:
sh
$ sqz recall "connection refused"
1. [git · 2h ago] … curl: (7) Failed to connect: >>connection refused<< on port 5432 …
full content: sqz expand 3f9a1c05e2d84b17
Agents get the same thing as the sqz_recall MCP tool.
Track Your Own Savings
Run sqz gain in your shell any time to see your own daily breakdown (see the
Token Savings section above for what the output looks like), and sqz stats
for the full cumulative report:
Add --breakdown to see exactly which commands consume the most tokens:
sh
$ sqz stats --breakdown
🔍 Top Token Consumers
──────────────────────────────────────────────────────────────────────
command calls tokens in out saved
──────────────────────────────────────────────────────────────────────
dedup 249 45541 3237 93%
stdin 51 30851 24289 21%
auto 132 18288 7740 58%
echo 17 1050 558 47%
ls -la 8 948 948 0%
cargo build 7 170 145 15%
git status 4 56 8 86%
──────────────────────────────────────────────────────────────────────
Honest accounting: cost and regret
Token reduction is not automatically billed-cost reduction — with provider
prompt caching, most context re-transmits at a ~90% discount, and compression
that drops something the agent needed costs extra turns instead
(arXiv:2607.12161). sqz measures both
sides instead of hand-waving:
sqz stats --cost estimates dollars saved under a prompt-cached billing
model (cache write ×1.25 once, cache read ×0.10 per subsequent turn), with
every assumption printed and overridable (--price-in, --reread-turns,
--cache-write-mult, --cache-read-mult). This is the conservative
estimate: without caching the same savings would bill at full input price
on every turn.
sqz stats reports regret signals: quick re-runs (the agent re-produced
byte-identical output within 2 minutes — the repeat bought nothing) and
ref expands (§ref§ tokens recovered to original bytes). Both are proxies
for "compression dropped something the model needed." If one command
keeps showing up, its formatter needs work — file an issue.
sqz's design already avoids the failure modes that study measured:
compression is deterministic and query-agnostic (never invalidates provider
prompt caches), only new tool output is touched (history is never rewritten),
piped or redirected commands are never intercepted, and the 16-token net-win
gate skips compressions that wouldn't pay for their own markers.
image
Per-project filtering:
sh
sqz stats --project . # stats for current project only
sqz stats --project list # list all tracked projects
sqz gain --project . # daily gains for current project
sqz gain --days 30 # last 30 days instead of 7
sqz gain --days 30 --project . # combine both
Stats are stored locally in SQLite under ~/.sqz/sessions.db — nothing leaves your machine.
How Compression Works
Per-command formatters — 45+ commands across 12 ecosystems get purpose-built compression:
Unknown commands fall through to the generic compression pipeline — no output is ever left uncompressed.
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.
Structural summaries — code files compressed to imports + function signatures + call graph (~70% reduction). The model sees the architecture, not implementation noise.
Dedup cache — SHA-256 content hash, persistent across sessions. Second read = 13-token reference.
Everything sqz persists (stats, dedup cache, sessions) lives in one SQLite
file, ~/.sqz/sessions.db by default. Set SQZ_DB_PATH to keep it
per-project instead:
sh
# e.g. in the project's .envrc (direnv)export SQZ_DB_PATH="$PWD/.sqz/sessions.db"
Every surface honors it — the shell hook, sqz stats/gain/expand, and
the MCP server (set it under env in your MCP config). Prefer absolute
paths: relative values resolve against whatever directory the process runs
from. The parent directory is created if missing (mode 0700, like ~/.sqz).
Privacy
Zero telemetry — no data transmitted, no crash reports
Fully offline — works in air-gapped environments
All processing local
Development
sh
git clone https://github.com/ojuschugh1/sqz.git
cd sqz
cargo test --workspace
cargo build --release
License
Elastic License 2.0 (ELv2) — use, fork, modify freely. Two restrictions: no competing hosted service, no removing license notices.
Thanks to everyone who has contributed code, fixes, and ideas to sqz:
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 to get started.
