Skip to content
Back to search

squeez

Hook-based token compressor for 7 AI CLI hosts (Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI, Pi, Hermes). Up to 95% bash compression, signature-mode for code reads, cross-call dedup, MCP server, self-teaching protocol. Zero runtime deps.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/claudioemmanuel/squeez with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/claudioemmanuel/squeez'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/claudioemmanuel--squeez/badge.svg)](/listings/claudioemmanuel--squeez)

HTML

<a href="/listings/claudioemmanuel--squeez"><img src="/api/listings/claudioemmanuel--squeez/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://git-scm.com/downloads). 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](https://crates.io/crates/squeez). Requires Rust stable. On Windows you also need [MSVC C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-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](https://github.com/google-gemini/gemini-cli/issues/25629)) | | **Codex CLI** | `~/.codex/AGENTS.md` | ✅ native | ✅ native | 🟡 soft via `AGENTS.md` | `apply_patch` hooks landed in 0.123.0 ([#18391](https://github.com/openai/codex/pull/18391)); `updatedInput` + `read_file`/`grep` hook surface still pending ([openai/codex#18491](https://github.com/openai/codex/issues/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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 791 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/banner.png" alt="squeez — hook-based token compressor for AI CLIs" width="100%">
  3. </p>
  4. # squeez
  5. [![CI](https://github.com/claudioemmanuel/squeez/actions/workflows/ci.yml/badge.svg)](https://github.com/claudioemmanuel/squeez/actions/workflows/ci.yml)
  6. [![npm](https://img.shields.io/npm/v/squeez.svg)](https://www.npmjs.com/package/squeez)
  7. [![Crates.io](https://img.shields.io/crates/v/squeez.svg)](https://crates.io/crates/squeez)
  8. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  9. [![DCO](https://img.shields.io/badge/contributions-DCO_signed--off-green.svg)](CONTRIBUTING.md#license--contributor-sign-off)
  10. [![Changelog](https://img.shields.io/badge/changelog-📋-blue.svg)](CHANGELOG.md)
  11. 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. Compression is **reversible** (what a large compression drops is stashed, one `squeez_retrieve` away) and **cheap**: one static binary, a pipeline linear in output size with fixed-size caches (see [Benchmarks](#benchmarks)).
  12. ---
  13. ## 📰 What's new
  14. > Latest first. Full history in [CHANGELOG.md](CHANGELOG.md).
  15. ### v1.48.25 – v1.49.1 — session identity, honest per-session stats, Hermes output hook
  16. - **Each squeez session knows which host session started it.** `squeez init` takes `--session-id` / `--cwd` (or `--stdin` to 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 carry `host_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)
  17. - **Summaries count only their own session.** `finalize` summed every event in the hourly log, which every session of that hour shares — a session that ran one `echo` reported the previous session's savings, and summing summaries overcounted ~8×. Events older than the session's start are now skipped. (#284)
  18. - **Handler stats name the program, not the first word.** `cd pkg && cargo test` is `cargo`, `export CI=1; npm test` is `npm`, `(cd x && make)` is `make`; `VAR=1` prefixes 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 routes `cd pkg && cargo test` to the test-runner handler. (#285)
  19. - **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's `transform_terminal_output` hook: the command runs unchanged, its output goes through `squeez filter`, and the full output is kept on disk, redacted, with its path appended. Contributed by [@fire](https://github.com/fire). (#275)
  20. ### v1.47 – v1.48 — agent metering, `squeez doctor`, Windows and OpenCode 2.x
  21. - **Sub-agent cost is measured, not estimated** — the real token usage of a sub-agent replaces the flat `agent_spawn_cost` guess; a spawn ceiling is enforced at `PreToolUse` and the metering blind spot (spawns counted only on return) is closed.
  22. - **Re-read amplification** — output that the session history says will be re-read many times is compressed harder.
  23. - **`squeez doctor`** — self-health check: hook drift and registration per host, config sanity, tracking freshness; each store judged by the host that owns it.
  24. - **Post-compact state comes back from `SessionStart`**, not `PostCompact` (Claude Code does not deliver PostCompact output to the model).
  25. - **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_tokens` pins it when detection is not possible.
  26. - **Windows** — helper processes spawn without a console window, `bash.exe` from 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.
  27. - **OpenCode 2.x** — the plugin tracks shell completions, runs `init` once 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/opencode` out of the watched config tree.
  28. - **Correctness** — JSON escapes decode on read (backslashes no longer double per save), concurrent `init` cannot corrupt an instruction file, every session starts with its own counters, the persona is taught once per session, and `wrap` fails open when the stash is refused rather than compressing lossily.
  29. ### v1.46.0 — shipped filter pack + native `git status`
  30. 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.
  31. - **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.
  32. - **`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`.
  33. - **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%]`.
  34. - **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.
  35. - **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.
  36. - **Benchmarks grew to 46 scenarios**, six of them covering the new rule pack, so the pack's contribution is measured rather than asserted.
  37. ---
  38. ## Install
  39. Three methods — all produce the same result (binary at `~/.claude/squeez/bin/squeez`, hooks registered).
  40. ### curl (recommended)
  41. ```bash
  42. curl -fsSL https://raw.githubusercontent.com/claudioemmanuel/squeez/main/install.sh | sh
  43. ```
  44. > **Windows:** requires [Git Bash](https://git-scm.com/downloads). Run the command above inside Git Bash — PowerShell/CMD are not supported.
  45. ### npm / npx
  46. ```bash
  47. # Install globally
  48. npm install -g squeez
  49. # Or run once without installing
  50. npx squeez
  51. ```
  52. Downloads the correct pre-built binary for your platform (macOS universal, Linux x86_64/aarch64, Windows x86_64). Requires Node ≥ 16.
  53. ### cargo (build from source)
  54. ```bash
  55. cargo install squeez
  56. ```
  57. Builds from [crates.io](https://crates.io/crates/squeez). Requires Rust stable. On Windows you also need [MSVC C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
  58. ---
  59. ### Supported hosts
  60. `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.
  61. | Host | Memory file | Bash wrap | Session memory | Budget inject (Read/Grep) | Notes |
  62. |---|---|---|---|---|---|
  63. | **Claude Code** | `~/.claude/CLAUDE.md` | ✅ native | ✅ native | ✅ native | Restart Claude Code to pick up hooks |
  64. | **Copilot CLI** | `~/.copilot/copilot-instructions.md` | ✅ native | ✅ native | ✅ native | Restart Copilot CLI after setup |
  65. | **OpenCode** | `~/.config/opencode/AGENTS.md` | ✅ native | ✅ native | ✅ native | Plugin at `~/.config/opencode/plugins/squeez.js`; MCP tool calls skip hooks (upstream sst/opencode#2319) |
  66. | **Gemini CLI** | `~/.gemini/GEMINI.md` | ✅ native | ✅ native | 🟡 soft via `GEMINI.md` | `BeforeTool` rewrite schema pending upstream docs ([google-gemini/gemini-cli#25629](https://github.com/google-gemini/gemini-cli/issues/25629)) |
  67. | **Codex CLI** | `~/.codex/AGENTS.md` | ✅ native | ✅ native | 🟡 soft via `AGENTS.md` | `apply_patch` hooks landed in 0.123.0 ([#18391](https://github.com/openai/codex/pull/18391)); `updatedInput` + `read_file`/`grep` hook surface still pending ([openai/codex#18491](https://github.com/openai/codex/issues/18491)) |
  68. | **Pi** | `~/.pi/agent/skills/squeez/SKILL.md` | ✅ native | ✅ via skill | ✅ native | TypeScript extension at `~/.pi/agent/extensions/squeez/index.ts`; restart Pi after setup |
  69. | **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` |
  70. ### Manage
  71. ```bash
  72. squeez setup # register into every detected host
  73. squeez setup --host=<slug> # register into one host
  74. squeez uninstall # remove squeez entries from every detected host
  75. squeez uninstall --host=<slug>
  76. ```
  77. Slugs: `claude-code` / `copilot` / `opencode` / `gemini` / `codex` / `pi` / `hermes`.
  78. After install, restart the CLI you use to pick up the new hooks.
  79. ### Uninstall
  80. ```bash
  81. squeez uninstall # preserves session data + config.ini
  82. bash ~/.claude/squeez/uninstall.sh # (legacy) full wipe, if the script exists
  83. ```
  84. ### Self-update
  85. ```bash
  86. squeez update # download latest binary + verify SHA256
  87. squeez update --check # check for update without installing
  88. squeez update --insecure # skip checksum (not recommended)
  89. ```
  90. ---
  91. ## What it does
  92. | Feature | Description |
  93. |---------|-------------|
  94. | **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.) |
  95. | **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. |
  96. | **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. |
  97. | **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. Each line is scored once and the top N selected in linear time. |
  98. | **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). The sketch is built in one streamed pass — O(n) time, O(k) memory, no per-trigram allocation. |
  99. | **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. |
  100. | **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. |
  101. | **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. |
  102. | **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. |
  103. | **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. |
  104. | **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. |
  105. | **`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. |
  106. | **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. |
  107. | **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. |
  108. | **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. |
  109. | **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). |
  110. | **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`. |
  111. | **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. |
  112. | **Caveman persona** | Injects an ultra-terse prompt at session start so the model responds with fewer tokens. |
  113. | **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. |
  114. | **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. |
  115. | **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`). |
  116. | **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. |
  117. | **Token economy** | Sub-agent cost measured from the host transcript's real `usage` (the flat `agent_spawn_cost` estimate is only the fallback), spawns counted at dispatch with a ceiling, burn rate prediction (`[budget: ~N calls left]`), session efficiency scoring, tool result size budgets. |
  118. | **Auto-calibration** | `squeez calibrate` runs benchmarks on install and generates an optimized `config.ini` (aggressive / balanced / conservative profiles). |
  119. ---
  120. ## How squeez compares
  121. 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.
  122. | Tool | Approach | Hosts | Deps | Key wins | Trade-off |
  123. |------|----------|-------|------|----------|-----------|
  124. | **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 |
  125. | [chopratejas/headroom](https://github.com/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. |
  126. | [teamchong/pxpipe](https://github.com/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. |
  127. | [rtk-ai/rtk](https://github.com/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. |
  128. | [KRLabsOrg/squeez](https://github.com/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. |
  129. | [ojuschugh1/sqz](https://github.com/ojuschugh1/sqz) | CLI context compressor | Any | Python | Single-command compression | Lower coverage than the others. |
  130. | [LLMLingua-2](https://github.com/microsoft/LLMLingua) (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. |
  131. | [TOON](https://github.com/toon-format/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](https://github.com/jhonatanjunio/squeez/pull/4) for `gh`/`kubectl`/`aws`/`gcloud`/`az` JSON outputs | Only helps on uniform JSON shapes. |
  132. **Why squeez is the safe default for a CLI hook** — it combines properties the other approaches trade away:
  133. - **Nothing to run beside it.** No model, no proxy in front of your API traffic, no daemon. The compressor is one static Rust binary (`libc` only on Unix); every hook script only finds that binary and runs `squeez hook <event>`, so no hook needs Python or any other interpreter (the Hermes plugin is Python because Hermes is).
  134. - **Lossless where it matters, reversible everywhere else.** Exact identifiers survive every summary; what a large compression drops is stashed and one `squeez_retrieve` away.
  135. - **Refuses net-loss compressions.** The net-win gate passes output through verbatim when compressing would cost more than it saves, and the preservation guard keeps the original when navigation anchors don't survive.
  136. - **Fails open.** Risky and bypassed commands run unwrapped under the host's own permission rules; if squeez can't stash or compress safely, you get the raw output.
  137. - **Cheap per call.** Linear-time pipeline, fixed-size caches, command exit detected within ~10 ms — `squeez benchmark` reproduces the [Benchmarks](#benchmarks) on your machine.
  138. - **Seven hosts, one config.** Same pipeline and session memory on Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI, Pi and Hermes.
  139. 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.
  140. ---
  141. ## Scope & Limits
  142. squeez optimizes what it can reach — the surfaces exposed by each host's hook API. It cannot fix token leaks outside those surfaces.
  143. ### Coverage table
  144. | Surface | How | When | Supported hosts |
  145. |---|---|---|---|
  146. | **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 7 (Hermes filters the output after the run instead of wrapping) |
  147. | **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 |
  148. | **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 |
  149. | **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) |
  150. | **Sub-agent output** | `SubagentStop` hook feeds `last_assistant_message` into SessionContext for cross-call dedup | On every sub-agent completion | Claude Code |
  151. | **Compaction lifecycle** | `PreCompact` / `PostCompact` log the event; `SessionStart` (`source: compact`) re-injects tracked session state (files, errors, git refs, retrievable blob ids) so it survives compaction | On context compaction | Claude Code |
  152. | **Session memory** | `SessionStart` injects prior session summary + file-access cache | Once per session start | all 7 |
  153. | **Markdown viewing** | Bash handler routes `.md` reads through `compress-md` when `auto_compress_md=true` | Viewer commands on .md paths | all 7 |
  154. ### What squeez CANNOT compress
  155. **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.
  156. **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.
  157. **User's top-level prompt.** squeez runs per tool call, not on user turns.
  158. **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](https://github.com/openai/codex/issues/18491)) — so Read/Grep caps for Codex are soft hints in AGENTS.md, not hard injections.
  159. ### Secondary wins (not compression, but token-saving)
  160. - **Cross-call redundancy dedup** — exact-hash and fuzzy-trigram collapsing across 16 recent calls (see [Context engine](#what-it-does))
  161. - **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
  162. - **File-access cache** — subsequent Bash commands trimmed when re-reading a file squeez has already fingerprinted
  163. - **Burn-rate warnings** — `[budget: ~N calls left]` nudges so the user changes behavior before context pressure spikes
  164. ### Reducing overall session cost
  165. squeez cannot automate these, but you can:
  166. - Fewer Agent/Task dispatches per session → use `squeez_agent_costs` to track, then refactor tasks to batch work
  167. - Smaller prompts injected into agents → squeez compresses them at dispatch, but smaller is better
  168. - Shorter CLAUDE.md / AGENTS.md files → run `squeez compress-md --ultra` to drop abbreviations and filler
  169. ---
  170. ## Benchmarks
  171. <!-- BENCHMARK:START -->
  172. Measured on macOS (Apple Silicon). Token count = `chars / 4` (matches Claude's ~4 chars/token). Run `squeez benchmark` to reproduce.
  173. ### Per-scenario results — 46 scenarios × 5 iterations
  174. | Scenario | Before | After | Reduction | Latency |
  175. |----------|--------|-------|-----------|---------|
  176. | `curl_json` | 18,904 tk | 36 tk | **-100%** | 658 µs |
  177. | `az_json` | 23,479 tk | 74 tk | **-100%** | 349 µs |
  178. | `summarize_huge` | 82,257 tk | 467 tk | **-99%** | 19.6 ms |
  179. | `xcode_build` | 1,881 tk | 17 tk | **-99%** | 171 µs |
  180. | `go_test_ndjson_failures` | 7,176 tk | 106 tk | **-99%** | 679 µs |
  181. | `read_reread_distant` | 717 tk | 17 tk | **-98%** | 7.7 ms |
  182. | `rsync_transfer` | 912 tk | 26 tk | **-97%** | 120 µs |
  183. | `repetitive_output` | 4,692 tk | 134 tk | **-97%** | 230 µs |
  184. | `pytest_failures` | 3,402 tk | 108 tk | **-97%** | 168 µs |
  185. | `jest_json_failures` | 5,643 tk | 218 tk | **-96%** | 454 µs |
  186. | `systemctl_status` | 732 tk | 41 tk | **-94%** | 118 µs |
  187. | `ps_aux` | 40,373 tk | 2,338 tk | **-94%** | 684 µs |
  188. | `cargo_test_failures` | 1,934 tk | 157 tk | **-92%** | 143 µs |
  189. | `git_log_200` | 2,692 tk | 275 tk | **-90%** | 250 µs |
  190. | `tsc_errors` | 731 tk | 101 tk | **-86%** | 129 µs |
  191. | `eslint_json_failures` | 1,553 tk | 233 tk | **-85%** | 238 µs |
  192. | `pip_install` | 407 tk | 62 tk | **-85%** | 108 µs |
  193. | `high_context_adaptive` | 4,418 tk | 729 tk | **-84%** | 667 µs |
  194. | `cargo_build_noisy` | 2,106 tk | 439 tk | **-79%** | 279 µs |
  195. | `bundle_install` | 121 tk | 28 tk | **-77%** | 95 µs |
  196. | `docker_logs` | 665 tk | 181 tk | **-73%** | 144 µs |
  197. | `curl_html_response` | 2,181 tk | 626 tk | **-71%** | 145 µs |
  198. | `git_status` | 50 tk | 16 tk | **-68%** | 119 µs |
  199. | `ruff_json_failures` | 1,261 tk | 494 tk | **-61%** | 213 µs |
  200. | `verbose_app_log` | 4,957 tk | 1,978 tk | **-60%** | 517 µs |
  201. | `npm_install` | 524 tk | 218 tk | **-58%** | 137 µs |
  202. | `crosscall_redundancy_3x` | 486 tk | 222 tk | **-54%** | 2.5 ms |
  203. | `ls_la` | 1,782 tk | 872 tk | **-51%** | 148 µs |
  204. | `mypy_errors` | 650 tk | 349 tk | **-46%** | 108 µs |
  205. | `shellcheck_run` | 335 tk | 187 tk | **-44%** | 89 µs |
  206. | `agent_directory_output` | 3,348 tk | 1,937 tk | **-42%** | 476 µs |
  207. | `env_dump` | 441 tk | 287 tk | **-35%** | 107 µs |
  208. | `agent_heavy` | 2,306 tk | 1,514 tk | **-34%** | 329 µs |
  209. | `git_copilot` | 640 tk | 421 tk | **-34%** | 165 µs |
  210. | `find_deep` | 424 tk | 279 tk | **-34%** | 112 µs |
  211. | `adversarial_tiny_output` | 4 tk | 3 tk | **-25%** | 85 µs |
  212. | `md_prose` | 187 tk | 142 tk | **-24%** | 73 µs |
  213. | `md_claude_md` | 316 tk | 270 tk | **-15%** | 144 µs |
  214. | `claude_md_overhead` | 717 tk | 635 tk | **-11%** | 97 µs |
  215. | `next_build_output` | 902 tk | 884 tk | **-2%** | 137 µs |
  216. | `git_diff` | 502 tk | 497 tk | **-1%** | 134 µs |
  217. | `jest_failures` | 451 tk | 448 tk | **-1%** | 117 µs |
  218. | `state_first_simulation` | 182 tk | 181 tk | **-1%** | 87 µs |
  219. | `kubectl_pods` | 1,513 tk | 1,513 tk | **-0%** | 114 µs |
  220. | `adversarial_dense_json` | 485 tk | 485 tk | **-0%** | 99 µs |
  221. | `adversarial_reread_tiny` | 4 tk | 4 tk | **-0%** | 6.6 ms |
  222. ### Aggregate
  223. | Metric | Value |
  224. |--------|-------|
  225. | **Total token reduction** | **91.2%** — 229,443 tk → 20,249 tk |
  226. | Bash output | **-88.7%** |
  227. | Markdown / context files | **-18.1%** |
  228. | Wrap / cross-call engine | **-99.2%** |
  229. | Quality (signal terms preserved) | **46 / 46 pass** |
  230. | Latency p50 (filter mode) | **< 0.3 ms** |
  231. | Latency p95 (incl. wrap/summarize) | **7 ms** |
  232. ### Estimated cost savings — Claude Sonnet 4.6 · $3.00 / MTok input
  233. | Usage | Baseline / month | Saved / month |
  234. |-------|-----------------|---------------|
  235. | 100 calls / day | $18.00 | **$16.41 (91%)** |
  236. | 1,000 calls / day | $180.00 | **$164.11 (91%)** |
  237. | 10,000 calls / day | $1800.00 | **$1641.06 (91%)** |
  238. <!-- BENCHMARK:END -->
  239. ### Independently verified with a real tokenizer
  240. The table above uses `chars / 4` for reproducibility (no vocab, no deps). A fair
  241. objection: *"that's a made-up unit — show me the reduction under a real byte-pair
  242. tokenizer."* So `bench/verify_tokens.py` re-tokenizes every fixture — the raw
  243. output **and** the squeez-compressed output — with `cl100k_base` (the real GPT-4
  244. family BPE tokenizer, via `tiktoken`) and compares against `chars/4`:
  245. | Model | Aggregate reduction (22 filter/markdown fixtures) |
  246. |-------|--------------------------------------------------|
  247. | **Real BPE (`cl100k_base`)** | **83.5%** — 112,557 tk → 18,590 tk |
  248. | `chars / 4` (benchmark unit) | 83.0% |
  249. | **Divergence** | **0.5 pts** → the reported reduction is *not* a token-model artifact |
  250. Reduction ratios are near model-invariant, so a real tokenizer confirms the
  251. claim rather than inflating it. Reproduce end-to-end:
  252. ```bash
  253. cargo build --release
  254. pip install tiktoken
  255. python3 bench/verify_tokens.py # human-readable table
  256. python3 bench/verify_tokens.py --json # machine-readable (see bench/verify_tokens.json)
  257. ```
  258. Nothing is cherry-picked: fixtures that squeez can't help (e.g. `kubectl_pods`,
  259. a 61-line output below the truncation threshold) stay in the aggregate at 0%.
  260. ---
  261. ## Commands
  262. ```bash
  263. squeez wrap <cmd> # compress a command's output end-to-end
  264. squeez filter <hint> # compress stdin (piped usage)
  265. squeez config <get|set|list|reset|path> # inspect/change config.ini (also via the /squeez skill)
  266. squeez compress-md [--ultra] [--dry-run] [--all] <file>... # compress markdown files
  267. squeez benchmark [--json] [--output <file>] [--scenario <name>] [--iterations <n>]
  268. squeez mcp # JSON-RPC 2.0 MCP server over stdin/stdout
  269. squeez protocol # print the auto-teach payload (markers + protocol)
  270. squeez update [--check] [--insecure] # self-update
  271. squeez init [--copilot|--host=<name>] # session-start hook (called by hook, not manually)
  272. [--session-id=<id>] [--cwd=<dir>] [--stdin] # record the host session (#286)
  273. squeez calibrate # auto-tune config from benchmarks
  274. squeez doctor # self-health check: hooks, registration, config, tracking freshness
  275. squeez discover # rank commands where a filter-DSL rule would pay off most
  276. squeez filter-test # run the inline self-tests of every filter-DSL rule
  277. squeez prune # on-demand cleanup of the stash blob store + session memory
  278. squeez setup / uninstall [--host=<slug>] # register / remove hooks (see Manage above)
  279. squeez budget-params <tool> # output JSON budget patch for tool
  280. squeez compact-summary [--session-start] # re-inject session state after /compact (called by SessionStart hook)
  281. squeez --version
  282. ```
  283. ### Escape hatch — bypass compression for one command
  284. ```bash
  285. --no-squeez git log --all --graph
  286. ```
  287. Prefix any command with `--no-squeez` to run it raw without squeez touching it.
  288. ### `squeez wrap`
  289. Runs a command, compresses its output, and prints a savings header:
  290. ```
  291. # squeez [git log] 2692→289 tokens (-89%) 0.2ms [adaptive: Ultra]
  292. ```
  293. `wrap` re-executes the command through a shell: `sh -c` on Unix, and on
  294. Windows `bash -c`, then `sh -c`, when one of them resolves on `PATH` — every
  295. agent host writes its terminal commands for bash there, so re-running them
  296. under `cmd.exe` corrupts quoting, `$(…)`, backticks and `;`. `cmd /C` remains
  297. the fallback when no POSIX shell is present, and is also retried automatically
  298. if the preferred shell cannot be spawned. `%SystemRoot%\System32\bash.exe` is
  299. skipped: that is the WSL launcher, which would run the command inside a Linux
  300. distro rather than against the host filesystem. `CLAUDE_CODE_GIT_BASH_PATH` is
  301. honoured when set. Set `SQUEEZ_SHELL` to force a specific shell:
  302. ```bash
  303. SQUEEZ_SHELL="C:/Program Files/Git/bin/bash.exe" squeez wrap 'ls -la'
  304. ```
  305. ### `squeez filter`
  306. Reads from stdin. Use for manual pipelines:
  307. ```bash
  308. git log --oneline | squeez filter git
  309. docker logs mycontainer 2>&1 | squeez filter docker
  310. ```
  311. ### `squeez compress-md`
  312. Pure-Rust, zero-LLM compressor for markdown files. Preserves code blocks, inline code, URLs, headings, file paths, and tables. Compresses prose only. Always writes a backup at `<stem>.original.md`.
  313. ```bash
  314. squeez compress-md CLAUDE.md # Full mode (English default)
  315. squeez compress-md --ultra CLAUDE.md # + abbreviations (with→w/, fn, cfg, etc.)
  316. squeez compress-md --lang pt CLAUDE.md # pt-BR locale (articles, fillers, phrases)
  317. squeez compress-md --dry-run CLAUDE.md # preview, no write
  318. squeez compress-md --all # compress all known locations automatically
  319. ```
  320. When `auto_compress_md = true` (default), `squeez init` runs `--all` silently on every session start.
  321. ### `squeez benchmark`
  322. Reproducible measurement of token reduction, cost, latency, and quality across 46 scenarios (bash output, markdown, wrap / cross-call engine, structured reporters, built-in filter rules, and adversarial cases where squeez should not win):
  323. ```bash
  324. squeez benchmark # human-readable report
  325. squeez benchmark --json # JSON to stdout
  326. squeez benchmark --output report.json # save JSON report
  327. squeez benchmark --scenario git # run only git scenarios
  328. squeez benchmark --iterations 5 # more iterations per scenario
  329. squeez benchmark --list # list all scenarios
  330. ```
  331. Quality is scored by checking that **signal terms** (words from error/warning/failed lines in the baseline) survive compression. 46/46 pass at ≥ 50% threshold.
  332. `squeez benchmark --efficiency-proof` additionally reports **cache-aware effective costs**: list-price ratios (input ×1.0, cache write ×1.25, cache read ×0.1, output ×5) applied identically to both sides of every row under the same cache state — so the provider's caching discount is never miscounted as compression savings. Negative savings are representable, never floored; JSON output is `schema_version: 2`. Savings are reported per compressed slice; end-to-end depends on workload.
  333. ### `squeez mcp`
  334. Runs a Model Context Protocol JSON-RPC 2.0 server over stdin/stdout. Hand-rolled, no `mcp.server` / `fastmcp` dependency — keeps the `libc`-only constraint intact. Wire it into Claude Code:
  335. ```bash
  336. claude mcp add squeez -- /path/to/squeez mcp
  337. ```
  338. Eighteen read-only tools become available to the LLM:
  339. | Tool | Returns |
  340. |------|---------|
  341. | `squeez_recent_calls` | Last N bash invocations with hash + length + cmd snippet — check before re-running |
  342. | `squeez_seen_files` | Files this session has touched, with the call number where each was last seen, sorted by recency |
  343. | `squeez_seen_errors` | Distinct error fingerprints observed this session (FNV-1a hashes of normalized errors) |
  344. | `squeez_seen_error_details` | Error fingerprints with the first 128 chars of message text — find *what* the error was |
  345. | `squeez_session_summary` | Token accounting + call counts (tokens_bash / tokens_read / tokens_other / seen_files / seen_errors / seen_git_refs) |
  346. | `squeez_session_stats` | Dedup hit counts (exact + fuzzy), summarize triggers, Ultra-mode calls, tokens saved per category |
  347. | `squeez_agent_costs` | Sub-agent usage: spawn count, cumulative estimated tokens, per-call breakdown |
  348. | `squeez_session_efficiency` | Session efficiency scores: compression ratio, tool choice, context reuse, budget conservation (basis points) |
  349. | `squeez_prior_summaries` | Last N finalized prior-session summaries with structured fields: investigated / learned / completed / next_steps |
  350. | `squeez_search_history` | Full-text search across all session summaries — find when you last saw an error or touched a file |
  351. | `squeez_file_history` | Sessions where a given file path was touched, with token-savings and commit status |
  352. | `squeez_session_detail` | Full structured view of a past session by date: calls, files, errors, git events, test summary |
  353. | `squeez_protocol` | Auto-teach payload — read once per session to learn squeez's markers + memory protocol |
  354. | `squeez_context_pressure` | Budget used %, calls remaining, tokens saved, and a recommendation (ok / compact_soon / use_state_first) |
  355. | `squeez_handler_stats` | Per-program cumulative compression across sessions (keyed by the program that produced the output, e.g. `cargo` for `cd pkg && cargo test`); flags under- (<10%) and over-performers (≥90%) at ≥5 calls |
  356. | `squeez_enterprise_savings` | Enterprise transport mode (Bedrock/Vertex/OTEL) + USD saved this session at public Sonnet rates |
  357. | `squeez_retrieve` | Expands a stashed output back to its verbatim original by `key`; optional `start_line`/`count` to page a slice |
  358. | `squeez_stash_search` | Finds a stashed output by meaning when the key is lost — term overlap + fuzzy shingle match, returns key + preview |
  359. All read-only. Backed by `SessionContext::load()`, `memory::read_last_n()`, and `memory::search_history()`. No side effects.
  360. ### `squeez protocol`
  361. Prints the auto-teach payload — a 2.4 KB self-describing block covering:
  362. - The 5-rule **memory protocol** (what to do with `[squeez: ...]` markers, when to call the MCP tools)
  363. - The **output marker spec** (`# squeez [...]`, `[squeez: identical to ...]`, `[squeez: ~95% similar to ...]`, `squeez:summary`, `# squeez hint:`)
  364. Same content the MCP `squeez_protocol` tool returns. Pipe it into a `system` prompt or paste it into a one-shot session that doesn't have the MCP server connected.
  365. ---
  366. ## Configuration
  367. Optional config file — all fields have defaults, none are required.
  368. | Platform | Config path |
  369. |----------|------------|
  370. | Claude Code / default | `~/.claude/squeez/config.ini` |
  371. | Copilot CLI | `~/.copilot/squeez/config.ini` |
  372. | OpenCode | `$XDG_STATE_HOME/squeez/opencode/config.ini` (`~/.local/state/squeez/opencode/` by default) |
  373. | Gemini CLI | `~/.gemini/squeez/config.ini` |
  374. | Codex CLI | `~/.codex/squeez/config.ini` |
  375. | Pi | `~/.pi/agent/squeez/config.ini` |
  376. | Hermes | `$HERMES_HOME/squeez/config.ini` (`~/.hermes/squeez/` by default) |
  377. `SQUEEZ_DIR` overrides the data directory (sessions, memory and `config.ini`) for any host. `squeez config path` prints the file in use.
  378. ```ini
  379. # ── Compression ────────────────────────────────────────────────
  380. max_lines = 200 # generic truncation limit
  381. dedup_min = 3 # collapse lines appearing ≥N times
  382. git_log_max_commits = 20
  383. git_diff_max_lines = 150
  384. docker_logs_max_lines = 100
  385. find_max_results = 50
  386. bypass = docker exec, psql, mysql, ssh # never compress these
  387. wrap_bash = true # false = never rewrite Bash calls to `squeez wrap`
  388. bash_risk_patterns = rm -rf, rm -fr, rm -r -f, git push --force, … # run unwrapped under native permission rules
  389. wrap_timeout_secs = 120 # give up on a wrapped command after this long
  390. builtin_filters = true # ship the 41-rule filter pack (project/user rules shadow it)
  391. preservation_floor = 0.70 # on ≥90% reductions, stash the original when fewer anchors than this survive
  392. # ── Context engine ─────────────────────────────────────────────
  393. adaptive_intensity = true # truly adaptive: Full <80% budget, Ultra ≥80%
  394. context_cache_enabled = true # track seen files/errors across calls
  395. redundancy_cache_enabled = true # collapse identical OR fuzzy-similar recent outputs
  396. read_dedup_session_long = true # also collapse a re-read of an unchanged file past the 16-call window
  397. summarize_threshold_lines = 500 # outputs above this trigger summarize fallback (×2 if benign)
  398. compact_threshold_tokens = 120000 # session token budget — drives adaptive intensity
  399. context_window_tokens = 0 # pin the real context window; 0 = detect it from the host transcript (200K / 1M)
  400. # ── Session memory ─────────────────────────────────────────────
  401. memory_retention_days = 30
  402. memory_file_warn_tokens = 1000 # warn when CLAUDE.md / AGENTS.md / SOUL.md grows past this
  403. # ── Output / persona ───────────────────────────────────────────
  404. persona = ultra # off | lite | full | ultra
  405. focus = off # off | adhd — output *structure*, orthogonal to persona
  406. auto_compress_md = true # run compress-md on every session start
  407. lang = en # compress-md locale: en | pt (pt-BR) — more languages extensible
  408. # ── Advanced tuning (rarely needed) ───────────────────────────
  409. max_call_log = 32 # rolling call log depth (also caps redundancy window)
  410. recent_window = 16 # how many recent calls are eligible for redundancy lookup
  411. similarity_threshold = 0.85 # Jaccard threshold for fuzzy dedup (0.0–1.0)
  412. ultra_trigger_pct = 0.80 # fraction of context budget at which Full → Ultra
  413. class_density = true # content-class token estimate: dense chars/2.0, prose chars/3.7 (false = legacy flat path)
  414. net_win_min_tokens = 24 # skip compression + header when it saves less than this (0 = gate off)
  415. mcp_prior_summaries_default = 5 # default n for squeez_prior_summaries
  416. mcp_recent_calls_default = 10 # default n for squeez_recent_calls
  417. # ── Token economy ─────────────────────────────────────────────
  418. agent_warn_threshold_pct = 0.50 # warn when agent cost > 50% of budget
  419. burn_rate_warn_calls = 20 # warn when < 20 calls remaining
  420. agent_spawn_cost = 200000 # fallback estimate per Agent/Task spawn, used until the real usage is measured
  421. agent_prompt_max_tokens = 2000 # compress an Agent/Task prompt above this at dispatch
  422. read_max_lines = 0 # max lines injected into Read tool_input (0 = off)
  423. grep_max_results = 0 # max results injected into Grep tool_input (0 = off)
  424. # ── Auto-curation nudges ──────────────────────────────────────
  425. nudge_enabled = true # emit [squeez: hint ...] markers on recurring patterns
  426. nudge_error_threshold = 3 # fingerprint repeats before a nudge fires
  427. nudge_file_mod_threshold = 5 # writes/creates to same path before nudge fires
  428. nudge_cmd_repeat_threshold = 4 # expensive-command repeats before nudge fires
  429. # ── Continuous handler calibration ────────────────────────────
  430. handler_stats_enabled = true # accumulate per-handler savings across sessions
  431. ```
  432. ### Adaptive intensity — Full / Ultra split
  433. When `adaptive_intensity = true` (default), squeez **actually adapts** to session pressure rather than always running Ultra:
  434. | Used / budget | Tier | Scaling |
  435. |---|---|---|
  436. | `< 80%` | **Full** | ×0.6 limits, dedup_min ×0.66 (floor 2) |
  437. | `≥ 80%` | **Ultra** | ×0.3 limits, dedup_min ×0.5 (floor 2) |
  438. | `adaptive_intensity = false` | **Lite** | passthrough — no scaling |
  439. Floors are enforced so we never reduce to zero: `max_lines ≥ 20`, `git_diff_max_lines ≥ 20`, `dedup_min ≥ 2`, `summarize_threshold_lines ≥ 50`.
  440. The active level is shown in every bash header: `[adaptive: Full]` or `[adaptive: Ultra]`.
  441. Pre-0.3 squeez was effectively always-Ultra. The new behavior preserves more verbatim text in the common case (empty / mid-session) and only graduates to aggressive compression when the context budget is genuinely under pressure.
  442. ### Caveman persona
  443. Three intensity levels (`lite`, `full`, `ultra`) and `off`. Default is `ultra`. The persona prompt is injected into:
  444. - The Claude Code session banner (printed at `SessionStart`)
  445. - The `<!-- squeez:start -->…<!-- squeez:end -->` block in `~/.copilot/copilot-instructions.md` for Copilot CLI
  446. ### ADHD focus mode
  447. `focus = adhd` is a second, independent axis. Persona decides *how terse* the
  448. prose is; focus decides *how it is ordered*. They stack — `persona = ultra` plus
  449. `focus = adhd` keeps maximum compression while forcing action-first structure.
  450. Turning it on changes three surfaces:
  451. 1. **The model's prose** — a 10-rule block (EN or pt-BR, per `lang`) rides
  452. alongside the persona block: lead with the next action, number multi-step
  453. work, restate state in one line, concrete time estimates, cap lists at 5, no
  454. preamble or closing pleasantries.
  455. 2. **The session banner** — the pending next step becomes line 1, remaining
  456. steps are numbered, one prior session is shown instead of three, and the
  457. stats line sinks to the bottom (state, not an action).
  458. 3. **Advisories and doctor** — `[squeez: …]` bursts are capped at 5 per command
  459. with an honest `+N more advisories suppressed` tail, and `squeez doctor`
  460. sorts failures first and ends with one command to run.
  461. ```bash
  462. squeez config set focus adhd # then `squeez init` to rewrite the memory block
  463. squeez config set focus off # back to the default ordering
  464. ```
  465. The ruleset is adapted from the MIT-licensed
  466. [i-have-adhd](https://github.com/ayghri/i-have-adhd) skill by ayghri.
  467. ---
  468. ## How it works
  469. ### Compression pipeline
  470. Output a dedicated handler doesn't claim passes through four strategies in order, each a single linear pass:
  471. 1. **smart_filter** — strips ANSI codes, progress bars, spinner chars, timestamps, and tool-specific noise (npm download lines, stack frame noise, etc.)
  472. 2. **dedup** — lines appearing ≥ `dedup_min` times are collapsed to one entry annotated `[×N]`
  473. 3. **log_template** — near-identical lines that differ only by a timestamp, id or counter collapse to one `[×N] <template>` line
  474. 4. **relevance truncation** — over the line limit, the highest-scoring lines (error/signal words, terms from the command, head/tail bias) are kept in original order; the full original stays retrievable
  475. Per-directory **grouping** (≥5 siblings → `dir/ N modified`) is reserved for `git status`, where the path list is the payload.
  476. ### Supported handlers
  477. | Category | Commands |
  478. |----------|----------|
  479. | Git | `git` |
  480. | Docker / containers | `docker`, `docker-compose`, `podman` |
  481. | Package managers | `npm`, `pnpm`, `bun`, `yarn` |
  482. | Build systems | `make`, `cmake`, `gradle`, `mvn`, `xcodebuild`, `cargo` (build), `next build/dev/start`, `vite build`, `turbo build` |
  483. | Test runners | `cargo test`, `go test`, `jest`, `vitest`, `pytest`, `py.test`, `nextest`, `playwright`, `bun test` |
  484. | TypeScript / linters | `tsc`, `eslint`, `biome`, `ruff`, `next lint` |
  485. | Cloud CLIs | `kubectl`, `gh`, `aws`, `gcloud`, `az`, `wrangler` |
  486. | Databases | `psql`, `prisma`, `mysql`, `drizzle-kit` |
  487. | Filesystem / viewers | `find`, `ls`, `du`, `ps`, `env`, `lsof`, `netstat`, `cat`, `head`, `tail`, `less`, `more`, `bat`, `bfs` |
  488. | JSON / YAML / IaC | `jq`, `yq`, `terraform`, `tofu`, `helm`, `pulumi` |
  489. | Text processing | `grep`, `rg`, `ugrep`, `awk`, `sed` |
  490. | Network | `curl`, `wget`, `http` |
  491. | Runtimes | `node`, `python`, `python3`, `ruby` |
  492. | Generic fallback | everything else — plus the 41 built-in filter-DSL rules and any `filters.ini` rule of your own |
  493. Dispatch looks at the program that produced the output: runner wrappers (`npx`, `bunx`, `pnpm exec`, `sudo`, `time`, `env`), `VAR=value` prefixes, leading `cd … &&` / `export …;` segments and `(` / `{` openers are peeled first, and a pipeline ending in a transforming stage (`cargo build 2>&1 | grep error`) dispatches on that stage.
  494. ### Hooks (Claude Code & Copilot CLI)
  495. Six hooks work together automatically after install on Claude Code (three on Copilot CLI):
  496. - **`PreToolUse`** — rewrites safe Bash calls: `git status` → `squeez wrap git status` (risky/bypassed commands pass through to native permission rules); injects Read/Grep/Glob limits; compresses Agent/Task prompts
  497. - **`SessionStart`** — runs `squeez init`: finalizes previous session into a memory summary, injects the persona prompt
  498. - **`PostToolUse`** — tracks every tool result; rewrites Read/Grep/Glob/Monitor output via `updatedToolOutput` when content is redundant or oversized (Claude Code v2.1.119+)
  499. - **`SubagentStop`** *(Claude Code only)* — feeds `last_assistant_message` into SessionContext so the parent agent can dedup against what the sub-agent saw
  500. - **`PreCompact`** *(Claude Code only)* — logs compaction events for session efficiency metrics; allows compaction to proceed
  501. - **`PostCompact`** *(Claude Code only)* — logs the compaction. Session state (files, errors, git refs, retrievable blob ids) is re-injected by `SessionStart` with `source: compact` (`squeez compact-summary --session-start`), since Claude Code does not deliver PostCompact output to the model
  502. ### Cross-call redundancy
  503. Two-path dedup across the last 16 calls:
  504. **Exact match** — FNV-1a hash of the compressed output. When a subsequent call produces the same bytes, it collapses to:
  505. ```
  506. [squeez: identical to 515ba5b2 at bash#35 — re-run with --no-squeez]
  507. ```
  508. **Fuzzy match** — bottom-k MinHash over whitespace-token trigrams (k=96, Jaccard ≥ 0.85, length-ratio guard ≥ 0.80). Survives timestamp changes, added/removed blank lines, and single-line edits. Collapses to:
  509. ```
  510. [squeez: ~92% similar to 515ba5b2 at bash#35 — re-run with --no-squeez]
  511. ```
  512. Minimum 6 lines to attempt fuzzy match (below that, exact-only).
  513. ### Summarize fallback
  514. When raw output exceeds `summarize_threshold_lines` (default 500), the full pipeline is bypassed and replaced with a ≤40-line dense summary:
  515. ```
  516. squeez:summary cmd=docker logs app
  517. total_lines=5003
  518. top_errors:
  519. - error: connection refused on tcp://10.0.0.1:5432
  520. top_files:
  521. - /var/log/app/error.log
  522. test_summary=FAILED: 3 of 248
  523. ids_preserved:
  524. - 3f2ec81ea3e4ce24
  525. - 550e8400-e29b-41d4-a716-446655440000
  526. - PROJ-1482
  527. tail_preserved=20
  528. [last 20 lines verbatim...]
  529. ```
  530. **Identifier factsheet:** the `ids_preserved:` block carries exact identifiers found in the region the summary drops — git SHAs / hex ids (≥7 chars with a digit), UUIDs, ticket codes, versions, and large integers — so the most dangerous failure mode of lossy summarization (a silently lost hash) can't happen. Extraction is deterministic and budget-capped at 16 facts / 256 chars; bulk generated sequences (hundreds of version strings in a build log) are recognized as noise and dropped wholesale while opaque ids survive. The Structured summary shape carries the same list as `"ids":[...]`.
  531. **Benign-aware threshold:** before summarizing, squeez scans for error markers (`error:`, `panic`, `traceback`, `FAILED`, `EXCEPTION`, `Fatal`). If none are found, the threshold is doubled (1,000 lines default) so successful builds, clean test runs, and uneventful logs stay verbatim unless they are genuinely huge.
  532. ---
  533. ## Platform notes
  534. ### OpenCode
  535. Plugin installed at `~/.config/opencode/plugins/squeez.js`. OpenCode auto-loads plugins on startup. All Bash commands are automatically compressed via `squeez wrap`.
  536. ### Hermes
  537. Directory plugin installed at `$HERMES_HOME/plugins/squeez-fallback/` —
  538. `~/.hermes/plugins/` when `HERMES_HOME` is unset (a leading `~` is expanded).
  539. Set `HERMES_HOME` if Hermes lives elsewhere (e.g. `%LOCALAPPDATA%\hermes` on
  540. Windows), otherwise
  541. `squeez setup --host=hermes` will not detect it. Directory plugins are opt-in;
  542. enable it once with `hermes plugins enable squeez-fallback`.
  543. The plugin uses Hermes's `transform_terminal_output` hook: the command runs
  544. unchanged and its output goes through `squeez filter`, so piped and chained
  545. commands are compressed too. The full output is saved, redacted, and the
  546. compressed text ends with its path (`$HERMES_HOME/cache/squeez-raw/`, mode
  547. 0600, pruned after 24 h). Output under `SQUEEZ_OUTPUT_MIN_CHARS` (default
  548. 4000) is left as is, and `SQUEEZ_OUTPUT_DISABLE=1` turns the hook off. Set
  549. `SQUEEZ_BIN` if squeez is not on `PATH`. To test it through the real Hermes
  550. terminal tool, run `.venv/bin/python <squeez>/plugins/hermes/tests/e2e_hermes.py`
  551. from a hermes-agent checkout.
  552. On `on_session_start` the plugin runs `squeez init --host=hermes`, which opens
  553. a squeez session under `$HERMES_HOME/squeez/` (and writes the persona block
  554. into `SOUL.md` when that file exists). Each output passed through
  555. `squeez filter` is then logged with `squeez track-filter`, so
  556. `squeez_session_summary` reports what Hermes actually saved. Outputs under the
  557. size threshold are never sent to squeez, so they are not counted.
  558. ### GitHub Copilot CLI
  559. Hooks registered in `~/.copilot/settings.json`. Session memory written to `~/.copilot/copilot-instructions.md` (Copilot CLI reads this automatically). State stored separately at `~/.copilot/squeez/`.
  560. Refresh memory manually:
  561. ```bash
  562. SQUEEZ_DIR=~/.copilot/squeez ~/.claude/squeez/bin/squeez init --copilot
  563. ```
  564. ### Pi
  565. TypeScript extension installed at `~/.pi/agent/extensions/squeez/index.ts`. Pi auto-discovers extensions from that directory — no settings patching needed. Session memory is injected via a skill at `~/.pi/agent/skills/squeez/SKILL.md`; Pi includes the skill description in every system prompt and loads full instructions on demand. Unlike other hosts, Pi achieves `BUDGET_HARD` output compression via the `tool_result` event (return-patch API), not just soft hints.
  566. ---
  567. ## Local development
  568. Requires Rust stable. Windows requires Git Bash.
  569. ```bash
  570. git clone https://github.com/claudioemmanuel/squeez.git
  571. cd squeez
  572. cargo test # run all tests (1,300+ tests across 96 integration suites + unit tests)
  573. cargo build --release # build release binary
  574. bash bench/run.sh # filter-mode benchmark (24 fixtures)
  575. bash bench/run_context.sh # context-engine benchmark (wrap scenarios, isolated SQUEEZ_DIR each)
  576. ./target/release/squeez benchmark # full 46-scenario benchmark suite
  577. bash build.sh # build + install to ~/.claude/squeez/bin/
  578. ```
  579. ---
  580. ## Contributing
  581. ```bash
  582. git checkout -b feature/your-change
  583. cargo test
  584. cargo build --release
  585. bash bench/run.sh
  586. git push -u origin feature/your-change
  587. gh pr create --base main --title "Short title" --body "Description"
  588. ```
  589. CI runs `cargo test`, `bench/run.sh`, `bench/run_context.sh`, and `squeez benchmark` on every push and pull request.
  590. See [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards.
  591. ---
  592. ## Similar projects
  593. There is an unrelated project with the same name at [KRLabsOrg/squeez](https://github.com/KRLabsOrg/squeez). This project (claudioemmanuel/squeez) is a hook-based token compressor for AI coding CLIs.
  594. ---
  595. ## License
  596. Licensed under the **Apache License 2.0** — see [LICENSE](LICENSE) + [NOTICE](NOTICE).
  597. Contributions require a DCO sign-off (`git commit -s …`) rather than a CLA. You keep copyright on what you contribute; sign-off is a lightweight affirmation that you have the right to submit it under Apache 2.0. See [CONTRIBUTING.md](CONTRIBUTING.md#license--contributor-sign-off) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.