sqz

  ███████╗ ██████╗ ███████╗
  ██╔════╝██╔═══██╗╚══███╔╝
  ███████╗██║   ██║  ███╔╝
  ╚════██║██║▄▄ ██║ ███╔╝
  ███████║╚██████╔╝███████╗
  ╚══════╝ ╚══▀▀═╝ ╚══════╝
  

为 AI 编码 Agent 提供注入前上下文压缩与会话去重

_{真实会话统计： 3,003 次压缩 · 节省 178,442 个 token · 平均减少 24.7% · 对模型已有的输出最多可减少 92%}

文档 · 安装 · 工作原理 · 支持的工具 · MCP 代理 · 基准测试 · 更新日志 · Discord

English | 简体中文 | 日本語 | 한국어 | Español | Português (Brasil)

---

AI 编码 Agent 的输入 token 大多消耗在工具输出上：构建日志、测试运行结果、git status，以及每次编辑后再次读取的同一个文件。这些内容未经处理就全部进入上下文窗口，并在之后的每一轮中重新发送。

sqz 会在工具输出进入上下文之前对其进行压缩。针对各命令的格式化器会保留 Agent 需要采取行动的内容（失败的测试、断言、file:line），并丢弃无关内容。模型上下文中已有的内容会以简短引用代替原文。源代码原样传递，堆栈跟踪、迁移内容和凭据行也同样如此。

cargo install sqz-cli sqz-mcp     # or: brew install ojuschugh1/sqz/sqz · npm i -g sqz-cli · pipx install sqz
sqz init                          # hooks + MCP server + agent guidance for every client it finds

_{来自发布版二进制文件的实际输出（assets/demo.tape）。使用 vhs assets/demo.tape 重新生成。}

Without sqz:                              With sqz:

cat auth.py (200 lines):   1,300 tokens    1,300 tokens  (source is served in full)
cargo test (1 failure):      366 tokens      185 tokens  (failure, assertion, file:line)
sed -n '41,80p' auth.py:     260 tokens       35 tokens  (§ref:…:L41-80§ to the read above)
git status, unchanged:       166 tokens       37 tokens  (§ref:…§)
─────────────────────────────────────      ─────────────
Total:                     2,092 tokens    1,557 tokens  (26% saved, nothing dropped)

单个 Rust 二进制文件，结果确定，无需调用大模型，可离线运行。每个压缩结果都能通过 sqz expand 逐字节精确还原，唯独提及凭据、堆栈跟踪或迁移的输出不会被 sqz 缓存。

说明

名称消歧： 本仓库 ojuschugh1/sqz 是一个独立项目，与其他任何名称相似或功能相同的工具，或其他用于缩短 “squeeze” 的压缩项目均无关联。如果你从 crates.io、npm、PyPI 或 Homebrew 安装了 sqz / sqz-cli / sqz-mcp，它们来自本仓库。

Token 节省

24.7%：基于 3,003 次实际压缩的平均缩减比例 · 13-token：模型已持有的输出所需的引用长度 · 100%：在质量基准测试中保留的 Agent 关键事实 · 0%：源代码、堆栈跟踪和凭据行的压缩比例

一位开发者一周的实际数据，取自 sqz gain 的输出：

$ sqz gain
sqz token savings (last 7 days)
──────────────────────────────────────────────────
  04-13 │                              │   2,329 saved
  04-14 │                              │       0 saved
  04-15 │███                           │  12,954 saved
  04-16 │██                            │   9,223 saved
  04-17 │████                          │  14,752 saved
  04-18 │██████████████████████████████│ 105,569 saved
  04-19 │████████                      │  30,882 saved
  04-20 │█                             │   4,334 saved
──────────────────────────────────────────────────
  Total: 3,003 compressions, 178,442 tokens saved (24.7% avg reduction)

单命令压缩

单命令压缩（通过 cargo test -p sqz-engine benchmarks 测量）：

