{"id":48868456,"url":"https://github.com/ojuschugh1/sqz","last_synced_at":"2026-04-23T08:01:24.928Z","repository":{"id":351000252,"uuid":"1208373001","full_name":"ojuschugh1/sqz","owner":"ojuschugh1","description":"Compress LLM context to save tokens and reduce costs","archived":false,"fork":false,"pushed_at":"2026-04-18T17:56:47.000Z","size":3742,"stargazers_count":76,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-18T23:02:51.991Z","etag":null,"topics":["agentic-ai","ai","api","cli","context","cost-optimization","extensions","javascript","llms","python","rust","token","tokens"],"latest_commit_sha":null,"homepage":"https://ojuschugh1.github.io/sqz/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ojuschugh1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"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":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-04-12T07:23:52.000Z","updated_at":"2026-04-18T21:50:12.000Z","dependencies_parsed_at":"2026-04-18T23:01:35.279Z","dependency_job_id":null,"html_url":"https://github.com/ojuschugh1/sqz","commit_stats":null,"previous_names":["ojuschugh1/sqz"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ojuschugh1/sqz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojuschugh1%2Fsqz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojuschugh1%2Fsqz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojuschugh1%2Fsqz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojuschugh1%2Fsqz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ojuschugh1","download_url":"https://codeload.github.com/ojuschugh1/sqz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojuschugh1%2Fsqz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32171223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agentic-ai","ai","api","cli","context","cost-optimization","extensions","javascript","llms","python","rust","token","tokens"],"created_at":"2026-04-15T20:01:02.776Z","updated_at":"2026-04-23T08:01:24.811Z","avatar_url":"https://github.com/ojuschugh1.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cpre\u003e\n  ███████╗ ██████╗ ███████╗\n  ██╔════╝██╔═══██╗╚══███╔╝\n  ███████╗██║   ██║  ███╔╝\n  ╚════██║██║▄▄ ██║ ███╔╝\n  ███████║╚██████╔╝███████╗\n  ╚══════╝ ╚══▀▀═╝ ╚══════╝\n  The Context Intelligence Layer\n  \u003c/pre\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eCompress LLM context to save tokens and reduce costs\u003c/strong\u003e — Shell Hook + MCP Server + Browser Extension + IDE Extensions\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003esqz: Compress what is safe, preserve what is critical.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Single Rust binary · Zero telemetry · 805 tests · 83 property-based correctness proofs\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/sqz-cli\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/sqz-cli?logo=rust\u0026logoColor=white\u0026label=crates.io\u0026color=e6522c\" alt=\"Crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/sqz-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/sqz-cli?logo=npm\u0026logoColor=white\u0026label=npm\u0026color=cb3837\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/sqz/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/sqz?logo=python\u0026logoColor=white\u0026label=PyPI\u0026color=3775a9\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://marketplace.visualstudio.com/items?itemName=ojuschugh1.sqz\"\u003e\u003cimg src=\"https://img.shields.io/badge/VS%20Code-Marketplace-007acc?logo=visual-studio-code\u0026logoColor=white\" alt=\"VS Code\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://addons.mozilla.org/en-US/firefox/addon/sqz-context-compression/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Firefox-Add--on-ff7139?logo=firefox-browser\u0026logoColor=white\" alt=\"Firefox\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://plugins.jetbrains.com/plugin/31240-sqz--context-intelligence/\"\u003e\u003cimg src=\"https://img.shields.io/badge/JetBrains-Plugin-000000?logo=jetbrains\u0026logoColor=white\" alt=\"JetBrains\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/j8EEyH5dSB\"\u003e\u003cimg src=\"https://img.shields.io/discord/1493251029075235076?logo=discord\u0026logoColor=white\u0026label=Discord\u0026color=5865F2\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e ·\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e ·\n  \u003ca href=\"#platforms\"\u003ePlatforms\u003c/a\u003e ·\n  \u003ca href=\"CHANGELOG.md\"\u003eChangelog\u003c/a\u003e ·\n  \u003ca href=\"https://discord.gg/j8EEyH5dSB\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nAI coding tools waste tokens. Every file read sends the full content — even if the LLM saw it 30 seconds ago. Every `git status` sends raw output. Every API response dumps uncompressed JSON. You're paying for tokens that carry zero signal.\n\n## The Solution\n\nsqz sits between your AI tool and the LLM, compressing everything before it reaches the model. Two layers work together:\n\n**Noise reduction** — a multi-stage compression pipeline strips nulls from JSON, collapses repeated log lines, folds unchanged diff context, encodes JSON arrays as tables, abbreviates common words, and applies run-length encoding to repetitive output. This is the core — it cleans up noisy tool output before it hits the context window.\n\n**Deduplication** — a compaction-aware SHA-256 cache returns a 13-token reference for repeated content. When a file changes by a few lines, delta encoding sends only the diff. A turn-counter heuristic detects when refs may have gone stale (the original content was compacted out of the LLM's context) and automatically re-sends the full compressed content instead of a dangling reference.\n\n```\nWithout sqz:                              With sqz:\n\nFile read #1:  2,000 tokens               File read #1:  ~800 tokens (compressed)\nFile read #2:  2,000 tokens               File read #2:  ~13 tokens  (dedup ref)\nFile read #3:  2,000 tokens               File read #3:  ~13 tokens  (dedup ref)\n─────────────────────────                  ─────────────────────────\nTotal:         6,000 tokens               Total:         ~826 tokens (86% saved)\n```\n\nNo workflow changes. Install once, save on every API call.\n\n## Token Savings\n\nsqz saves tokens in two ways: compression (removing noise from content) and deduplication (replacing repeated reads with 13-token references). The dedup cache is where the biggest savings happen in real sessions.\n\n### Where sqz shines\n\n| Scenario | Savings | Why |\n|---|---:|---|\n| Repeated file reads (5x) | **86%** | Dedup cache: 13-token ref after first read |\n| JSON API responses with nulls | **7–56%** | Strip nulls + TOON encoding (varies by null density) |\n| Repeated log lines | **58%** | Condense + RLE collapses duplicates |\n| Large JSON arrays | **45%** | Tabular encoding for uniform arrays, collapse for mixed |\n| Git diffs | **11%** | Fold unchanged context lines |\n| Prose / documentation | **2–20%** | Token pruning + word abbreviation + entropy truncation |\n\n### Where sqz intentionally preserves content\n\n| Scenario | Savings | Why |\n|---|---:|---|\n| Stack traces | **0%** | Error content is critical — safe mode preserves it |\n| Test output | **0%** | Pass/fail signals must not be altered |\n| Short git output | **0%** | Already compact, nothing to strip |\n\nThis is by design. sqz's confidence router detects high-risk content (errors, test results, diffs) and routes it through safe mode to avoid dropping signal. A tool that claims 89% compression on `cargo test` output is either lying or deleting your error messages.\n\n### Benchmark suite\n\nCommand: `cargo test -p sqz-engine benchmarks -- --nocapture`\n\nFor a full session-level comparison with rtk, see [docs/benchmark-vs-rtk.md](docs/benchmark-vs-rtk.md).\n\n| Case | Before | After | Saved |\n|---|---:|---:|---:|\n| repeated_logs | 148 | 62 | **58.1%** |\n| json_api | 64 | 59 | **7.8%** |\n| git_diff | 61 | 54 | **11.5%** |\n| large_json_array | 259 | 142 | **45.2%** |\n| stack_trace (safe mode) | 82 | 82 | **0.0%** |\n| prose_docs | 124 | 121 | **2.4%** |\n\n### Track your savings\n\n```sh\nsqz gain          # ASCII chart of daily token savings\nsqz stats         # Cumulative compression report\n```\n\n## Install\n\n```sh\n# Confirmed working:\ncargo install sqz-cli\n\n# Coming soon (scaffolded, not yet live):\n# curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh\n# brew install sqz\n# npm install -g sqz-cli\n```\n\n\u003e All install channels point to [github.com/ojuschugh1/sqz](https://github.com/ojuschugh1/sqz).\n\nThen:\n\n```sh\nsqz init\n```\n\nThat's it. Shell hooks installed, AI tool hooks configured, default presets created, ready to go.\n\n`sqz init` automatically installs:\n- **Shell hooks** (Bash/Zsh/Fish/Nushell/PowerShell) — `sqz_run` and `sqz_sudo` wrappers\n- **PreToolUse hooks** for Claude Code, Cursor, Windsurf, and Cline — transparent command interception that pipes all bash output through sqz without any manual prefixing\n\nAfter init, every terminal command your AI tool runs is automatically compressed. No workflow changes needed.\n\n## How It Works\n\nsqz operates at four integration levels simultaneously:\n\n### 1. Transparent Interception (PreToolUse Hooks)\n\nThe most effective integration. sqz installs a PreToolUse hook that intercepts bash commands before execution and rewrites them to pipe output through `sqz compress`. The AI tool never knows it happened — it just gets compressed output.\n\n```\nWithout sqz:  Claude → git status → raw output (300 tokens)\nWith sqz:     Claude → git status → [hook rewrites] → compressed output (45 tokens)\n```\n\nSupported tools: Claude Code, Cursor, Windsurf, Cline. The hook skips interactive commands (vim, ssh, python REPL) and commands already piped through sqz.\n\nYou can also manually invoke the hook: `sqz hook claude`, `sqz hook cursor`.\n\n### 2. Shell Hook (CLI Proxy)\n\nIntercepts command output from 100+ CLI tools (git, cargo, npm, docker, kubectl, aws, etc.) and compresses it before the LLM sees it. Includes session-level n-gram abbreviation for recurring phrases and word abbreviation for common long words.\n\n```sh\n# Before: git log sends ~800 tokens of raw output\n# After: sqz compresses to ~150 tokens, same information\n```\n\n### 2. MCP Server\n\nA compiled Rust binary (not Node.js) that serves as an MCP server with intelligent tool selection (TF-IDF + cosine similarity), preset hot-reload, and the full compression pipeline.\n\n```json\n{\n  \"mcpServers\": {\n    \"sqz\": {\n      \"command\": \"sqz-mcp\",\n      \"args\": [\"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n### 3. Browser Extension\n\nChrome and Firefox extensions for ChatGPT, Claude.ai, Gemini, Grok, and Perplexity. Compresses pasted content client-side via a lightweight WASM engine (TOON encoding + whitespace normalization + phrase substitution). The full pipeline runs in the CLI/MCP — the browser uses a fast subset optimized for paste-time latency. Zero network requests.\n\n### 4. IDE Extensions\n\nNative [VS Code](https://marketplace.visualstudio.com/items?itemName=ojuschugh1.sqz) and JetBrains extensions that intercept file reads at the editor level, with AST-aware compression for 18 languages and a status bar showing token budget.\n\n## Features\n\n### Compression Pipeline\n- **10 registered stages** — ansi_strip, keep_fields, strip_fields, condense, git_diff_fold, strip_nulls, flatten, truncate_strings, collapse_arrays, custom_transforms\n- **6 post-stage processors** — RLE (run-length encoding), sliding window dedup, entropy-weighted truncation, self-information token pruning, dictionary compression, TOON encoding\n- **Word abbreviation** — 100+ common long words abbreviated at the output layer (implementation→impl, configuration→config, authentication→auth, etc.)\n- **Tabular encoding** — uniform JSON arrays (objects with identical keys) encoded as compact header + rows instead of repeated objects\n- **TOON encoding** — lossless JSON compression producing compact ASCII-safe output (reduction varies by structure, 4–30% typical)\n- **Tree-sitter AST** — structural code extraction for 4 languages natively (Rust, Python, JavaScript, Bash) + 14 via regex fallback (TypeScript, Go, Java, C, C++, Ruby, JSON, HTML, CSS, C#, Kotlin, Swift, TOML, YAML)\n- **Image compression** — screenshots → semantic DOM descriptions\n- **ANSI auto-strip** — removes color codes before compression\n\n### Caching \u0026 Deduplication\n- **SHA-256 content cache** — on a miss, content is compressed and stored; on a hit, the engine returns a compact inline reference (~13 tokens). LRU eviction, persisted across sessions.\n- **Compaction-aware dedup** — a turn-counter heuristic tracks when each ref was last sent. After 20 turns (configurable), refs are considered stale and the full compressed content is re-sent instead of a dangling reference. `notify_compaction()` explicitly invalidates all refs when the harness signals a context reset.\n- **Delta encoding** — near-duplicate content (similarity \u003e 0.6) produces a compact line-level diff instead of re-sending the full file. SimHash fingerprinting enables O(1) candidate detection before falling back to LCS comparison.\n- **N-gram abbreviation** — session-level phrase frequency tracking replaces recurring multi-word phrases with short symbols + legend.\n- **SQLite FTS5 session store** — cross-session memory with full-text search\n- **Correction log** — immutable append-only log that survives compaction\n- **CTX format** — portable session graph across Claude, GPT, and Gemini\n\n### Intelligence\n- **Confidence routing** — entropy analysis + pattern detection routes high-risk content (stack traces, secrets, migrations) to safe mode automatically\n- **TF-IDF + cosine tool selection** — exposes 3–5 relevant tools per task via TF-IDF weighted semantic matching (falls back to Jaccard for short queries)\n- **Prompt cache awareness** — preserves Anthropic 90% and OpenAI 50% cache boundaries\n- **Model routing** — routes simple tasks to cheaper local models based on complexity scoring\n- **Terse mode** — system prompt injection for concise LLM responses (3 levels)\n- **Predictive budget warnings** — alerts at 70% and 85% thresholds\n- **Compression quality metrics** — Shannon entropy-based efficiency measurement with quality grades (Excellent/Good/Fair/Poor) and headroom reporting\n- **TextRank extractive compression** — graph-based sentence ranking (PageRank algorithm) for prose content, keeps the most important sentences\n- **MDL stage selection** — Minimum Description Length principle selects the optimal compression stages per content type, skipping stages where overhead exceeds savings\n- **Transparent interception** — PreToolUse hooks for Claude Code, Cursor, Windsurf, Cline automatically pipe all bash output through sqz\n\n### Cost \u0026 Analytics\n- **Real-time USD tracking** — per-tool breakdown with cache discount impact\n- **Multi-agent budgets** — per-agent allocation with isolation and enforcement\n- **Session cost summaries** — total tokens, USD, cache savings, compression savings\n\n### Extensibility\n- **TOML presets** — hot-reload within 2 seconds, community-driven ecosystem\n- **Plugin API** — Rust trait + WASM interface for custom compression strategies\n- **100+ CLI patterns** — git, cargo, npm, docker, kubectl, aws, and more\n\n### Privacy\n- **Zero telemetry** — no data transmitted, no crash reports, no analytics\n- **Fully offline** — works in air-gapped environments after install\n- **Local only** — all processing happens on your machine\n\n## Platforms\n\nsqz integrates with AI coding tools across 4 levels:\n\n### Level 1 — MCP Config Only\nContinue · Zed\n\n### Level 2 — Shell Hook + MCP\nCopilot · Gemini CLI · Codex · OpenCode · Goose · Aider · Amp\n\n### Level 3 — PreToolUse Hook (Transparent Interception)\nClaude Code · Cursor · Windsurf · Cline — `sqz init` installs hooks that automatically pipe all bash output through sqz. No manual prefixing needed.\n\n### Level 4 — Native / Deep\n[VS Code](https://marketplace.visualstudio.com/items?itemName=ojuschugh1.sqz) · [JetBrains](https://plugins.jetbrains.com/plugin/31240-sqz--context-intelligence/) · Chrome (ChatGPT, Claude.ai, Gemini, Grok, Perplexity) · [Firefox](https://addons.mozilla.org/en-US/firefox/addon/sqz-context-compression/)\n\nSee [docs/integrations/](docs/integrations/) for platform-specific setup guides.\n\n## CLI Commands\n\n```sh\nsqz init              # Install shell hooks + AI tool hooks + default presets\nsqz hook claude       # Process a PreToolUse hook for Claude Code\nsqz hook cursor       # Process a PreToolUse hook for Cursor\nsqz compress \u003ctext\u003e   # Compress text (or pipe from stdin)\nsqz compress --verify # Compress with confidence score\nsqz compress --mode safe|aggressive  # Force compression mode\nsqz discover          # Find missed savings opportunities\nsqz resume            # Resume previous session with context guide\nsqz stats             # Cumulative compression report\nsqz gain              # ASCII chart of daily token savings\nsqz gain --days 30    # Last 30 days\nsqz analyze \u003cfile\u003e    # Per-block Shannon entropy analysis\nsqz export \u003csession\u003e  # Export session to .ctx format\nsqz import \u003cfile\u003e     # Import a .ctx file\nsqz status            # Show token budget and usage\nsqz cost \u003csession\u003e    # Show USD cost breakdown\n```\n\n## Configuration\n\nsqz uses TOML presets with hot-reload. The `[preset]` table maps to the Rust `PresetHeader` type (`name`, `version`, optional `description`).\n\n```toml\n[preset]\nname = \"default\"\nversion = \"1.0\"\n\n[compression]\nstages = [\"keep_fields\", \"strip_fields\", \"condense\", \"strip_nulls\",\n          \"flatten\", \"truncate_strings\", \"collapse_arrays\", \"custom_transforms\"]\n\n[compression.condense]\nenabled = true\nmax_repeated_lines = 3\n\n[compression.strip_nulls]\nenabled = true\n\n[budget]\nwarning_threshold = 0.70\nceiling_threshold = 0.85\ndefault_window_size = 200000\n\n[terse_mode]\nenabled = true\nlevel = \"moderate\"\n\n[model]\nfamily = \"anthropic\"\nprimary = \"claude-sonnet-4-20250514\"\ncomplexity_threshold = 0.4\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                Integration Surfaces                  │\n│  CLI Binary  │  MCP Server  │  Browser  │  IDE Ext  │\n└──────┬───────┴──────┬───────┴─────┬─────┴─────┬─────┘\n       │              │             │            │\n       └──────────────┴─────────────┴────────────┘\n                          │\n       ┌──────────────────┴──────────────────┐\n       │         sqz_engine (Rust core)       │\n       │         53 modules · ~30K lines      │\n       │                                      │\n       │  Compression Pipeline (16 stages)    │\n       │  TOON Encoder (lossless JSON)        │\n       │  AST Parser (tree-sitter, 18 langs)  │\n       │  Cache Manager (SHA-256 + SimHash)   │\n       │  Delta Encoder (LCS + SimHash)       │\n       │  Session Store (SQLite FTS5)         │\n       │  Budget Tracker (multi-agent)        │\n       │  Cost Calculator (real-time USD)     │\n       │  Tool Selector (TF-IDF + cosine)     │\n       │  Confidence Router (entropy-based)   │\n       │  Prompt Cache Detector               │\n       │  Model Router (complexity routing)   │\n       │  Token Pruner (self-information)     │\n       │  Entropy Truncator (rate-distortion) │\n       │  RLE Compressor + Sliding Window     │\n       │  Dict Compressor (JSON fields)       │\n       │  BPE Compressor (vocabulary)         │\n       │  SimHash (LSH fingerprinting)        │\n       │  Compression Quality (Shannon bound) │\n       │  N-gram Abbreviator (session-level)  │\n       │  Correction Log (append-only)        │\n       │  Plugin API (Rust + WASM)            │\n       └─────────────────────────────────────┘\n```\n\n## Distribution\n\n| Channel | Command | Status |\n|---|---|---|\n| Cargo | `cargo install sqz-cli` | Live |\n| Homebrew | `brew install sqz` | Coming soon |\n| npm | `npm install -g sqz-cli` / `npx sqz-cli` | Coming soon |\n| curl | `curl -fsSL .../install.sh \\| sh` | Coming soon |\n| Docker | `docker run sqz` | Coming soon |\n| GitHub Releases | Pre-built binaries for Linux, macOS, Windows | Coming soon |\n\n## Development\n\n```sh\ngit clone https://github.com/ojuschugh1/sqz.git\ncd sqz\ncargo test --workspace    # 805 tests\ncargo build --release     # optimized binary\n```\n\n### Rust API names (`sqz_engine`)\n\nPrefer the primary type names below; the second name in each row is a `type` alias kept for compatibility.\n\n| Primary | Alias |\n| --- | --- |\n| `Session` | `SessionState` |\n| `Turn` | `ConversationTurn` |\n| `PinnedSegment` | `PinEntry` |\n| `KvFact` | `Learning` |\n| `WindowUsage` | `BudgetState` |\n| `ToolCall` | `ToolUsageRecord` |\n| `EditRecord` | `CorrectionEntry` |\n| `EditHistory` | `CorrectionLog` |\n| `PresetHeader` | `PresetMeta` |\n\n**File cache:** `CacheManager` returns `CacheResult::Dedup` (compact inline reference, ~13 tokens), `CacheResult::Delta` (near-duplicate diff), or `CacheResult::Fresh` (newly compressed payload). Stale refs (older than 20 turns) automatically return `Fresh` to avoid dangling references after context compaction.\n\n**Defensive API:** `SqzEngine::compress_or_passthrough()` guarantees any input produces a `CompressedContent` output — never returns an error. On internal failure, returns the original input unchanged.\n\n**Sandbox:** `SandboxResult` uses `status_code`, `was_truncated`, and `was_indexed` (stdout-only data enters the context window).\n\n### Project Structure\n\n```\nsqz_engine/     Core Rust library (53 modules, all compression logic)\nsqz/            CLI binary (shell hooks, commands)\nsqz-mcp/        MCP server binary (stdio/SSE transport)\nsqz-wasm/       WASM target for browser extension\nextension/      Chrome extension (content scripts, popup)\nvscode-extension/   VS Code extension (TypeScript)\njetbrains-plugin/   JetBrains plugin (Kotlin)\ndocs/           Integration guides and documentation\n```\n\n### Testing\n\nThe test suite includes 805 tests with 83 property-based correctness properties validated via proptest:\n\n- TOON round-trip fidelity\n- Compression preserves semantically significant content\n- ASCII-safe output across all inputs\n- File cache — deduplication, staleness detection, and invalidation\n- Compaction-aware ref tracking (stale refs re-send content)\n- Delta encoding similarity bounds\n- SimHash hamming distance symmetry and bounds\n- Budget token count invariants\n- Pin/unpin compaction round-trips\n- CTX format round-trip serialization\n- Plugin priority ordering\n- Tool selection cardinality bounds (TF-IDF + Jaccard)\n- Cross-tokenizer determinism\n- RLE and sliding window dedup bounds\n- Entropy truncation segment accounting\n- BPE merge savings non-negativity\n- Zipf's law vocabulary pruning preservation\n\n## Contributing\n\nWe welcome contributions. By submitting a pull request, you agree to the [Contributor License Agreement](CLA.md).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.\n\n## License\n\nLicensed under [Elastic License 2.0](LICENSE) (ELv2). You can use, fork, modify, and distribute sqz freely. Two restrictions: you cannot offer it as a competing hosted/managed service, and you cannot remove licensing notices.\n\nWe chose ELv2 over MIT because MIT permits repackaging the code as a competing closed-source SaaS — ELv2 prevents that while keeping the source available to everyone.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fojuschugh1%2Fsqz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fojuschugh1%2Fsqz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fojuschugh1%2Fsqz/lists"}