Squeez

squeez

[](https://github.com/claudioemmanuel/squeez/actions/workflows/ci.yml) [](https://www.npmjs.com/package/squeez) [](https://crates.io/crates/squeez) [](LICENSE) [](CONTRIBUTING.md#license--contributor-sign-off) [](CHANGELOG.md)

End-to-end token optimizer for Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI, and OpenAI Codex CLI. Compresses bash output up to 95%, collapses redundant calls, and injects a terse prompt persona — automatically, with zero new runtime dependencies.

---

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 x8664/aarch64, Windows x8664). 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 |

Manage

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

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

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=""] 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] 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. | | 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. | | Config CLI + /squeez | squeez config get/set/list/reset/path reads and writes config.ini safely (schema validation, comment-preserving writes). squeez setup installs a /squeez slash command that drives it in natural language from inside the session. | | Post-compact re-injection | After /compact, the PostCompact hook re-injects squeez's tracked session state (recent files, error snippets, git refs, retrievable blob ids) as additionalContext — so concrete state survives compaction instead of being re-discovered. | | Bash-wrap safety | Risky commands (rm -rf, git push --force, npm publish, … — configurable bash_risk_patterns) and bypassed commands run unwrapped, so the host's native permission rules evaluate the original command. wrap_bash = false disables wrapping entirely. See [SECURITY.md](SECURITY.md). | | Token estimate | Compression-timing decisions use a code- and CJK-aware token estimate rather than a flat chars/4 (punctuation-dense code and CJK no longer undercount). | | Auto-teach payload | squeez protocol (or the squeez_protocol MCP tool) prints a 2.4 KB self-describing payload — the LLM learns squeez's markers and protocol on first call. | | Caveman persona | Injects an ultra-terse prompt at session start so the model responds with fewer tokens. | | Memory-file compression | squeez compress-md compresses CLAUDE.md / AGENTS.md / copilot-instructions.md in-place — pure Rust, zero LLM. i18n-aware: set lang = pt (or --lang pt) for pt-BR article/filler/phrase dropping and Unicode-correct matching. | | Session memory | On SessionStart, injects a structured summary of the previous session: files investigated, learned facts (errors + git events), completed work (builds, test passes), and next steps (unresolved errors, failing tests). Summaries carry temporal validity (valid_from/valid_to). | | Token tracking | Every PostToolUse result (Bash, Read, Grep, Glob, Monitor, SubagentStop) feeds a SessionContext so squeez knows what the agent has already seen. Read/Grep/Glob/Monitor outputs are also rewritten via updatedToolOutput (Claude Code v2.1.119+) when content is redundant or oversized. | | Token economy | Sub-agent cost tracking (~200K tokens/spawn), burn rate prediction ([budget: ~N calls left]), session efficiency scoring, tool result size budgets. | | Auto-calibration | squeez calibrate runs benchmarks on install and generates an optimized config.ini (aggressive / balanced / conservative profiles). |

---

How squeez compares

There are now several token-reduction tools targeting AI coding CLIs. They make different bets — the right one depends on what you care about: zero deps, lossless filtering, structural reformatting, or task-conditioned ML.

| Tool | Approach | Hosts | Deps | Key wins | Trade-off | |------|----------|-------|------|----------|-----------| | squeez (this project) | Hook + filter pipeline + context engine (MinHash dedup, log-template, relevance truncation, summarize, adaptive intensity) + reversible compression (retrieve) + MCP server | Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI | Zero runtime deps (libc only on Unix) | Up to 95% on bash; cross-call dedup; reversible squeez_retrieve; signature-mode for source files; TOON re-encoder (incl. nested JSON); 17 MCP tools; post-compact state re-injection; enterprise (Bedrock/Vertex) USD-saved estimate | Heuristic, not ML — no per-task understanding | | chopratejas/headroom | Library + HTTP proxy + MCP; compresses tool output, logs, RAG chunks and conversation history at the API layer with real tokenizers and ML (Kompress/Magika) | Any (OpenAI/Anthropic/Bedrock/Vertex via proxy) | Python + Rust; PyTorch/HF models | 60-95%; reaches conversation history (the biggest sink) via the proxy; reversible CCR; image compression | Heavier (proxy + ML deps); not a zero-dep drop-in hook. squeez adopts its reversible-retrieve and post-compact ideas within the zero-dep hook model. | | rtk-ai/rtk | Hook proxy that rewrites bash commands (git status → rtk git status), then compresses 100+ command outputs | Claude Code, Cursor | Zero deps (Rust) | 60-90% on 100+ commands; rtk read -l aggressive for signature mode | rtk#582: aggressive rewriting can increase total cost by 18% because Claude emits +50% more output tokens to compensate for stripped context. squeez ships a guard against this regime. | | KRLabsOrg/squeez | Task-conditioned ML (Qwen 2B / ModernBERT 150M) — pipe tool output + task description, get back only relevant lines | Any (CLI tool) | Python, PyTorch / vLLM server | 92% compression, F1 0.80; task-aware (same log slices kept differently per query) | Requires running an LLM locally; not zero-dep. Same project name, different design. | | ojuschugh1/sqz | CLI context compressor | Any | Python | Single-command compression | Lower coverage than the others. | | LLMLingua-2 (Microsoft) | Neural prompt compressor that removes 50-80% of a prompt while preserving meaning | API / library | Python, transformers | Strong on long static prompts | Latency + model dep; not a CLI hook. | | TOON | Schema-aware JSON replacement (users[100]{id,name,role}:) — ~40% fewer tokens on arrays of uniform objects | Library, not a CLI | TypeScript SDK | Lossless on the right shape; squeez embeds a TOON encoder for gh/kubectl/aws/gcloud/az JSON outputs | Only helps on uniform JSON shapes. |