内容	压缩前	压缩后	节省
重复日志行	148	39	74%
大型 JSON 数组	259	111	57%
JSON API 响应	64	53	17%
Git 差异	61	54	11%
文本/文档	124	122	2%
堆栈跟踪（安全模式）	82	82	0%

会话级去重

模型上下文中已有的内容会以引用形式返回。使用发布版二进制文件和临时数据库进行测量，测试数据来自 sqz/tests/quality_bench.rs 和 demo/，统计 Agent 能看到的所有内容（引用加上 sqz 在 stderr 输出的一行说明）的 cl100k token 数：

重复内容	不使用 sqz	使用 sqz	节省
再次运行且未变化的 git status	166	37	78%
读取先前读过的 200 行文件中的第 41–80 行	260	35	87%
相同的 cargo test 输出，内容未变化	366	39	89%

说说实际会重复什么。一位用户统计了自己 92 个 Claude Code 会话（脚本），发现 542 次读取中只有 1 次是重复读取整个文件，重复读取行范围的情况则占 8.4%。因此 sqz 不会以“同一个文件读五遍”为主要卖点：实际发生的重复包括未变化的命令输出、已读文件的行范围，以及小幅编辑后重新读取文件，而每种情况都有对应的引用类型（详情）。命令输出嘈杂且命令重复运行的会话，收益最大。

安装

预构建二进制文件（无需编译器 — 可在所有平台上运行）：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.ps1 | iex

# Any platform via npm
npm install -g sqz-cli

# macOS / Linux via Homebrew
brew tap ojuschugh1/sqz
brew install sqz

通过 Cargo 从源代码构建：

cargo install sqz-cli sqz-mcp

sqz-cli 提供 sqz 二进制文件；sqz-mcp 提供 MCP 服务。sqz-engine 是库依赖项 — 会自动编译，无需单独安装。

从源代码构建（cargo install sqz-cli）也可行，但需要 C 工具链：

• Linux：build-essential（apt）或等效工具
• macOS：Xcode 命令行工具（xcode-select --install）
• **Windows：安装了“Desktop development with C++”工作负载的 Visual Studio Build Tools。**如果没有这些工具，cargo install 会报错，提示 linker link.exe not found。如果尚未安装，请改用上文的 PowerShell 或 npm 安装方式。

然后初始化：

sqz init --global     # hooks apply to every project on this machine
# or
sqz init              # hooks apply to just this project (.claude/settings.local.json)

--global 会写入 ~/.claude/settings.json（根据 Anthropic 范围表，这是用户范围）， 因此 sqz hook 会在这台机器上的每个 Claude Code 会话中触发。这是首次安装时的 常见情况。~/.claude/settings.json 中现有的 permissions、env、 statusLine 和其他无关 hook 都会保留 — sqz 会合并自己的条目，而不是覆盖它们。 这些条目包括它的 hook 和两条 allow 规则：Bash(set -o pipefail) 与 Bash(sqz compress --cmd *)，仅涵盖它所添加重写内容涉及的部分。 sqz 不会批准命令；仍由你自己的权限规则决定。 当 Claude Code 在执行重写后的命令前征求确认或拒绝执行时，提示信息中会 引用重写后的命令，例如，git tag v0 会显示为 set -o pipefail; git tag v0 2>&1。

如果你希望仅在某个仓库中启用 sqz，可以使用普通的 sqz init（项目范围）。 如果 ~/.claude/settings.json 中已包含 sqz hook，它会将这些 hook 从项目文件中排除，因为它们已经在每个项目中运行。

安装后，sqz doctor 会检查整个链路 — 二进制文件、数据库、shell hook、检测到的客户端与实际经由 sqz 路由的客户端，以及近期是否有内容被压缩 — 并为发现的每个问题输出修复方法。sqz doctor --fix 会应用这些修复。升级 sqz 后，请运行一次：它会更新旧版本写入的 hook 和指引，移除当前 sqz 已不再使用的 hook 文件以及 ~/.claude/settings.json 中已存在 hook 的项目副本，将找不到 sqz 二进制文件的 hook 指向当前运行的二进制文件，并提示仍在运行其他 sqz 二进制文件的 hook。sqz uninstall 只会移除 sqz 自己的条目，仅在文件中已无其他内容时才删除该文件，最后会列出保留的文件。如果无法使用终端回答提示，则需要添加 --yes，与 sqz reset 相同。

