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-playbookand more. Every rule ships an inline self-test that CI gates on. Project and user rules still shadow any built-in;builtin_filters = falseturns the pack off. git statusreads as porcelain — re-run asgit status --porcelain=v1 -band 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 secondgit status.- The preservation guard actually runs.
economy::preservationused to execute only inbenchmark. 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 planandnpx terraform planreach 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, |