Sqz: AIコーディングのコンテキスト圧縮
AIエージェント用事前圧縮: 平均24.7%削減、重複は92%。Rust製、オフライン、LLM呼び出しゼロ。
AIコーディングエージェントは推論でトークンを燃やしているのではない。cargo testの出力、git statusの spam、同じファイルの5回読みで燃やしている。
それを解くのが sqz ↗。モデル context に入る前にツール出力を圧縮する単一 Rust バイナリ。LLM呼び出しなし、完全オフライン、sqz expandでバイト完全復元。
実セッション統計: 3,003回圧縮、178,442トークン節約、平均24.7%削減、既知出力では92-96%。
なぜ重要か#
毎ターン履歴を再送する。1,200トークンのテストログは1回払いではない。compaction まで毎ターン払い続ける。prompt caching を入れると課金計算は微妙になるが方向は明確: ノイズ出力はセッションを短くし、コストを上げ、有用な推論を追い出す。
[!NOTE] トークン削減 ≠ 課金削減1:1。prompt caching 下では重複 context は約90%割引。
sqz stats --costはこれを正直にモデル化する。
ELI5: エージェントは毎回スーツケース(context window)を詰める。今は汚れ物——全 pass テスト、不変のgit status、重複読み——を詰め込む。sqz は畳んで重複を抜き、付箋を残す友人:「青シャツはもう入ってる、ポケット3を見て」。
圧縮するもの、しないもの#
圧縮する:
- Shell出力 — 12エコシステム45+フォーマッタ: git, cargo, npm/pnpm/yarn/bun, pytest, ruff, mypy, go test(
-json含む), docker/podman, kubectl, aws, terraform, gcloud, gradle, maven, xcodebuild, adb logcat, dotnet, gh, grep/rg, tree, curl等 - JSON — null除去、debug field 除外、flatten、配列集約、TOON符号化
- ログ — 反復行を集約(既定
max_repeated_lines = 3) - テスト出力 — Rust, Go, Python, JS, JVM用状態機械パーサで失敗のみ
触らない:
- ソース、スタックトレース、エラーメッセージ、secret → safe mode、圧縮0%
- プロンプトとモデル応答 → フレームワーク所有、sqz対象外
[!TIP] 全圧縮結果はバイト完全復元可能:
sqz expand <ref>。
数値#
単発圧縮(cargo test -p sqz-engine benchmarks):
| 内容 | 前 | 後 | 削減 |
|---|---|---|---|
| 反復ログ行 | 148 | 62 | 58% |
| 大 JSON 配列 | 259 | 142 | 45% |
| JSON API応答 | 64 | 53 | 17% |
| Git diff | 61 | 54 | 12% |
| 文章/docs | 124 | 121 | 2% |
| スタックトレース(safe) | 82 | 82 | 0% |
dedup 込みセッション(本領発揮):
| 繰り返し | sqzなし | sqzあり | 削減 |
|---|---|---|---|
不変git status再実行 | 155 | 13 | 92% |
| 200行中41-80行の再読 | 305 | 16 | 95% |
同一cargo test | 303 | 13 | 96% |
README例:
cat auth.py (500行): 4,000 token 4,000 token (ソースは全文)
cargo test (1失敗): 1,200 token 120 token (失敗+assertion+file:line)
sed -n '40,80p' auth.py: 330 token 18 token (§ref:…:L40-80§)
git status 不変: 160 token 13 token (§ref:…§)
───────────────────────────────────── ─────────────
合計: 5,690 token 4,151 token (27%節約, 欠落ゼロ)text著者の注意: 丸ごと再読は俗説より稀(92セッション542読で1回)。実際は不変コマンド出力、行範囲、小編集後再読——各々に専用参照型がある。
2分インストール#
# macOS / Linux (prebuilt, コンパイラ不要)
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh
# npm
npm install -g sqz-cli
# Homebrew
brew tap ojuschugh1/sqz
brew install sqz
# ソースから
cargo install sqz-cli sqz-mcpbash次に:
sqz init --global # 全プロジェクト (~/.claude/settings.json マージ)
# または
sqz init # このプロジェクトのみ
sqz init --only opencode,codex
sqz init --skip cursor,windsurf
sqz doctor # 検証: binary, DB, hook, 直近圧縮bash[!WARNING]
sqz initはopencode.jsoncをJSONパースしてコメントを落とす。保持したい場合は手動:sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts、そしてsqz-mcpエントリを手で追加。
フック前に試す: counterfactual replay#
Claude CodeやKiro済みなら transcript をローカル replay、アップロードなし:
sqz discover --replay
# Sessions replayed: 24
# Tool outputs: 43
# Tokens (original): 116,598 → compressed: 92,560
# Estimated avoidable: 24,038 tokens (20.6%)bash各セッションは使い捨てキャッシュで replay、セッション跨ぎ dedup で水増ししない。
CLI チートシート#
sqz compress "text" # または stdin pipe
sqz compress --no-cache # dedupなし全出力
sqz expand a1b2c3d4 # prefix一致、または §ref:…§ 貼付
sqz gain # 日次棒グラフ直近7日
sqz gain --days 30 --project . # 30日, 現プロジェクト
sqz stats # 累計 + regret信号
sqz stats --cost # prompt-cached課金での$
sqz stats --breakdown # コマンド別トークン消費
sqz recall "connection refused" # 圧縮済み全文 FTS5検索
sqz resume # compaction後 context再注入
sqz compact # 積極退避: --strategy keep_recent|keep_relevant|keep_errors
sqz vizit # htop風ライブダッシュ
sqz discover # 圧縮弱いコマンド発見bashdedup 回避(GLM 5.1等が§ref§でループ):
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1 # 全域無効
export SQZ_REF_TTL_SECS=300 # ref有効短縮 (既定1800, 0=無効)bash圧縮仕組み: 6段階#
- 専用フォーマッタ —
cargo testは失敗テスト+assertion+file:line保持。git statusは要約。未知は汎用へ——未圧縮ゼロ。 - 表圧縮 —
ps aux等の位置合わせ空白を2空白区切りに。厳格検出: indent行、コード、YAML、JSONは非一致。 - 構造要約 — コード→import+シグネチャ+コールグラフ(約70%減)。実装ノイズでなく構造を見せる。
- dedup キャッシュ — SHA-256、SQLite永続。同一バイト→13トークン
§ref:HASH§。既知ファイルの行範囲→§ref:HASH:L40-80§。小編集後再読→差分行のみ。ref寿命30分(SQZ_REF_TTL_SECS)、compactionでリセット。 - JSONパイプライン — null除去→debug除外→flatten→配列集約→TOON(可逆コンパクト)。
- Safe mode — エントロピー分析でトレース、secret、migration検出→圧縮0%パススルー。
遅延 sub-ms(p99 < 5ms〜100KB)、SQLite照会約0.1ms。LLM推論比で無視可能。
対応ツール#
| ツール | 統合 | 設定 |
|---|---|---|
| Claude Code / Cursor / Windsurf / Cline | PreToolUse hook (透過) | sqz init |
| Gemini CLI | BeforeTool hook | sqz init |
| Kiro | Steering + MCP | sqz init |
| OpenCode | TypeScript plugin | sqz init |
| Codex / Zed | AGENTS.md + MCP | sqz init |
| Copilot CLI | preToolUse hook | sqz init |
| Copilot coding agent (CI) | repo hook, 自己bootstrap | sqz init --ci + commit |
| 任意MCPサーバ | sqz-mcp proxy -- <server> | 結果+tools/list圧縮 |
| VS Code / JetBrains / Chrome / Firefox | 拡張 | Marketplace |
MCP proxy例:
{
"mcpServers": {
"github": {
"command": "sqz-mcp",
"args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}json--lazy-tools(1文説明+sqz_tool_help要求時全文——tools/listだけで10-40k燃やすサーバあり)、--no-desc、--no-cache。proxyはsqz_expandを注入し原文バイト復元。
正直な会計: cost と regret#
他が見ない2信号:
sqz stats --cost— prompt-cached課金での$(書込×1.25一回、読込×0.10毎ターン)。仮定は全表示、--price-in等で上書き可。保守的設計。- regret信号 — 速い再実行(2分内同一バイト再現=無駄)とref expand(
§ref§を戻した=全文要)。同一コマンド常連はフォーマッタ不備——issueへ。
arXiv:2607.12161 ↗の失敗を回避: 決定論+クエリ非依存(provider cache無効化なし)、新規出力のみ(履歴不改変)、pipe/redirect非横取り、16トークン net-win ゲートで割に合わない圧縮を skip。
実践: セッションに組込む#
# 1. 節約見込みを見る
sqz discover --replay
# 2. global導入
sqz init --global
sqz doctor
# 3. 普通に作業して計測
sqz gain
sqz stats --breakdown
# 4. 再実行より recall
sqz recall "Failed to connect"
sqz expand 3f9a1c05e2d84b17bashdirenvでプロジェクト別DB:
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"bashhook、stats/gain/expand、MCP全対応。親dir自動作成 mode 0700。
設定#
[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 = 200000tomlプライバシ#
テレメトリゼロ、クラッシュ報告なし、完全オフライン、エアギャップ可。統計は~/.sqz/sessions.db(SQLite FTS5)。外部送信なし。
使わない方がいい時#
- 監査用逐語ログ要——
--no-cacheやsafe経路、後でexpand。 - モデルが
§ref§解釈不可——dedup無効(SQZ_NO_DEDUP=1)。 - net-win下の微小出力——sqzが既に skip(16トークン閾値)。
結論#
sqz は正しい境界: ツール実行時。prompt書換えでもモデル別アダプタでもない。sqz init一発で全 framework、Rust決定論 core でp99 5ms未満、dedup で重複を13トークン参照に。
まずsqz discover --replay——自身 transcript で20%+回避可能なら hook 導入。