{"id":48473743,"url":"https://github.com/claudioemmanuel/squeez","last_synced_at":"2026-05-18T02:01:29.997Z","repository":{"id":349574551,"uuid":"1189487703","full_name":"claudioemmanuel/squeez","owner":"claudioemmanuel","description":"Hook-based token compressor for 5 AI CLI hosts (Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI). Up to 95% bash compression, signature-mode for code reads, cross-call dedup, MCP server, self-teaching protocol. Zero runtime deps.","archived":false,"fork":false,"pushed_at":"2026-05-14T23:33:11.000Z","size":2050,"stargazers_count":116,"open_issues_count":1,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T01:32:29.811Z","etag":null,"topics":["ai-cli","bash-hook","claude-code","codex-cli","context-engineering","context-window","copilot-cli","gemini-cli","llm","llm-tools","mcp-server","opencode","rust","session-memory","signature-extraction","token-compression","token-optimizer","zero-dependency"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claudioemmanuel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"claudioemmanuel"}},"created_at":"2026-03-23T11:21:53.000Z","updated_at":"2026-05-14T23:33:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/claudioemmanuel/squeez","commit_stats":null,"previous_names":["claudioemmanuel/squeez"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/claudioemmanuel/squeez","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudioemmanuel%2Fsqueez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudioemmanuel%2Fsqueez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudioemmanuel%2Fsqueez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudioemmanuel%2Fsqueez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claudioemmanuel","download_url":"https://codeload.github.com/claudioemmanuel/squeez/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claudioemmanuel%2Fsqueez/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33162446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-cli","bash-hook","claude-code","codex-cli","context-engineering","context-window","copilot-cli","gemini-cli","llm","llm-tools","mcp-server","opencode","rust","session-memory","signature-extraction","token-compression","token-optimizer","zero-dependency"],"created_at":"2026-04-07T07:48:38.191Z","updated_at":"2026-05-18T02:01:29.988Z","avatar_url":"https://github.com/claudioemmanuel.png","language":"Rust","funding_links":["https://github.com/sponsors/claudioemmanuel"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"squeez — hook-based token compressor for AI CLIs\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# squeez\n\n[![CI](https://github.com/claudioemmanuel/squeez/actions/workflows/ci.yml/badge.svg)](https://github.com/claudioemmanuel/squeez/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/squeez.svg)](https://www.npmjs.com/package/squeez)\n[![Crates.io](https://img.shields.io/crates/v/squeez.svg)](https://crates.io/crates/squeez)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![DCO](https://img.shields.io/badge/contributions-DCO_signed--off-green.svg)](CONTRIBUTING.md#license--contributor-sign-off)\n[![Changelog](https://img.shields.io/badge/changelog-📋-blue.svg)](CHANGELOG.md)\n\nEnd-to-end token optimizer for Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI, and OpenAI Codex CLI. Compresses bash output up to **95%**, collapses redundant calls, and injects a terse prompt persona — automatically, with zero new runtime dependencies.\n\n---\n\n## Install\n\nThree methods — all produce the same result (binary at `~/.claude/squeez/bin/squeez`, hooks registered).\n\n### curl (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/claudioemmanuel/squeez/main/install.sh | sh\n```\n\n\u003e **Windows:** requires [Git Bash](https://git-scm.com/downloads). Run the command above inside Git Bash — PowerShell/CMD are not supported.\n\n### npm / npx\n\n```bash\n# Install globally\nnpm install -g squeez\n\n# Or run once without installing\nnpx squeez\n```\n\nDownloads the correct pre-built binary for your platform (macOS universal, Linux x86_64/aarch64, Windows x86_64). Requires Node ≥ 16.\n\n### cargo (build from source)\n\n```bash\ncargo install squeez\n```\n\nBuilds 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/).\n\n---\n\n### Supported hosts\n\n`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.\n\n| Host | Memory file | Bash wrap | Session memory | Budget inject (Read/Grep) | Notes |\n|---|---|---|---|---|---|\n| **Claude Code** | `~/.claude/CLAUDE.md` | ✅ native | ✅ native | ✅ native | Restart Claude Code to pick up hooks |\n| **Copilot CLI** | `~/.copilot/copilot-instructions.md` | ✅ native | ✅ native | ✅ native | Restart Copilot CLI after setup |\n| **OpenCode** | `~/.config/opencode/AGENTS.md` | ✅ native | ✅ native | ✅ native | Plugin at `~/.config/opencode/plugins/squeez.js`; MCP tool calls skip hooks (upstream sst/opencode#2319) |\n| **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)) |\n| **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)) |\n| **Pi** | `~/.pi/agent/skills/squeez/SKILL.md` | ✅ native | ✅ via skill | ✅ native | TypeScript extension at `~/.pi/agent/extensions/squeez/index.ts`; restart Pi after setup |\n\n### Manage\n\n```bash\nsqueez setup                  # register into every detected host\nsqueez setup --host=\u003cslug\u003e    # register into one host\nsqueez uninstall              # remove squeez entries from every detected host\nsqueez uninstall --host=\u003cslug\u003e\n```\n\nSlugs: `claude-code` / `copilot` / `opencode` / `gemini` / `codex` / `pi`.\n\nAfter install, restart the CLI you use to pick up the new hooks.\n\n### Uninstall\n\n```bash\nsqueez uninstall              # preserves session data + config.ini\nbash ~/.claude/squeez/uninstall.sh   # (legacy) full wipe, if the script exists\n```\n\n### Self-update\n\n```bash\nsqueez update             # download latest binary + verify SHA256\nsqueez update --check     # check for update without installing\nsqueez update --insecure  # skip checksum (not recommended)\n```\n\n---\n\n## What it does\n\n| Feature | Description |\n|---------|-------------|\n| **Bash compression** | Intercepts every command via `PreToolUse` hook, applies smart filter → dedup → grouping → truncation. Up to 95% reduction. |\n| **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). |\n| **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. |\n| **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. |\n| **MCP server** | `squeez mcp` runs a JSON-RPC 2.0 server over stdio exposing 13 read-only tools so any MCP-compatible LLM can query session memory directly. Hand-rolled, no `mcp.server` dependency. |\n| **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. |\n| **Caveman persona** | Injects an ultra-terse prompt at session start so the model responds with fewer tokens. |\n| **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. |\n| **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`). |\n| **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. |\n| **Token economy** | Sub-agent cost tracking (~200K tokens/spawn), burn rate prediction (`[budget: ~N calls left]`), session efficiency scoring, tool result size budgets. |\n| **Auto-calibration** | `squeez calibrate` runs benchmarks on install and generates an optimized `config.ini` (aggressive / balanced / conservative profiles). |\n\n---\n\n## Scope \u0026 Limits\n\nsqueez optimizes what it can reach — the surfaces exposed by each host's hook API. It cannot fix token leaks outside those surfaces.\n\n### Coverage table\n\n| Surface | How | When | Supported hosts |\n|---|---|---|---|\n| **Bash stdout/stderr** | `PreToolUse` wraps command w/ 4-stage pipeline (smart-filter → dedup → grouping → truncation) | Every Bash invocation | all 5 |\n| **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 |\n| **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 |\n| **Agent / Task prompt** | `PreToolUse` compresses `tool_input.prompt` (markdown-aware, via `compress-prompt`) | When prompt \u003e `agent_prompt_max_tokens` | Claude Code (post–v1.8.0) |\n| **Sub-agent output** | `SubagentStop` hook feeds `last_assistant_message` into SessionContext for cross-call dedup | On every sub-agent completion | Claude Code |\n| **Compaction lifecycle** | `PreCompact` logs the event; `PostCompact` emits a re-arm reminder so the model knows compression is still active | On context compaction | Claude Code |\n| **Session memory** | `SessionStart` injects prior session summary + file-access cache | Once per session start | all 5 |\n| **Markdown viewing** | Bash handler routes `.md` reads through `compress-md` when `auto_compress_md=true` | Viewer commands on .md paths | all 5 |\n\n### What squeez CANNOT compress\n\n**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.\n\n**Skills \u0026 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.\n\n**User's top-level prompt.** squeez runs per tool call, not on user turns.\n\n**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.\n\n### Secondary wins (not compression, but token-saving)\n\n- **Cross-call redundancy dedup** — exact-hash and fuzzy-trigram collapsing across 16 recent calls (see [Context engine](#what-it-does))\n- **File-access cache** — subsequent Bash commands trimmed when re-reading a file squeez has already fingerprinted\n- **Burn-rate warnings** — `[budget: ~N calls left]` nudges so the user changes behavior before context pressure spikes\n\n### Reducing overall session cost\n\nsqueez cannot automate these, but you can:\n- Fewer Agent/Task dispatches per session → use `squeez_agent_costs` to track, then refactor tasks to batch work\n- Smaller prompts injected into agents → squeez compresses them at dispatch, but smaller is better\n- Shorter CLAUDE.md / AGENTS.md files → run `squeez compress-md --ultra` to drop abbreviations and filler\n\n---\n\n## Benchmarks\n\n\u003c!-- BENCHMARK:START --\u003e\nMeasured on macOS (Apple Silicon). Token count = `chars / 4` (matches Claude's ~4 chars/token). Run `squeez benchmark` to reproduce.\n\n### Per-scenario results — 28 scenarios × 5 iterations\n\n| Scenario | Before | After | Reduction | Latency |\n|----------|--------|-------|-----------|---------|\n| `summarize_huge` | 82,257 tk | 420 tk | **-99%** | 55.9 ms |\n| `repetitive_output` | 4,692 tk | 37 tk | **-99%** | 221 µs |\n| `xcode_build` | 1,881 tk | 17 tk | **-99%** | 83 µs |\n| `high_context_adaptive` | 4,418 tk | 52 tk | **-99%** | 866 µs |\n| `agent_directory_output` | 3,348 tk | 167 tk | **-95%** | 371 µs |\n| `ps_aux` | 40,373 tk | 2,352 tk | **-94%** | 4.6 ms |\n| `git_log_200` | 2,692 tk | 289 tk | **-89%** | 229 µs |\n| `tsc_errors` | 731 tk | 101 tk | **-86%** | 22 µs |\n| `cargo_build_noisy` | 2,106 tk | 452 tk | **-79%** | 289 µs |\n| `docker_logs` | 665 tk | 186 tk | **-72%** | 50 µs |\n| `curl_html_response` | 2,181 tk | 626 tk | **-71%** | 50 µs |\n| `find_deep` | 424 tk | 134 tk | **-68%** | 132 µs |\n| `git_status` | 50 tk | 16 tk | **-68%** | 15 µs |\n| `pytest_failures` | 3,402 tk | 1,189 tk | **-65%** | 358 µs |\n| `verbose_app_log` | 4,957 tk | 1,991 tk | **-60%** | 330 µs |\n| `npm_install` | 524 tk | 232 tk | **-56%** | 49 µs |\n| `crosscall_redundancy_3x` | 486 tk | 241 tk | **-50%** | 51.7 ms |\n| `ls_la` | 1,782 tk | 886 tk | **-50%** | 237 µs |\n| `env_dump` | 441 tk | 287 tk | **-35%** | 28 µs |\n| `git_copilot` | 640 tk | 421 tk | **-34%** | 131 µs |\n| `agent_heavy` | 2,306 tk | 1,564 tk | **-32%** | 368 µs |\n| `md_prose` | 187 tk | 138 tk | **-26%** | 880 µs |\n| `md_claude_md` | 316 tk | 247 tk | **-22%** | 1.4 ms |\n| `claude_md_overhead` | 717 tk | 649 tk | **-9%** | 22 µs |\n| `git_diff` | 502 tk | 497 tk | **-1%** | 44 µs |\n| `jest_failures` | 451 tk | 448 tk | **-1%** | 54 µs |\n| `state_first_simulation` | 182 tk | 181 tk | **-1%** | 5 µs |\n| `kubectl_pods` | 1,513 tk | 1,513 tk | **-0%** | 36 µs |\n\n### Aggregate\n\n| Metric | Value |\n|--------|-------|\n| **Total token reduction** | **90.7%** — 164,224 tk → 15,333 tk |\n| Bash output | **-83.9%** |\n| Markdown / context files | **-23.5%** |\n| Wrap / cross-call engine | **-99.2%** |\n| Quality (signal terms preserved) | **28 / 28 pass** |\n| Latency p50 (filter mode) | **4.2 ms** |\n| Latency p95 (incl. wrap/summarize) | **52 ms** |\n\n### Estimated cost savings — Claude Sonnet 4.6 · $3.00 / MTok input\n\n| Usage | Baseline / month | Saved / month |\n|-------|-----------------|---------------|\n| 100 calls / day | $18.00 | **$16.32 (91%)** |\n| 1,000 calls / day | $180.00 | **$163.19 (91%)** |\n| 10,000 calls / day | $1800.00 | **$1631.88 (91%)** |\n\u003c!-- BENCHMARK:END --\u003e\n\n---\n\n## Commands\n\n```bash\nsqueez wrap \u003ccmd\u003e                        # compress a command's output end-to-end\nsqueez filter \u003chint\u003e                     # compress stdin (piped usage)\nsqueez compress-md [--ultra] [--dry-run] [--all] \u003cfile\u003e...   # compress markdown files\nsqueez benchmark [--json] [--output \u003cfile\u003e] [--scenario \u003cname\u003e] [--iterations \u003cn\u003e]\nsqueez mcp                               # JSON-RPC 2.0 MCP server over stdin/stdout\nsqueez protocol                          # print the auto-teach payload (markers + protocol)\nsqueez update [--check] [--insecure]     # self-update\nsqueez init [--copilot]                  # session-start hook (called by hook, not manually)\nsqueez calibrate                         # auto-tune config from benchmarks\nsqueez budget-params \u003ctool\u003e              # output JSON budget patch for tool\nsqueez --version\n```\n\n### Escape hatch — bypass compression for one command\n\n```bash\n--no-squeez git log --all --graph\n```\n\nPrefix any command with `--no-squeez` to run it raw without squeez touching it.\n\n### `squeez wrap`\n\nRuns a command, compresses its output, and prints a savings header:\n\n```\n# squeez [git log] 2692→289 tokens (-89%) 0.2ms [adaptive: Ultra]\n```\n\n### `squeez filter`\n\nReads from stdin. Use for manual pipelines:\n\n```bash\ngit log --oneline | squeez filter git\ndocker logs mycontainer 2\u003e\u00261 | squeez filter docker\n```\n\n### `squeez compress-md`\n\nPure-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 `\u003cstem\u003e.original.md`.\n\n```bash\nsqueez compress-md CLAUDE.md             # Full mode (English default)\nsqueez compress-md --ultra CLAUDE.md    # + abbreviations (with→w/, fn, cfg, etc.)\nsqueez compress-md --lang pt CLAUDE.md  # pt-BR locale (articles, fillers, phrases)\nsqueez compress-md --dry-run CLAUDE.md  # preview, no write\nsqueez compress-md --all                # compress all known locations automatically\n```\n\nWhen `auto_compress_md = true` (default), `squeez init` runs `--all` silently on every session start.\n\n### `squeez benchmark`\n\nReproducible measurement of token reduction, cost, latency, and quality across 19 scenarios:\n\n```bash\nsqueez benchmark                          # human-readable report\nsqueez benchmark --json                   # JSON to stdout\nsqueez benchmark --output report.json     # save JSON report\nsqueez benchmark --scenario git           # run only git scenarios\nsqueez benchmark --iterations 5           # more iterations per scenario\nsqueez benchmark --list                   # list all scenarios\n```\n\nQuality is scored by checking that **signal terms** (words from error/warning/failed lines in the baseline) survive compression. 19/19 pass at ≥ 50% threshold.\n\n### `squeez mcp`\n\nRuns 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:\n\n```bash\nclaude mcp add squeez -- /path/to/squeez mcp\n```\n\nThirteen read-only tools become available to the LLM:\n\n| Tool | Returns |\n|------|---------|\n| `squeez_recent_calls` | Last N bash invocations with hash + length + cmd snippet — check before re-running |\n| `squeez_seen_files` | Files this session has touched, with access type (Read/Write/Created/Deleted), sorted by recency |\n| `squeez_seen_errors` | Distinct error fingerprints observed this session (FNV-1a hashes of normalized errors) |\n| `squeez_seen_error_details` | Error fingerprints with the first 128 chars of message text — find *what* the error was |\n| `squeez_session_summary` | Token accounting + call counts (tokens_bash / tokens_read / tokens_other / seen_files / seen_errors / seen_git_refs) |\n| `squeez_session_stats` | Dedup hit counts (exact + fuzzy), summarize triggers, Ultra-mode calls, tokens saved per category |\n| `squeez_agent_costs` | Sub-agent usage: spawn count, cumulative estimated tokens, per-call breakdown |\n| `squeez_session_efficiency` | Session efficiency scores: compression ratio, tool choice, context reuse, budget conservation (basis points) |\n| `squeez_prior_summaries` | Last N finalized prior-session summaries with structured fields: investigated / learned / completed / next_steps |\n| `squeez_search_history` | Full-text search across all session summaries — find when you last saw an error or touched a file |\n| `squeez_file_history` | Sessions where a given file path was touched, with token-savings and commit status |\n| `squeez_session_detail` | Full structured view of a past session by date: calls, files, errors, git events, test summary |\n| `squeez_protocol` | Auto-teach payload — read once per session to learn squeez's markers + memory protocol |\n\nAll read-only. Backed by `SessionContext::load()`, `memory::read_last_n()`, and `memory::search_history()`. No side effects.\n\n### `squeez protocol`\n\nPrints the auto-teach payload — a 2.4 KB self-describing block covering:\n\n- The 5-rule **memory protocol** (what to do with `[squeez: ...]` markers, when to call the MCP tools)\n- The **output marker spec** (`# squeez [...]`, `[squeez: identical to ...]`, `[squeez: ~95% similar to ...]`, `squeez:summary`, `# squeez hint:`)\n\nSame 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.\n\n---\n\n## Configuration\n\nOptional config file — all fields have defaults, none are required.\n\n| Platform | Config path |\n|----------|------------|\n| Claude Code / default | `~/.claude/squeez/config.ini` |\n| Copilot CLI | `~/.copilot/squeez/config.ini` |\n\n```ini\n# ── Compression ────────────────────────────────────────────────\nmax_lines              = 200     # generic truncation limit\ndedup_min              = 3       # collapse lines appearing ≥N times\ngit_log_max_commits    = 20\ngit_diff_max_lines     = 150\ndocker_logs_max_lines  = 100\nfind_max_results       = 50\nbypass                 = docker exec, psql, mysql, ssh   # never compress these\n\n# ── Context engine ─────────────────────────────────────────────\nadaptive_intensity         = true    # truly adaptive: Full \u003c80% budget, Ultra ≥80%\ncontext_cache_enabled      = true    # track seen files/errors across calls\nredundancy_cache_enabled   = true    # collapse identical OR fuzzy-similar recent outputs\nsummarize_threshold_lines  = 500     # outputs above this trigger summarize fallback (×2 if benign)\ncompact_threshold_tokens   = 120000  # session token budget — drives adaptive intensity\n\n# ── Session memory ─────────────────────────────────────────────\nmemory_retention_days = 30\n\n# ── Output / persona ───────────────────────────────────────────\npersona          = ultra    # off | lite | full | ultra\nauto_compress_md = true     # run compress-md on every session start\nlang             = en       # compress-md locale: en | pt (pt-BR) — more languages extensible\n\n# ── Advanced tuning (rarely needed) ───────────────────────────\nmax_call_log              = 32    # rolling call log depth (also caps redundancy window)\nrecent_window             = 16    # how many recent calls are eligible for redundancy lookup\nsimilarity_threshold      = 0.85  # Jaccard threshold for fuzzy dedup (0.0–1.0)\nultra_trigger_pct         = 0.80  # fraction of context budget at which Full → Ultra\nmcp_prior_summaries_default = 5   # default n for squeez_prior_summaries\nmcp_recent_calls_default    = 10  # default n for squeez_recent_calls\n\n# ── Token economy ─────────────────────────────────────────────\nagent_warn_threshold_pct  = 0.50  # warn when agent cost \u003e 50% of budget\nburn_rate_warn_calls      = 20    # warn when \u003c 20 calls remaining\nagent_spawn_cost          = 200000 # estimated tokens per Agent/Task spawn\nread_max_lines            = 0     # max lines injected into Read tool_input (0 = off)\ngrep_max_results          = 0     # max results injected into Grep tool_input (0 = off)\n\n# ── Auto-curation nudges ──────────────────────────────────────\nnudge_enabled              = true   # emit [squeez: hint ...] markers on recurring patterns\nnudge_error_threshold      = 3      # fingerprint repeats before a nudge fires\nnudge_file_mod_threshold   = 5      # writes/creates to same path before nudge fires\nnudge_cmd_repeat_threshold = 4      # expensive-command repeats before nudge fires\n\n# ── Continuous handler calibration ────────────────────────────\nhandler_stats_enabled      = true   # accumulate per-handler savings across sessions\n```\n\n### Adaptive intensity — Full / Ultra split\n\nWhen `adaptive_intensity = true` (default), squeez **actually adapts** to session pressure rather than always running Ultra:\n\n| Used / budget | Tier | Scaling |\n|---|---|---|\n| `\u003c 80%` | **Full** | ×0.6 limits, dedup_min ×0.66 (floor 2) |\n| `≥ 80%` | **Ultra** | ×0.3 limits, dedup_min ×0.5 (floor 2) |\n| `adaptive_intensity = false` | **Lite** | passthrough — no scaling |\n\nFloors are enforced so we never reduce to zero: `max_lines ≥ 20`, `git_diff_max_lines ≥ 20`, `dedup_min ≥ 2`, `summarize_threshold_lines ≥ 50`.\n\nThe active level is shown in every bash header: `[adaptive: Full]` or `[adaptive: Ultra]`.\n\nPre-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.\n\n### Caveman persona\n\nThree intensity levels (`lite`, `full`, `ultra`) and `off`. Default is `ultra`. The persona prompt is injected into:\n- The Claude Code session banner (printed at `SessionStart`)\n- The `\u003c!-- squeez:start --\u003e…\u003c!-- squeez:end --\u003e` block in `~/.copilot/copilot-instructions.md` for Copilot CLI\n\n---\n\n## How it works\n\n### Compression pipeline\n\nEach bash command passes through four strategies in order:\n\n1. **smart_filter** — strips ANSI codes, progress bars, spinner chars, timestamps, and tool-specific noise (npm download lines, stack frame noise, etc.)\n2. **dedup** — lines appearing ≥ `dedup_min` times are collapsed to one entry annotated `[×N]`\n3. **grouping** — files in the same directory (≥5 siblings) are collapsed to `dir/  N modified  [squeez grouped]`\n4. **truncation** — `Head` (keep first N) or `Tail` (keep last N) depending on handler; truncated portion noted\n\n### Supported handlers\n\n| Category | Commands |\n|----------|----------|\n| Git | `git` |\n| Docker / containers | `docker`, `docker-compose`, `podman` |\n| Package managers | `npm`, `pnpm`, `bun`, `yarn` |\n| Build systems | `make`, `cmake`, `gradle`, `mvn`, `xcodebuild`, `cargo` (build), `next build/dev/start` |\n| Test runners | `cargo test`, `jest`, `vitest`, `pytest`, `nextest`, `playwright`, `bun test` |\n| TypeScript / linters | `tsc`, `eslint`, `biome` |\n| Cloud CLIs | `kubectl`, `gh`, `aws`, `gcloud`, `az`, `wrangler` |\n| Databases | `psql`, `prisma`, `mysql`, `drizzle-kit` |\n| Filesystem | `find`, `ls`, `du`, `ps`, `env`, `lsof`, `netstat` |\n| JSON / YAML / IaC | `jq`, `yq`, `terraform`, `tofu`, `helm`, `pulumi` |\n| Text processing | `grep`, `rg`, `awk`, `sed` |\n| Network | `curl`, `wget` |\n| Runtimes | `node`, `python`, `ruby` |\n| Generic fallback | everything else |\n\n### Hooks (Claude Code \u0026 Copilot CLI)\n\nSix hooks work together automatically after install on Claude Code (three on Copilot CLI):\n\n- **`PreToolUse`** — rewrites every Bash call: `git status` → `squeez wrap git status`; injects Read/Grep/Glob limits; compresses Agent/Task prompts\n- **`SessionStart`** — runs `squeez init`: finalizes previous session into a memory summary, injects the persona prompt\n- **`PostToolUse`** — tracks every tool result; rewrites Read/Grep/Glob/Monitor output via `updatedToolOutput` when content is redundant or oversized (Claude Code v2.1.119+)\n- **`SubagentStop`** *(Claude Code only)* — feeds `last_assistant_message` into SessionContext so the parent agent can dedup against what the sub-agent saw\n- **`PreCompact`** *(Claude Code only)* — logs compaction events for session efficiency metrics; allows compaction to proceed\n- **`PostCompact`** *(Claude Code only)* — emits a re-arm reminder after compaction so the model knows compression is still active\n\n### Cross-call redundancy\n\nTwo-path dedup across the last 16 calls:\n\n**Exact match** — FNV-1a hash of the compressed output. When a subsequent call produces the same bytes, it collapses to:\n\n```\n[squeez: identical to 515ba5b2 at bash#35 — re-run with --no-squeez]\n```\n\n**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:\n\n```\n[squeez: ~92% similar to 515ba5b2 at bash#35 — re-run with --no-squeez]\n```\n\nMinimum 6 lines to attempt fuzzy match (below that, exact-only).\n\n### Summarize fallback\n\nWhen raw output exceeds `summarize_threshold_lines` (default 500), the full pipeline is bypassed and replaced with a ≤40-line dense summary:\n\n```\nsqueez:summary cmd=docker logs app\ntotal_lines=5003\ntop_errors:\n  - error: connection refused on tcp://10.0.0.1:5432\ntop_files:\n  - /var/log/app/error.log\ntest_summary=FAILED: 3 of 248\ntail_preserved=20\n[last 20 lines verbatim...]\n```\n\n**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.\n\n---\n\n## Platform notes\n\n### OpenCode\n\nPlugin installed at `~/.config/opencode/plugins/squeez.js`. OpenCode auto-loads plugins on startup. All Bash commands are automatically compressed via `squeez wrap`.\n\n### GitHub Copilot CLI\n\nHooks registered in `~/.copilot/settings.json`. Session memory written to `~/.copilot/copilot-instructions.md` (Copilot CLI reads this automatically). State stored separately at `~/.copilot/squeez/`.\n\nRefresh memory manually:\n\n```bash\nSQUEEZ_DIR=~/.copilot/squeez ~/.claude/squeez/bin/squeez init --copilot\n```\n\n### Pi\n\nTypeScript 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.\n\n---\n\n## Local development\n\nRequires Rust stable. Windows requires Git Bash.\n\n```bash\ngit clone https://github.com/claudioemmanuel/squeez.git\ncd squeez\n\ncargo test                  # run all tests (356 tests, 37 suites)\ncargo build --release       # build release binary\n\nbash bench/run.sh           # filter-mode benchmark (14 fixtures)\nbash bench/run_context.sh   # context-engine benchmark (3 wrap scenarios)\n./target/release/squeez benchmark   # full 19-scenario benchmark suite\n\nbash build.sh               # build + install to ~/.claude/squeez/bin/\n```\n\n---\n\n## Contributing\n\n```bash\ngit checkout -b feature/your-change\ncargo test\ncargo build --release\nbash bench/run.sh\ngit push -u origin feature/your-change\ngh pr create --base main --title \"Short title\" --body \"Description\"\n```\n\nCI runs `cargo test`, `bench/run.sh`, `bench/run_context.sh`, and `squeez benchmark` on every push and pull request.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards.\n\n---\n\n## Similar projects\n\nThere 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.\n\n---\n\n## License\n\nLicensed under the **Apache License 2.0** — see [LICENSE](LICENSE) + [NOTICE](NOTICE).\n\nContributions 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaudioemmanuel%2Fsqueez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaudioemmanuel%2Fsqueez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaudioemmanuel%2Fsqueez/lists"}