在安装任何钩子之前，先看看 sqz 能节省多少

如果你已经在使用 Claude Code 或 Kiro，你的会话记录就保存在磁盘上。通过 sqz 引擎重放这些记录，就能根据你自己的会话计算反事实估算，所有计算都在本地完成，不会上传任何内容。以下是作者上周使用 Kiro IDE 工作的记录，已精简为摘要：

$ sqz discover --replay
sqz discover — counterfactual replay (last 7 days)
────────────────────────────────────────────────────────

  Kiro IDE: 35 sessions, 155 sub-agent runs, advisory

                            outputs    tokens in    avoidable
    shell                     6,297    1,917,662      454,028  23.7%
    file reads                4,880    7,854,071      188,239   2.4%
    other MCP servers         1,547    6,717,440    4,234,128  63.0%
    already through sqz         260    1,393,517            -
    out of reach              4,172    1,282,285            -

  Avoidable with no help from the agent:   0 tokens
  Avoidable if the agent uses every route: 4,876,395 tokens, 25.4% of all tool output
  Of that, 3,816,588 is the MCP proxy's lossy first pass.

每项输出都会按照 sqz 在该客户端上实际可能采用的方式进行重放。Kiro 不允许 sqz 重写工具调用，因此这里的第一项总计为零；在 Claude Code 中，shell 行会拆分为钩子自行重写的命令和跳过的命令。第二项总计假设 Agent 通过 sqz compress 管道处理 shell 输出，使用 sqz MCP 工具读取文件（无损，因此只统计重复内容），并在 sqz-mcp proxy 后运行 MCP 服务。报告还会说明代理在首次处理时裁剪长字符串和数组所节省的内容。所有客户端都无法处理网页抓取、编辑和子 Agent 结果；这些内容只会计入统计，不会重放。

它会扫描 ~/.claude/projects 和 ~/.kiro/sessions（Kiro CLI 和 IDE），也可以通过 --transcripts PATH 指定任意路径。每份会话记录都会使用全新的一次性缓存进行重放，因此去重引用不会假装跨会话生效。报告使用“估算”一词，是因为这确实只是估算：这些输出当时并未经过压缩。

只使用一个 Agent？ 传入 --only（或 --skip）来限制要写入的配置：

sqz init --only opencode              # just OpenCode, nothing else
sqz init --only opencode,codex        # OpenCode and Codex
sqz init --skip cursor,windsurf       # everything except Cursor and Windsurf

接受的名称：claude、cursor、windsurf、cline、gemini、kiro、opencode、codex。别名（claude-code、gemini-cli、roo、kiro-cli）也可使用。--only 和 --skip 不能同时使用。

手动安装（保留配置中的注释）

sqz init 会通过 JSON 解析器往返处理你的配置文件，以合并 sqz 条目，这会删除 opencode.jsonc（以及其他工具接受的类似带注释 JSON 文件）中的注释。如果你仔细为配置添加了注释，并希望保留它们，请改为手动安装。

OpenCode — 分两步：

1. 将插件文件放到指定位置。sqz 会将生成的 TS 输出到 stdout，因此你无需手动编写路径转义逻辑：

   mkdir -p ~/.config/opencode/plugins
   sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts
   

2. 自行将 MCP 条目添加到现有的 opencode.jsonc 中。 将此代码块追加到顶层 mcp 对象中（如果不存在 mcp 对象，则先创建）：

   "sqz": {
     "type": "local",
     "command": ["sqz-mcp", "--transport", "stdio"],
     "enabled": true
   }
   

