blog.dopana

Back

Your AI coding agent is not burning tokens on reasoning. It burns them on cargo test output, git status spam, and reading the same file five times.

That is the problem sqz ↗ solves. A single Rust binary that compresses tool output before it enters the model context. No LLM calls, fully offline, byte-exact reversible with sqz expand.

Real session stats from the repo: 3,003 compressions, 178,442 tokens saved, 24.7% average reduction, up to 92-96% on output the model already has.

Why This Matters#

Every agent turn re-sends history. A 1,200-token test log is not paid once — it is paid every turn after that until compaction. Add prompt caching and the math gets subtle, but the direction is clear: noisy tool output shortens sessions, increases cost, and pushes out useful reasoning.

[!NOTE] Token reduction ≠ billed-cost reduction 1:1. With provider prompt caching, repeated context bills at ~90% discount. sqz stats --cost models this honestly instead of hand-waving.

ELI5 mental model: your agent packs a suitcase (context window) for every trip. Right now it stuffs in dirty laundry — full passing tests, unchanged git status, repeated file reads. sqz is the friend who folds, removes duplicates, and leaves a sticky note: “blue shirt already in bag, see pocket 3”.

git, cargo, pytest, docker...unknownyes, in contextnoyesnoAgent tool call: git status, cargotest, cat filesqz PreToolUse hookPer-command formatter?Keep failure, assertion, file:line.Drop noiseGeneric pipeline: collapserepeats, compact tablesSeen before? SHA-256 lookupReturn 13-token §ref:HASH§Stack trace / secret / migration?Safe mode: 0% compression,passthroughCompressed output to model

What Gets Compressed, What Does Not#

Compressed:

  • Shell output — 45+ formatters across 12 ecosystems: git, cargo, npm/pnpm/yarn/bun, pytest, ruff, mypy, go test (incl. -json stream), docker/podman, kubectl, aws, terraform, gcloud, gradle, maven, xcodebuild, adb logcat, dotnet, gh, grep/rg, tree, curl, and more
  • JSON — strip nulls, drop debug fields, flatten, collapse arrays, TOON encoding
  • Logs — collapse repeated lines (max_repeated_lines = 3 by default)
  • Test output — failures only via state-machine parsers for Rust, Go, Python, JS, JVM

Never touched:

  • Source code, stack traces, error messages, secrets → safe mode, 0% compression
  • Your prompts and model responses → owned by the agent framework, not sqz

[!TIP] Every compressed result is recoverable byte-exact: sqz expand <ref>.

The Numbers#

Single-command compression (cargo test -p sqz-engine benchmarks):

ContentBeforeAfterSaved
Repeated log lines1486258%
Large JSON array25914245%
JSON API response645317%
Git diff615412%
Prose/docs1241212%
Stack trace (safe mode)82820%

Session-level with dedup (where sqz wins big):

RepeatWithout sqzWith sqzSaved
Unchanged git status rerun1551392%
Lines 41-80 of 200-line file read earlier3051695%
Same cargo test, nothing changed3031396%

Demo from README:

cat auth.py (500 lines):   4,000 tokens    4,000 tokens  (source served in full)
cargo test (1 failure):    1,200 tokens      120 tokens  (failure + assertion + file:line)
sed -n '40,80p' auth.py:     330 tokens       18 tokens  (§ref:…:L40-80§)
git status, unchanged:       160 tokens       13 tokens  (§ref:…§)
─────────────────────────────────────      ─────────────
Total:                     5,690 tokens    4,151 tokens  (27% saved, nothing dropped)
text

One nuance the author calls out: whole-file re-reads are rarer than lore suggests (1 in 542 reads in one user’s 92-session count). Real repeats are unchanged command output, line ranges, and re-reads after small edits — each gets its own reference type.

Install in 2 Minutes#

install.sh
# macOS / Linux (prebuilt, no compiler)
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh

# Any platform via npm
npm install -g sqz-cli

# macOS via Homebrew
brew tap ojuschugh1/sqz
brew install sqz

# From source
cargo install sqz-cli sqz-mcp
bash

Then:

init
sqz init --global   # every project on machine (~/.claude/settings.json merge)
# or
sqz init            # this project only
sqz init --only opencode,codex  # limit clients
sqz init --skip cursor,windsurf # everything except these
sqz doctor          # verify chain: binary, DB, hooks, recent compressions
bash

[!WARNING] sqz init round-trips opencode.jsonc through a JSON parser and drops comments. To preserve comments, install manually: sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts, then add the sqz-mcp entry by hand.

Try Before You Hook: Counterfactual Replay#

Already use Claude Code or Kiro? Replay existing transcripts locally, nothing uploaded:

discover
sqz discover --replay
# Sessions replayed: 24
# Tool outputs: 43
# Tokens (original): 116,598 → compressed: 92,560
# Estimated avoidable: 24,038 tokens (20.6%)
bash

Each session replays against a fresh throwaway cache, so cross-session dedup never inflates numbers.

CLI Cheat Sheet#

