squeez

End-to-end token optimizer for seven AI CLI hosts — Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI, OpenAI Codex CLI, Pi, and Hermes. Compresses bash output up to 95%, collapses redundant calls, preserves exact identifiers through every summary, refuses net-loss compressions, and injects a terse prompt persona — automatically, with zero new runtime dependencies.

📰 What's new

Latest first. Full history in CHANGELOG.md.

v1.46.0 — shipped filter pack + native git status

The filter DSL could always cover the long tail GenericHandler can't compress — it just shipped empty, so every user started from a blank filters.ini. This release fills it, adds a native git status path, and makes two guards that were only ever measured in benchmarks run for real.

• 41 built-in filter rules (assets/filters_builtin.ini) — pip/uv/poetry, bundle/composer/rubocop/phpstan, dotnet/swift/gcc, mypy/basedpyright/golangci-lint, shellcheck/hadolint/yamllint/markdownlint/pre-commit, systemctl/journalctl/rsync/ping/ansible-playbook and more. Every rule ships an inline self-test that CI gates on. Project and user rules still shadow any built-in; builtin_filters = false turns the pack off.

• git status reads as porcelain — re-run as git status --porcelain=v1 -b and rendered as a working-tree summary. Exact paths are never collapsed to counts, raw porcelain codes never reach the model, and in-progress rebase/merge/bisect (which porcelain omits) is read from .git/ markers instead of a second git status.

• The preservation guard actually runs. economy::preservation used to execute only in benchmark. It now scores anchor survival at wrap time on ≥90%-reduction calls; below the floor the verbatim original is stashed and the header carries [anchors: N%].

• The net-win gate counts its own marker. The ~40-token retrieve marker was appended after the gate decided the call was a win, so a call saving 25 tokens could ship a 40-token marker and still claim a win. It is now inside the arithmetic.

• Dispatch blind spots closed — TF_LOG=debug terraform plan and npx terraform plan reach the terraform branch; wrappers peel in a loop (sudo npx vitest); a pipeline ending in a transforming stage (cargo build | grep error) dispatches on that stage.

• Benchmarks grew to 46 scenarios, six of them covering the new rule pack, so the pack's contribution is measured rather than asserted.

Install

Three methods — all produce the same result (binary at ~/.claude/squeez/bin/squeez, hooks registered).

curl (recommended)

curl -fsSL https://raw.githubusercontent.com/claudioemmanuel/squeez/main/install.sh | sh

Windows: requires Git Bash. Run the command above inside Git Bash — PowerShell/CMD are not supported.

npm / npx

# Install globally
npm install -g squeez

# Or run once without installing
npx squeez

Downloads the correct pre-built binary for your platform (macOS universal, Linux x86_64/aarch64, Windows x86_64). Requires Node ≥ 16.

cargo (build from source)

cargo install squeez

Builds from crates.io. Requires Rust stable. On Windows you also need MSVC C++ Build Tools.

Supported hosts

squeez setup auto-detects every CLI present on disk and registers the hooks. squeez uninstall removes them. Session data and config.ini are preserved so reinstall is lossless.

Host Memory file Bash wrap Session memory Budget inject (Read/Grep) Notes

Claude Code ~/.claude/CLAUDE.md ✅ native ✅ native ✅ native Restart Claude Code to pick up hooks

Copilot CLI ~/.copilot/copilot-instructions.md ✅ native ✅ native ✅ native Restart Copilot CLI after setup