文件其余部分的注释都会保留。OpenCode 会自动发现插件文件；无需添加 plugin 数组条目（添加后会导致重复加载，参见 issue #10）。

同一个插件文件可在 OpenCode 1 和 2 上加载。OpenCode 2 不会加载 sqz 2.0.0 及更早版本写入的插件，因此升级 sqz 后，请运行 sqz doctor --fix（或再次运行上方的 print-opencode-plugin 命令）来重写插件文件。

其他工具：Claude Code 和 Gemini CLI 使用不支持注释的纯 JSON 配置；Cursor、Windsurf 和 Cline 使用 Markdown 规则文件；Codex 则会在 ~/.codex/config.toml 中添加 TOML 条目并保留注释，因此这些工具的自动配置方式不会造成破坏。请对这些工具使用 sqz init --only <tool>。如果已有 .gemini/settings.json，sqz 会将钩子合并进去；如果其中包含注释或无法解析，sqz init 会保持文件不变，并打印出需要手动添加的条目。

之后运行 sqz doctor，查看每个客户端的配置情况及其所处的集成层级。

工作原理

对于透明客户端（Claude Code、Gemini CLI、Copilot CLI、OpenCode），sqz 会安装一个钩子，重写 shell 命令，让其输出在到达 AI 工具之前先经过 sqz 处理。对于建议型客户端，系统会告知 Agent 将输出通过管道传入 sqz compress，或使用 sqz MCP 工具。下表列出了各客户端的级别。

Claude → git status → [sqz hook rewrites] → compressed output

压缩的内容：

• Shell 输出：针对各命令的格式化工具（git、cargo、npm/pnpm/yarn/bun、pytest、ruff、mypy、go、docker ps/images、kubectl describe/apply、terraform、gradle、maven、xcodebuild、adb logcat、dotnet、grep/rg、tree、curl 等）
• JSON：移除 null 和空值，将超过 500 个字符的字符串截短，采用紧凑编码、TOON 格式
• 日志 — 折叠重复行
• 测试输出 — 仅显示失败项（针对 Rust、Go、Python、JS、JVM 的状态机解析器）

不会压缩的内容：

• 源代码：首次读取时完整提供
• 堆栈跟踪、SQL 迁移、PEM 块和凭据行：会进入安全模式并原样传递，不受大小限制，也不会缓存；在 shell 钩子中，针对单个命令的格式化工具仍可能对其周围的测试运行内容进行摘要
• 你的提示词和 AI 的响应 — 由 AI 工具控制，而非 sqz

支持的工具

工具	集成方式	设置
Claude Code	PreToolUse + PostToolUse 钩子 + MCP 服务（透明）	sqz init
Cursor	.cursor/rules/sqz.mdc 指引（建议型）；需手动添加 MCP 服务	sqz init
Windsurf	.windsurf/rules/sqz.md 指引（建议型）；需手动添加 MCP 服务	sqz init
Cline	.clinerules 指引（建议型）；需手动添加 MCP 服务	sqz init
Gemini CLI	BeforeTool 钩子（透明）	sqz init
Kiro	Steering + MCP 服务（建议型）	sqz init
OpenCode	适用于 OpenCode 1 和 2 的 TypeScript 插件 + MCP 服务（透明）	sqz init
Codex CLI	AGENTS.md 指引 + MCP 服务（建议型）	sqz init
Zed	AGENTS.md 指引 + MCP 服务（建议型）	sqz init
Copilot CLI	preToolUse 钩子（透明），需存在 ~/.copilot	sqz init
Copilot 编码 Agent（CI）	仓库级钩子，可在云沙盒中自行引导启动	sqz init --ci + 提交
任意 CI 流水线	setup-sqz action — 在 LLM 步骤前压缩日志	uses: ojuschugh1/setup-sqz@v1
任意 MCP 服务	sqz-mcp proxy 对其进行封装，并压缩其工具结果	见下文
VS Code	扩展	从 Marketplace 安装
JetBrains	插件	从 Marketplace 安装
Chrome	浏览器扩展	ChatGPT、Claude.ai、Gemini、Grok、Perplexity
Firefox	浏览器扩展	相同网站