If you want a CLI hook that just works, never needs a Python runtime, and never silently inflates your output tokens, squeez is the safe default. If you can run an LLM next to your shell and want task-aware filtering, KRLabsOrg/squeez is worth a look as a complement. The two squeez projects share a name but are independent.

---

Scope & Limits

squeez optimizes what it can reach — the surfaces exposed by each host's hook API. It cannot fix token leaks outside those surfaces.

Coverage table

| Surface | How | When | Supported hosts | |---|---|---|---| | Bash stdout/stderr | PreToolUse wraps command w/ the filter pipeline (smart-filter → dedup → log-template → relevance-truncation; original stashed for squeez_retrieve). Risky/bypassed commands run unwrapped under native permission rules. | Every Bash invocation | all 5 | | Read / Grep / Glob limits | PreToolUse injects limit / head_limit per read_max_lines / grep_max_results | Every Read/Grep/Glob call | Claude Code, Copilot, OpenCode (hard); Gemini + Codex soft via GEMINI.md / AGENTS.md | | Read / Grep / Glob / Monitor output rewrite | PostToolUse runs squeez compress-output and returns updatedToolOutput when content is redundant or oversized | Claude Code v2.1.119+ | Claude Code | | Agent / Task prompt | PreToolUse compresses tool_input.prompt (markdown-aware, via compress-prompt) | When prompt > agent_prompt_max_tokens | Claude Code (post–v1.8.0) | | Sub-agent output | SubagentStop hook feeds last_assistant_message into SessionContext for cross-call dedup | On every sub-agent completion | Claude Code | | Compaction lifecycle | PreCompact logs the event; PostCompact re-injects tracked session state (files, errors, git refs, retrievable blob ids) as additionalContext so it survives compaction | On context compaction | Claude Code | | Session memory | SessionStart injects prior session summary + file-access cache | Once per session start | all 5 | | Markdown viewing | Bash handler routes .md reads through compress-md when auto_compress_md=true | Viewer commands on .md paths | all 5 |

What squeez CANNOT compress

Agent/Task returned output. No hook API surface exists to rewrite an Agent's return value. PostToolUse updatedToolOutput (Claude Code v2.1.119+) covers built-in tools (Read, Grep, Glob, Monitor) but not the Agent/Task result. Workaround: keep agent prompts compact (squeez compresses at dispatch time via PreToolUse), and use squeez_agent_costs MCP tool to monitor spawn overhead.

Skills & slash-command files. Claude Code loads these into the system prompt before any hook fires. squeez has no visibility into session-start system prompt construction.

User's top-level prompt. squeez runs per tool call, not on user turns.

Tools whose host doesn't expose PreToolUse / BeforeTool. E.g. Codex apply_patch hooks landed in 0.123.0, but updatedInput is explicitly unsupported and read_file/grep still have no hook surface (openai/codex#18491) — so Read/Grep caps for Codex are soft hints in AGENTS.md, not hard injections.

Secondary wins (not compression, but token-saving)

• Cross-call redundancy dedup — exact-hash and fuzzy-trigram collapsing across 16 recent calls (see [Context engine](#what-it-does))
• Skill re-injection dedup — when the same skill body is injected by the Skill tool more than once in a session, the repeat collapses to [squeez: identical to Skill #N]. Keyed by body hash in a session-long store (not the 16-call window), so it fires even when injections recur far apart
• File-access cache — subsequent Bash commands trimmed when re-reading a file squeez has already fingerprinted
• Burn-rate warnings — [budget: ~N calls left] nudges so the user changes behavior before context pressure spikes

Reducing overall session cost

squeez cannot automate these, but you can:

• Fewer Agent/Task dispatches per session → use squeez_agent_costs to track, then refactor tasks to batch work
• Smaller prompts injected into agents → squeez compresses them at dispatch, but smaller is better
• Shorter CLAUDE.md / AGENTS.md files → run squeez compress-md --ultra to drop abbreviations and filler

---

Benchmarks

Measured on macOS (Apple Silicon). Token count = chars / 4 (matches Claude's ~4 chars/token). Run squeez benchmark to r

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: claudioemmanuel
• Source: claudioemmanuel/squeez
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.