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.
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. |
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. |
| Token estimate | Compression-timing decisions use a content-class calibrated estimate: output is classified Dense/Prose/Mixed and counted at chars/2.0, chars/3.7, or the code- and CJK-aware char-class estimator — dense tool output really runs ~1.9 chars/token in production, not chars/4. Flat legacy path stays available via class_density = false. |
| 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