透明客户端具有一个钩子，会自行将 shell 命令通过 sqz 处理。对于建议型客户端，只有当 Agent 将输出通过管道传入 sqz compress 或调用 sqz MCP 工具时，sqz 才会节省令牌；客户端内置的 shell 和文件工具会绕过它。sqz doctor 会显示各客户端的级别。

压缩任意 MCP 服务

sqz-mcp proxy 位于你的 Agent 与任意 stdio MCP 服务之间，并压缩返回的数据：工具结果会经过完整的 sqz 流程（重复内容使用去重引用、堆栈跟踪和机密信息采用安全模式、错误结果保持不变），并精简冗长的工具描述，让 tools/list 不再占用你的上下文窗口。代理会注入一个 sqz_expand 工具，让 Agent 能以字节级精确的方式恢复任何缓存的原始内容；提及凭据、堆栈跟踪或迁移的结果绝不会被缓存。

在 MCP 配置中，将服务的命令加上此前缀即可完成封装：

{
  "mcpServers": {
    "github": {
      "command": "sqz-mcp",
      "args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}

标志：--lazy-tools 会将每个工具描述缩短为一句话，并注入一个 sqz_tool_help 工具，按需提供完整的原始文档（有些 MCP 服务仅 tools/list 就会占用 10-40k 个 token）；--no-desc 会原样保留描述；--no-cache 不存储任何内容，因此不会发送去重引用，也不会添加 sqz_expand 工具。适用于所有 MCP 客户端（Claude Code、Cursor、Windsurf、Zed、Codex、Kiro，……），因为客户端看到的只是一个普通 MCP 服务。完整指南（包括服务自带的 sqz_read_file / sqz_grep / sqz_list_dir 工具和各客户端的配置）：MCP 上下文压缩。

CLI

sqz init --global             # Install hooks for every project on this machine
sqz init                      # Install hooks for just this project
sqz init --only kiro          # Only configure Kiro (skip the rest)
sqz init --only opencode      # Only configure OpenCode (skip the rest)
sqz init --skip cursor        # Configure every agent except Cursor
sqz init --ci                 # Also write .github/hooks/sqz.json for Copilot agent CI runs
sqz compress <text>           # Compress (or pipe from stdin)
sqz compress --no-cache       # Compress without dedup (always full output)
sqz expand <ref>              # Recover original content from a §ref:HASH§ token
sqz compact                   # Evict stale context to free tokens
sqz reset                     # Clear dedup cache or compression stats
sqz gain                      # Show daily token savings (bar chart)
sqz gain --project .          # Per-project daily gains
sqz gain --days 30            # Last 30 days
sqz stats                     # Cumulative compression report (includes regret signals)
sqz stats --cost              # Estimated $ saved under a prompt-cached billing model
sqz stats --breakdown         # Per-command token usage breakdown
sqz stats --project .         # Stats for current project only
sqz stats --project list      # List all tracked projects
sqz stats --share             # Five-line share card sized for a paste into an issue or post
sqz doctor                    # Verify sqz is installed, wired into your clients, and active
sqz doctor --fix              # Apply the fixes doctor prints (run once after upgrading)
sqz uninstall                 # Remove sqz's hooks, guidance and MCP entries, keep the rest
sqz discover                  # Find missed savings (incl. your weakest-compressing commands)
sqz discover --replay         # Counterfactual replay of your agent transcripts (Claude Code, Kiro)
sqz recall "auth timeout"     # Full-text search everything sqz has compressed
sqz resume                    # Re-inject session context after compaction
sqz vizit                     # Live terminal dashboard (like htop for AI agents)
sqz hook claude               # Process a PreToolUse hook (Claude Code)
sqz hook claude-post          # Process a PostToolUse hook (Claude Code)
sqz hook kiro                 # Legacy; Kiro now uses steering + MCP (sqz init)
sqz print-opencode-plugin     # Print OpenCode plugin TS for manual install
sqz proxy --port 8080         # Local endpoint: compresses an API request body and sends it back, no forwarding

去重应急方案

当 sqz 发现相同内容出现两次时，会返回精简的 §ref:HASH§ 令牌，而不是完整文本。大多数模型都能正常处理，但有些模型（例如 GLM 5.1）无法解析这种引用格式，会陷入循环。以下是四种应对方法：

# 1. Recover original content from a ref
sqz expand a1b2c3d4              # prefix match
sqz expand '§ref:a1b2c3d4§'     # paste the whole token

# 2. Compress without dedup (per-invocation)
echo "..." | sqz compress --no-cache

# 3. Disable dedup globally (env var)
export SQZ_NO_DEDUP=1

# 3b. Or just shorten the ref freshness window (seconds, default 1800).
# Useful on clients without a compaction hook; 0 disables refs.
export SQZ_REF_TTL_SECS=300

# 4. MCP passthrough tool (returns input byte-exact, zero transforms)
# Available via tools/list when sqz-mcp is running

Recall：搜索 sqz 见过的所有内容

所有流经 sqz 的内容都会在本地建立索引（SQLite FTS5，数据只保存在你的设备上，不会外传）。当 Agent 压缩上下文后，丢失了一小时前的错误消息时，可以搜索它，而不是重新运行命令：

$ sqz recall "connection refused"
  1. [git · 2h ago]  … curl: (7) Failed to connect: >>connection refused<< on port 5432 …
     full content: sqz expand 3f9a1c05e2d84b17

Agent 也可以通过 sqz_recall MCP 工具使用同样的功能。

跟踪你自己的节省量

随时在 shell 中运行 sqz gain，查看你每天的明细（输出示例请参阅上文的 Token 节省部分）；运行 sqz stats 查看完整的累计报告：

$ sqz stats
  📊 sqz compression stats
  ──────────────────────────────────────────────────

  178,442  tokens saved
  ↓  24.7% average reduction

  Compressions           3,003
  Tokens in              721,840
  Tokens out             543,398
  Tokens saved           178,442
  Avg reduction          24.7%

  🗄️  Cache
  ──────────────────────────────────────────────────
  Entries                43
  Size                   39.1 KB

添加 --breakdown，即可准确查看哪些命令消耗的 token 最多：

$ sqz stats --breakdown

  🔍 Top Token Consumers
  ──────────────────────────────────────────────────────────────────────
  command               calls  tokens in        out    saved
  ──────────────────────────────────────────────────────────────────────
  dedup                   249      45541       3237      93%
  stdin                    51      30851      24289      21%
  auto                    132      18288       7740      58%
  echo                     17       1050        558      47%
  ls -la                    8        948        948       0%
  cargo build               7        170        145      15%
  git status                4         56          8      86%
  ──────────────────────────────────────────────────────────────────────

sqz stats 和 sqz gain 会统计 sqz 实际输出内容的 cl100k token 数，其中包括缩写说明和展开提示。对于超过 2 KB 的连续同类字符（例如一长行分隔符），会按每 2 KB 分段计数，误差约为 1%，另加 4 个 token。

坦诚核算：成本与后悔

Token 减少并不一定意味着计费成本降低——借助服务提供商的提示词缓存，大部分上下文会以约 90% 的折扣重新传输；而压缩如果删掉了 Agent 需要的内容，就会增加额外轮次 （arXiv:2607.12161）。sqz 会同时衡量这两方面，而不是含糊其辞：

• sqz stats --cost 会根据提示词缓存计费模型估算节省的金额（缓存写入 ×1.25，仅计一次；后续每轮缓存读取 ×0.10），并打印所有假设，且支持覆盖（--price-in、--reread-turns、--cache-write-mult、--cache-read-mult）。这是保守估算：如果没有缓存，同样的节省会按每轮完整的输入价格计费。
• sqz stats 会报告后悔信号：快速重跑（Agent 在 2 分钟内重新生成了逐字节相同的输出——重复操作毫无收益；Claude Code PostToolUse hook 从不通过引用作答，因此这类重复会计为普通压缩），以及 ref 展开（将 §ref§ token 还原为原始字节）。这两者都是“压缩删掉了模型需要的内容”的间接指标。如果某条命令总是出现，就说明它的格式化器需要改进——请提交 issue。

sqz 的设计已经规避了研究测得的失效模式：压缩具有确定性，且与查询无关（绝不会使服务提供商的提示词缓存失效）；只处理新工具输出（不会重写历史记录）；会留下那些后续还有输出、运行服务或将任务置于后台的命令（在 Claude Code 非 bypass 模式下，PreToolUse hook 会按原样保留管道、循环和 heredoc，PostToolUse hook 则会在成功运行后压缩它们的输出）；分组列表和管道（Gemini CLI、Copilot CLI、bypass 模式下的 Claude Code）会跳过逐命令格式化器；16-token 净收益门槛会跳过那些省不出自身标记开销的压缩。如果重写可能导致运行与原命令不同的一组命令，也会按原样保留命令。在 ls ${DEST:?}; echo next 中，如果单独对 ls 使用管道，那么当扩展失败导致 shell 停止后，echo next 仍会运行；而当列表作为一个整体交给 sqz 处理时，cd build && make; make test 中 cd 失败会跳过整个分组，而不只是跳过 make。

按项目筛选：

sqz stats --project .           # stats for current project only
sqz stats --project list        # list all tracked projects
sqz gain --project .            # daily gains for current project
sqz gain --days 30              # last 30 days instead of 7
sqz gain --days 30 --project .  # combine both

统计数据会以 SQLite 格式存储在本地的 ~/.sqz/sessions.db 中——不会有任何数据离开你的设备。

压缩原理

1. 以下命令使用专用格式化器：

   生态系统	命令
   Git	status、log、diff、show、stash、remote、fetch、push、pull、add、commit
   Rust	cargo build/test/clippy/check/nextest
   JavaScript	npm/pnpm/yarn/bun install/audit/outdated（test 和 run 失败时也会处理）、tsc、eslint、biome
   Python	pytest、ruff、mypy、pip
   Go	go test（包括 -json 流）、go build、go vet、golangci-lint
   Cloud	terraform plan/apply/destroy/refresh/init
   容器	docker/podman ps/images、kubectl describe/apply
   JVM	gradle build/test、maven
   移动端	xcodebuild（build + test）、adb logcat
   .NET	dotnet build/publish/test
   系统	grep/rg、tree、curl/wget

   其他命令，包括 kubectl get 和 logs、gh、aws、gcloud、ls 和 find，都会经过通用压缩流程。

2. 表格压缩器——没有专用格式化器的工具输出的对齐列（ps aux、netstat、数据库 CLI）会将连续填充空格压缩为两个空格的分隔符。检测条件很严格——缩进的行、代码、YAML 和 JSON 均不会匹配。

3. 结构化摘要：引擎提供一个 API，可将代码文件精简为导入项、函数签名和调用图。钩子和 MCP 路径不会使用它；它们会完整提供源代码。

4. 去重缓存：使用 SHA-256 内容哈希，并在会话之间持久保存。模型已获取过的字节完全相同的输出 = 13 个 token 的引用。模型已完整获取过的文件中的某个行范围（sed -n '40,80p'、使用 offset/limit 的 sqz_read_file）= §ref:HASH:L40-80§。通过 sqz MCP 工具重新读取小幅编辑后的文件 = 变更行及其两侧各一行未变更的内容（shell 钩子会再次发送已编辑的文件）；如果编辑分散在文件各处，则会返回完整文件。只有原始内容仍在上下文中时才会提供引用（30 分钟窗口，可通过 SQZ_REF_TTL_SECS 调整，压缩时重置）。

5. JSON 流程：移除 null 值 → 删除记账字段（__v、etag、请求 ID 和关联 ID）→ 扁平化 → 折叠数组 → 使用 TOON 编码（无损紧凑格式）。在任何嵌套深度，值为空字符串、数组或对象的字段都会被删除；超过 500 个字符的字符串会截断至前 500 个字符，后接 ...。

6. 安全模式：堆栈跟踪（跟踪标头后接其帧）、行首的 SQL DDL、PEM 块和凭据行（key=value 或 key: value，且键看起来像密钥），无论是否带有 ANSI 颜色，都会跳过处理流程并原样传递，不受大小限制；唯一例外是会剥除 ANSI 代码，并且绝不缓存。在 shell 钩子中，仍会先运行逐命令格式化器。只有当摘要能够原样保留每个包含上述内容的段落中的所有行时，才会使用该摘要；因此，它可以对包含跟踪的测试运行其余部分进行摘要；否则，整个输出会直接传递。若输出只是在这些结构之外提及密码、密钥、跟踪或迁移，则仍会按常规压缩，但不会缓存，因此有损阶段丢弃的内容无法还原。

如果某个阶段发生 panic，sqz compress 会原样输出输入，在 stderr 上打印一行内容，并保留命令的退出状态；Claude Code PostToolUse 钩子则会保持结果不变。

质量测量结果（包括各阶段会丢弃什么，以及绝不会触碰什么）：质量基准。完整技术详情请参阅 docs/。

配置

# ~/.sqz/presets/default.toml
[preset]
name = "default"
version = "1.0"

[compression.condense]
enabled = true
max_repeated_lines = 3

[compression.strip_nulls]
enabled = true

[budget]
warning_threshold = 0.70
default_window_size = 200000

每个项目的数据库

sqz 持久化的所有内容（统计数据、去重缓存、会话）都存储在一个 SQLite 文件中，默认为 ~/.sqz/sessions.db。设置 SQZ_DB_PATH 即可改为按项目存储：

# e.g. in the project's .envrc (direnv)
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"

所有使用场景都会遵循此设置——Shell 钩子、sqz stats/gain/expand，以及 MCP 服务（在 MCP 配置的 env 下设置）。建议使用绝对路径：相对路径会根据进程的 当前工作目录解析。如果父目录不存在，会自动创建（权限模式为 0700，与 ~/.sqz 相同）。

隐私

• 零遥测——不会传输数据，也不会生成崩溃报告
• 完全离线——可在隔离网络环境中运行
• 所有处理均在本地完成

开发

git clone https://github.com/ojuschugh1/sqz.git
cd sqz
cargo test --workspace
cargo build --release

许可证

sqz 采用 Apache License, Version 2.0 或 MIT license 进行许可，由你选择。

版权所有 2026 Ojus Chugh

截至 2.0.0（含）的版本均根据 Elastic License 2.0 发布。

贡献须遵守 Contributor License Agreement。

链接

• 文档索引
• 如何阻止 AI 编码 Agent 反复读取同一文件
• MCP 上下文压缩
• 质量基准：压缩率与信息保留
• 上下文腐化与上下文压缩
• 选择上下文压缩方案
• 白皮书：注入前上下文压缩
• Token 节省基准
• Discord
• 更新日志
• MCP Registry 名称：mcp-name: io.github.ojuschugh1/sqz

Star 历史

如果 sqz 今天帮你节省了 Token，点个 Star 就能帮助其他人发现它。如果你想展示自己的数据，可以运行 sqz stats --share 查看。

贡献者

感谢所有为 sqz 贡献代码、修复和创意的人：

也感谢所有提交详细错误报告、帮助我们修复问题的人。精准的复现步骤让这个项目在每次发布时都变得更好。想加入他们吗？PR 审核很快：查看未解决的问题，即可开始参与。

_{贡献者列表由 contrib.rocks 生成。}