squeez MCP server
Commit Nov 13, 2026Compresses bash output and terminal logs by up to 95% to optimize token usage for AI CLI hosts like Claude Code and GitHub Copilot.
Also known as claudioemmanuel/squeez
- Stars
- 232
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is squeez MCP?
squeez compresses bash output and terminal logs by up to 95% to optimize token usage for AI CLI hosts like Claude Code and GitHub Copilot.
Summary generated from the project's README
About squeez MCP server
Reducing token consumption for AI CLI hosts is what squeez achieves by compressing bash output and terminal logs by up to 95%. It is designed for developers using tools like Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI, OpenAI Codex CLI, Pi, and Hermes. By intercepting commands through various hooks, it applies smart filtering, deduplication, and log-template compaction to ensure only the most relevant information reaches the model.
Users can install the tool via curl, npm, or cargo to register hooks across their detected CLI environments. The system uses a reversible compression method where large outputs are stashed in a content-addressed blob, allowing the model to recover lost details using the squeez_retrieve MCP tool. It also features a built-in filter pack with 41 rules for common tools like pip, cargo, and git status to handle specific command outputs intelligently. This ensures that even when aggressive compression occurs, critical identifiers and error signals remain intact.
What you can do with it
- 1Recover lost terminal detailsWhen an AI model needs to see the original uncompressed log, it can use a specific tool to retrieve the stashed data.
- 2Handle massive log filesInstead of hitting context limits with huge outputs, the tool provides a dense summary of the most important lines.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
SQUEEZ_DIRSQUEEZ_SHELL
| Name | Description | |
|---|---|---|
| SQUEEZ_DIR | — | |
| SQUEEZ_SHELL | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubsqueez
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.48.25 – v1.49.1 — session identity, honest per-session stats, Hermes output hook
- Each squeez session knows which host session started it.
squeez inittakes--session-id/--cwd(or--stdinto read the host's session-start payload); the Claude Code hook and the OpenCode plugin pass them.current.json, the finalized summary and the session-start snapshot in the shared hourly log carryhost_session_id, so a stats panel can label a row "the chat that ran the release" instead of "today 07:10". Optional fields; hosts that send nothing change nothing. (#286) - Summaries count only their own session.
finalizesummed every event in the hourly log, which every session of that hour shares — a session that ran oneechoreported the previous session's savings, and summing summaries overcounted ~8×. Events older than the session's start are now skipped. (#284) - Handler stats name the program, not the first word.
cd pkg && cargo testiscargo,export CI=1; npm testisnpm,(cd x && make)ismake;VAR=1prefixes and subshell openers no longer take slots. A full table evicts its least-called name instead of silently dropping new ones (64 → 128 slots). The same fix routescd pkg && cargo testto the test-runner handler. (#285) - Hermes compresses output instead of rewriting commands. The plugin moved from
pre_tool_call+squeez wrap(which had to skip every piped or chained command) to Hermes'stransform_terminal_outputhook: the command runs unchanged, its output goes throughsqueez filter, and the full output is kept on disk, redacted, with its path appended. Contributed by @fire. (#275)
v1.47 – v1.48 — agent metering, squeez doctor, Windows and OpenCode 2.x
- Sub-agent cost is measured, not estimated — the real token usage of a sub-agent replaces the flat
agent_spawn_costguess; a spawn ceiling is enforced atPreToolUseand the metering blind spot (spawns counted only on return) is closed. - Re-read amplification — output that the session history says will be re-read many times is compressed harder.
squeez doctor— self-health check: hook drift and registration per host, config sanity, tracking freshness; each store judged by the host that owns it.- Post-compact state comes back from
SessionStart, notPostCompact(Claude Code does not deliver PostCompact output to the model). - 1M-window models (Fable / Mythos) are detected from the transcript's model-identity record, so budgets, intensity and the banner stop assuming 200K;
context_window_tokenspins it when detection is not possible. - Windows — helper processes spawn without a console window,
bash.exefrom WindowsApps is recognized as the WSL launcher and skipped, the post-exit drain is bounded, MSYS children are killed on timeout, and Codex/Gemini hook commands are bash-prefixed so they actually run. - OpenCode 2.x — the plugin tracks shell completions, runs
initonce per session, builds the wrap command for the shell OpenCode runs (PowerShell / pwsh / bash), starts no child process synchronously, and keeps runtime state in$XDG_STATE_HOME/squeez/opencodeout of the watched config tree. - Correctness — JSON escapes decode on read (backslashes no longer double per save), concurrent
initcannot corrupt an instruction file, every session starts with its own counters, the persona is taught once per session, andwrapfails open when the stash is refused rather than compressing lossily.
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 |
✅ output hook (transform_terminal_output) |
✅ native | ❌ no budget surface | Python plugin (__init__.py + plugin.yaml) at $HERMES_HOME/plugins/squeez-fallback/; opt-in — enable once with hermes plugins enable squeez-fallback |
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 18 tools (16 read-only session-memory queries, squeez_retrieve to expand a compressed output, squeez_stash_search to find one by meaning) 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, staged/unstaged/untracked/conflicted). Exact paths are preserved, never collapsed to counts, and raw porcelain codes never reach the model. In-progress rebase/merge/bisect/cherry-pick — which porcelain omits — is read from .git/ markers rather than a second git status run. Yields to any output flag you passed yourself; degrades to raw output on an unrecognized shape. |
| Preservation guard | On calls that reduce by ≥90%, the surviving fraction of navigation anchors (file paths, file:line refs, error markers, test verdicts) is scored at wrap time. Below preservation_floor (0.70) the verbatim original is stashed even outside the usual size gates and the header carries [anchors: N%] — so over-compression costs a marker, not a re-investigation. |
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 SessionStart hook (source: compact) re-injects squeez's tracked session state (recent files, error snippets, git refs, retrievable blob ids), capped at 4000 chars — 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. |
| ADHD focus mode | focus = adhd shapes output structure rather than length: next action first, numbered steps, one-line state restatement, advisories capped at 5, squeez doctor sorted failures-first with a single closing command. Stacks with any persona. |
| 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) and, when the host provides one, the id and working directory of the host session they came from (host_session_id/cwd). |
| 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 + identifier factsheet, adaptive intensity, net-win gate) + reversible compression (retrieve) + MCP server | Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI, Pi, Hermes | Zero runtime deps (libc only on Unix) |
Up to 95% on bash; cross-call dedup; reversible squeez_retrieve; exact ids (SHAs/UUIDs/tickets) survive every summary; signature-mode for source files; TOON re-encoder (incl. nested JSON); 18 MCP tools; post-compact state re-injection; cache-aware savings proof; 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. |
| teamchong/pxpipe | Local API proxy that renders bulky request context (system prompt, tool docs, old history, big tool_results) as dense PNG images — image tokens are priced by pixel area, so dense text packs ~3.1 chars/image-token vs ~1 as text | Claude Code (/v1/messages), Codex (/v1/responses) |
Node/pnpm; canvas at build time | ~59–70% end-to-end bill cut on Fable 5 traffic; reaches surfaces hooks can't (system prompt, tool docs, history); rigorous per-request count_tokens counterfactual measurement |
Lossy: exact-string recall from images fails on most models (0/15 verbatim on Opus 4.8; silent confabulation, not errors) — default scope is Fable 5 only. Complementary to squeez, not competing: squeez compresses losslessly at the hook layer before content enters context; pxpipe cheapens what remains on the wire. They stack — squeez v1.35.0's factsheet, class-density and cache-aware accounting are ported from its measurement discipline. |
| 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 |
Rewriting a command changes what runs, not just how its output is printed. Compression also has a floor: on low-entropy content there is little to remove, and a transformed format can cost more than it saves. |
| 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.
squeez MCP questions
How much can squeez compress bash output?
It can compress bash output by up to 95%.
Can the AI recover information lost during compression?
Yes, the model can recover any dropped detail using the squeez_retrieve MCP tool by referencing a stashed content-addressed blob.
Which AI CLI hosts are supported?
It supports Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI, OpenAI Codex CLI, Pi, and Hermes.
Does it require any runtime dependencies?
No, it operates with zero new runtime dependencies.