cli
sqz compress "some text"       # or pipe stdin
sqz compress --no-cache        # skip dedup, full output
sqz expand a1b2c3d4            # prefix match, or paste full §ref:…§
sqz gain                       # daily bar chart, last 7 days
sqz gain --days 30 --project . # last 30 days, current project
sqz stats                      # cumulative + regret signals
sqz stats --cost               # $ under prompt-cached billing model
sqz stats --breakdown          # top token consumers per command
sqz recall "connection refused" # FTS5 search over everything compressed
sqz resume                     # re-inject context after compaction
sqz compact                    # proactive eviction: --strategy keep_recent|keep_relevant|keep_errors
sqz vizit                      # htop-like live dashboard
sqz discover                   # weakest-compressing commands
bash

Dedup escape hatch (some models like GLM 5.1 loop on §ref§):

dedup-off
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1          # disable globally
export SQZ_REF_TTL_SECS=300    # shorten ref window (default 1800, 0 = off)
bash

How Compression Works: 6 Stages#

  1. Per-command formatters — purpose-built per tool. cargo test keeps failing test + assertion + file:line. git status becomes compact summary. Unknown commands fall through to generic pipeline — nothing left uncompressed.
  2. Table compactor — collapses padding runs in ps aux, netstat, DB CLIs to two-space separators. Strict detector: indented lines, code, YAML, JSON never match.
  3. Structural summaries — code → imports + signatures + call graph (~70% reduction). Architecture, not implementation noise.
  4. Dedup cache — SHA-256 hash, persistent in SQLite. Byte-identical → 13-token §ref:HASH§. Line range of known file → §ref:HASH:L40-80§. Re-read after small edit → only changed lines. Refs live 30 min (SQZ_REF_TTL_SECS), reset on compaction.
  5. JSON pipeline — strip nulls → project debug fields → flatten → collapse arrays → TOON (lossless compact format).
  6. Safe mode — entropy analysis detects stack traces, secrets, migrations → 0% compression, passthrough.

Sub-millisecond latency (p99 < 5ms to 100KB), ~0.1ms SQLite lookup. Negligible vs LLM inference.

Supported Tools#

ToolIntegrationSetup
Claude Code / Cursor / Windsurf / ClinePreToolUse hook (transparent)sqz init
Gemini CLIBeforeTool hooksqz init
KiroSteering + MCPsqz init
OpenCodeTypeScript pluginsqz init
Codex / ZedAGENTS.md + MCPsqz init
Copilot CLIpreToolUse hooksqz init
Copilot coding agent (CI)repo hook, self-bootstrapssqz init --ci + commit
Any MCP serversqz-mcp proxy -- <server>compresses tool results + tools/list
VS Code / JetBrains / Chrome / FirefoxExtensionsMarketplaces

MCP proxy example — wraps any stdio server:

mcp.json
{
  "mcpServers": {
    "github": {
      "command": "sqz-mcp",
      "args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}
json

Flags: --lazy-tools (one-sentence descs + sqz_tool_help on demand — some servers burn 10-40k tokens on tools/list alone), --no-desc, --no-cache. Proxy injects sqz_expand so agent recovers originals byte-exact.

Honest Accounting: Cost and Regret#

Two signals most compression tools ignore:

  • sqz stats --cost — dollars under prompt-cached billing (cache write ×1.25 once, cache read ×0.10 per turn). Assumptions printed, overridable via --price-in, --reread-turns, --cache-write-mult, --cache-read-mult. Conservative by design.
  • Regret signals in sqz stats — quick re-runs (byte-identical output reproduced within 2 min = repeat bought nothing) and ref expands (§ref§ recovered to bytes = model needed full content). If one command keeps appearing, its formatter needs work — file an issue.

Design avoids known failure modes from arXiv:2607.12161 ↗: deterministic + query-agnostic (never invalidates provider prompt caches), only new tool output touched (history never rewritten), piped/redirected commands never intercepted, 16-token net-win gate skips compressions that would not pay for markers.

Practical Example: Wire Into a Session#

session
# 1. check what you would have saved
sqz discover --replay

# 2. install globally
sqz init --global
sqz doctor

# 3. work normally, then track
sqz gain
sqz stats --breakdown

# 4. recall beats re-running
sqz recall "Failed to connect"
sqz expand 3f9a1c05e2d84b17
bash

Per-project DB isolation with direnv:

.envrc
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"
bash

All surfaces honor it: shell hook, stats/gain/expand, MCP server (env in MCP config). Parent dir created mode 0700.

Configuration#

~/.sqz/presets/default.toml
[preset]
name = "default"
version = "1.0"

[compression.condense]
enabled = true
max_repeated_lines = 3

[compression.strip_nulls]
enabled = true

[budget]
warning_threshold = 0.70
default_window_size = 200000
toml

Privacy#

Zero telemetry, no crash reports, fully offline, air-gap capable. Stats in ~/.sqz/sessions.db (SQLite FTS5). Nothing leaves machine.

When Not to Use sqz#

  • You need verbatim logs for audit — use --no-cache or safe-mode paths, or expand after.
  • Your model cannot parse §ref§ tokens — disable dedup (SQZ_NO_DEDUP=1).
  • Tiny outputs under net-win gate — sqz already skips these (16-token threshold).

Conclusion#

sqz sits at the right boundary: tool execution, not prompt rewriting, not model-specific adapters. One sqz init covers every agent framework, deterministic Rust core keeps p99 under 5ms, and dedup turns repeats into 13-token refs.

Start with sqz discover --replay — if your own transcripts show 20%+ avoidable tokens, install the hook.

References#