OpenCode ~/.config/opencode/AGENTS.md ✅ native ✅ native ✅ native Plugin at ~/.config/opencode/plugins/squeez.js; MCP tool calls skip hooks (upstream sst/opencode#2319)

Gemini CLI ~/.gemini/GEMINI.md ✅ native ✅ native 🟡 soft via GEMINI.md BeforeTool rewrite schema pending upstream docs (google-gemini/gemini-cli#25629)

Codex CLI ~/.codex/AGENTS.md ✅ native ✅ native 🟡 soft via AGENTS.md apply_patch hooks landed in 0.123.0 (#18391); updatedInput + read_file/grep hook surface still pending (openai/codex#18491)

Pi ~/.pi/agent/skills/squeez/SKILL.md ✅ native ✅ via skill ✅ native TypeScript extension at ~/.pi/agent/extensions/squeez/index.ts; restart Pi after setup

Hermes ~/.hermes/profiles/default/SOUL.md ✅ native ✅ native ❌ no budget surface Python plugin (__init__.py + plugin.yaml) auto-discovered by Hermes; detected via ~/.hermes/

Manage

squeez setup                  # register into every detected host
squeez setup --host=<slug>    # register into one host
squeez uninstall              # remove squeez entries from every detected host
squeez uninstall --host=<slug>

Slugs: claude-code / copilot / opencode / gemini / codex / pi / hermes.

After install, restart the CLI you use to pick up the new hooks.

Uninstall

squeez uninstall              # preserves session data + config.ini
bash ~/.claude/squeez/uninstall.sh   # (legacy) full wipe, if the script exists

Self-update

squeez update             # download latest binary + verify SHA256
squeez update --check     # check for update without installing
squeez update --insecure  # skip checksum (not recommended)

What it does

Feature Description

Bash compression Intercepts every command via PreToolUse hook, applies smart filter → dedup → log-template → relevance-truncation. Up to 95% reduction. (Per-dir grouping stays reserved for git status, where the path list is the payload.)

Reversible compression When a large output is compressed, the verbatim original is stashed in a content-addressed blob and a [squeez: … call squeez_retrieve with key="<id>"] marker is emitted. The model recovers any dropped detail via the squeez_retrieve MCP tool — so compression can be aggressive without losing information. TTL-pruned, zero-dep.

Log-template compaction Collapses near-identical log lines that differ only by a timestamp, id, hex hash, or 1ms-style value into one [×N] <template> line — what dedup (exact-only) leaves on the table.

Relevance-aware truncation When the generic handler must truncate, it keeps the highest-relevance lines (error/signal words + terms drawn from the command) instead of a blind head — so a buried error survives.

Context engine Cross-call redundancy with two paths: exact-hash match (FNV-1a, fast) and fuzzy trigram-shingle Jaccard ≥0.85 (whitespace, timestamps, single-line edits no longer defeat dedup).

Summarize fallback Outputs exceeding 500 lines are replaced with a ≤40-line dense summary (top errors, files, test result, tail). Benign outputs get 2× the threshold so successful builds stay verbatim.

Identifier factsheet Exact identifiers in the region a summary drops — git SHAs, UUIDs, ticket codes, versions, large ids — ride along in every dense summary (ids_preserved: / "ids":[...]). Deterministic, budget-capped (16 facts / 256 chars), so lossy summarization never silently loses a hash or ticket number.

Net-win gate The # squeez header itself costs ~15–25 tokens. When applied compression saves less than net_win_min_tokens (default 24), the call becomes a verbatim passthrough with zero savings recorded — no net-loss invocations.

Adaptive intensity Truly adaptive: Full (×0.6 limits) below 80% of token budget, Ultra (×0.3) above. Used to be always-Ultra; now actually responds to session pressure.

MCP server squeez mcp runs a JSON-RPC 2.0 server over stdio exposing 17 tools (16 read-only session-memory queries + squeez_retrieve to expand a compressed output) so any MCP-compatible LLM can query session memory directly. Hand-rolled, no mcp.server dependency.

Built-in filter pack 41 shipped filter-DSL rules (assets/filters_builtin.ini) covering the long tail with no dedicated handler — pip/uv/poetry, bundle/composer/rubocop/phpstan, dotnet/swift/gcc, mypy/basedpyright/golangci-lint, shellcheck/hadolint/yamllint/markdownlint/pre-commit, systemctl/journalctl/rsync/ping/ansible-playbook, and more. Every rule carries an inline self-test that squeez filter-test and CI gate on. A project or user rule of the same name shadows a built-in; builtin_filters = false turns the pack off.

git status porcelain git status is re-run as git status --porcelain=v1 -b and rendered as a working-tree summary (branch, ahead/behind,