blog.dopana

戻る

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を見て」。

git, cargo, pytest, docker...未知あり, context内なしはいいいえエージェントのツール呼び出し:git status, cargo test, catsqz PreToolUse hook専用フォーマッタあり?失敗, assertion, file:line を保持。ノイズ削除汎用パイプライン: 反復集約, 表圧縮既見? SHA-256 照会13トークン §ref:HASH§ を返すスタックトレース / secret /migration?Safe mode: 圧縮0%, パススルー圧縮出力をモデルへ

圧縮するもの、しないもの#

圧縮する:

  • 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):

内容前後削減
反復ログ行1486258%
大 JSON 配列25914245%
JSON API応答645317%
Git diff615412%
文章/docs1241212%
スタックトレース(safe)82820%

dedup 込みセッション(本領発揮):

繰り返しsqzなしsqzあり削減
不変git status再実行1551392%
200行中41-80行の再読3051695%
同一cargo test3031396%

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分インストール#

install.sh
# 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-mcp
bash

次に:

init
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、アップロードなし:

discover
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 チートシート#

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                   # 圧縮弱いコマンド発見
bash

dedup 回避(GLM 5.1等が§ref§でループ):

dedup-off
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1          # 全域無効
export SQZ_REF_TTL_SECS=300    # ref有効短縮 (既定1800, 0=無効)
bash

圧縮仕組み: 6段階#

  1. 専用フォーマッタ — cargo testは失敗テスト+assertion+file:line保持。git statusは要約。未知は汎用へ——未圧縮ゼロ。
  2. 表圧縮 — ps aux等の位置合わせ空白を2空白区切りに。厳格検出: indent行、コード、YAML、JSONは非一致。
  3. 構造要約 — コード→import+シグネチャ+コールグラフ(約70%減)。実装ノイズでなく構造を見せる。
  4. dedup キャッシュ — SHA-256、SQLite永続。同一バイト→13トークン§ref:HASH§。既知ファイルの行範囲→§ref:HASH:L40-80§。小編集後再読→差分行のみ。ref寿命30分(SQZ_REF_TTL_SECS)、compactionでリセット。
  5. JSONパイプライン — null除去→debug除外→flatten→配列集約→TOON(可逆コンパクト)。
  6. Safe mode — エントロピー分析でトレース、secret、migration検出→圧縮0%パススルー。

遅延 sub-ms(p99 < 5ms〜100KB)、SQLite照会約0.1ms。LLM推論比で無視可能。

対応ツール#

ツール統合設定
Claude Code / Cursor / Windsurf / ClinePreToolUse hook (透過)sqz init
Gemini CLIBeforeTool hooksqz init
KiroSteering + MCPsqz init
OpenCodeTypeScript pluginsqz init
Codex / ZedAGENTS.md + MCPsqz init
Copilot CLIpreToolUse hooksqz init
Copilot coding agent (CI)repo hook, 自己bootstrapsqz init --ci + commit
任意MCPサーバsqz-mcp proxy -- <server>結果+tools/list圧縮
VS Code / JetBrains / Chrome / Firefox拡張Marketplace

MCP proxy例:

mcp.json
{
  "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。

実践: セッションに組込む#

session
# 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 3f9a1c05e2d84b17
bash

direnvでプロジェクト別DB:

.envrc
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"
bash

hook、stats/gain/expand、MCP全対応。親dir自動作成 mode 0700。

設定#

~/.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
toml

プライバシ#

テレメトリゼロ、クラッシュ報告なし、完全オフライン、エアギャップ可。統計は~/.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 導入。

参考文献#