sqz

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

AI コーディングエージェント向けの、注入前コンテキスト圧縮とセッション重複排除

_{実際のセッション統計： 3,003 回の圧縮 · 178,442 トークンを削減 · 平均削減率 24.7% · モデルがすでに持っている出力では最大 92%}

ドキュメント · インストール · 仕組み · 対応ツール · MCP プロキシ · ベンチマーク · 変更履歴 · Discord

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

---

AI コーディングエージェントは、入力トークンの大半をツール出力に費やしています。ビルドログ、テスト実行結果、git status、編集のたびに読み直される同じファイルなどです。これらはすべて加工されずにコンテキストウィンドウへ入り、その後の各ターンでも再送されます。

sqz は、ツール出力がコンテキストに入る前に圧縮します。コマンドごとのフォーマッターは、エージェントが処理する情報（失敗したテスト、アサーション、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 バイナリで、決定論的に動作し、LLM の呼び出しはなく、オフラインでも使えます。圧縮された結果はすべて、sqz expand でバイト単位まで正確に復元できます。ただし、認証情報、スタックトレース、またはマイグレーションに言及する出力は、sqz がキャッシュしないため例外です。

メモ

名称の混同に関する注意： このリポジトリ ojuschugh1/sqz は独立したプロジェクトであり、同じような名前や動作のほかのツールや、「squeeze」を短縮するほかの圧縮プロジェクトとは無関係です。crates.io、npm、PyPI、または Homebrew から sqz / sqz-cli / sqz-mcp をインストールした場合、それはこのリポジトリのものです。

トークンの削減量

実際の圧縮 3,003 件で平均 24.7% 削減 · モデルがすでに保持している出力には 13 トークンの参照 · 品質ベンチマークでエージェントに不可欠な事実を 100% 保持 · ソースコード、スタックトレース、認証情報を含む行は 0% 削減

ある開発者の 1 週間分を、実際の 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/ のフィクスチャを使って測定しました。エージェントが目にするすべて（参照と、stderr に出力される sqz の 1 行の注記）の cl100k トークン数です。

繰り返し	sqz なし	sqz あり	削減率
変更のない git status を再実行	166	37	78%
先に読み込んだ 200 行のファイルの 41-80 行	260	35	87%
変更のない同じ cargo test 出力	366	39	89%

実際に何が繰り返されるのかについて、少し説明します。あるユーザーが自身の Claude Code セッションを 92 件調べた結果（スクリプト）、ファイル全体の再読み込みが完全に同一だったのは 542 回中 1 回で、行範囲の再読み込みは 8.4% でした。そのため、sqz は「同じファイルを 5 回読む」ことを主なユースケースとはしていません。実際に起きる繰り返しは、変更のないコマンド出力、すでに読み込んだファイルの行範囲、小さな編集後のファイルの再読み込みです。それぞれに専用の参照タイプがあります（詳細）。出力量の多いコマンドや、コマンドを繰り返し実行するセッションで、最も大きな効果が得られます。

インストール

ビルド済みバイナリ（コンパイラー不要 — すべてのプラットフォームで動作します）：

# 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 Command Line Tools（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 のスコープ表におけるユーザースコープです）。そのため、このマシン上のすべての Claude Code セッションで sqz フックが実行されます。初回インストールでは、通常この方法を使います。~/.claude/settings.json にある既存の permissions、env、statusLine、および無関係なフックは保持されます。sqz は上書きせず、自身の項目をマージします。 追加されるのは自身のフックと、Bash(set -o pipefail) および Bash(sqz compress --cmd *) の 2 つの許可ルールです。これらが対象とするのは、書き換えによって追加される部分のみです。 sqz がコマンドを許可することはありません。引き続き、独自の権限ルールによって判断されます。 書き換えられたコマンドの実行前に Claude Code が確認を求める場合や、コマンドを拒否する場合、そのメッセージには書き換え後のコマンドが引用されます。たとえば、git tag v0 に対しては set -o pipefail; git tag v0 2>&1 のように表示されます。

~/.claude/settings.json にすでに sqz フックがある場合は、プロジェクトスコープの通常の sqz init を使うと、sqz を 1 つのリポジトリ内でのみ有効にできます。フックはすべてのプロジェクトで実行されるため、プロジェクトファイルには追加されません。

インストール後、sqz doctor はバイナリ、データベース、シェルフック、検出されたクライアントと実際に sqz 経由で実行されるクライアント、直近に圧縮が行われたかどうかを含む一連の設定を確認し、見つかった問題ごとに修正方法を表示します。sqz doctor --fix はそれらの問題を修正します。sqz のアップグレード後に一度実行してください。古いバージョンが書き込んだフックやガイダンスを最新の状態にし、現在の sqz が使用しなくなったフックファイルと、~/.claude/settings.json にすでにあるフックのプロジェクト内コピーを削除します。また、sqz バイナリが見つからないフックの参照先を実行中のバイナリに変更し、別の sqz バイナリを実行するフックがあれば通知します。sqz uninstall は sqz 独自の項目のみを削除し、他に何も残っていない場合に限りファイルを削除して、最後に保持したファイルを一覧表示します。プロンプトに応答するターミナルがない場合は、sqz reset と同様に --yes が必要です。

フックをインストールする前に、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 では、シェル行はフックが独自に書き換えるコマンドとスキップするコマンドに分かれます。2 番目の合計は、エージェントがシェル出力を sqz compress 経由でパイプし、sqz MCP ツールでファイルを読み取り（ロスレスなので繰り返しのみカウントされます）、sqz-mcp proxy の背後で MCP サーバーを実行することを前提としており、レポートにはそのうちどれだけがプロキシによる初回パスでの長い文字列と配列の切り詰めであるかが記載されます。Web フェッチ、編集、サブエージェントの結果はどのクライアントでも到達不能であり、再生されずにカウントされます。

これは ~/.claude/projects と ~/.kiro/sessions（Kiro CLI と IDE）をスキャンします。または --transcripts PATH で任意の場所を指定できます。各トランスクリプトは新しく使い捨てのキャッシュに対して再生されるため、重複排除の参照がセッションをまたぐように見えることはありません。また、レポートに「推定」と記載されるのは、まさにそのとおりだからです。これらの出力はその時点では圧縮されていませんでした。

1 つのエージェントしか使用していませんか? --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 は、sqz エントリをマージするために設定ファイルを JSON パーサー経由でラウンドトリップするため、opencode.jsonc（および他のツールが受け入れる、コメント付き JSON の類似ファイル）内のコメントが失われます。設定に注意深くコメントを付けており、それを保持したい場合は、代わりに手動でインストールしてください。

OpenCode — 2 ステップ:

1. プラグインファイルを所定の場所に配置します。sqz は生成された TS を stdout に出力するので、パスのエスケープ処理を自分で書く必要はありません:

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

2. 既存の opencode.jsonc に MCP エントリを自分で追加します。このブロックをトップレベルの 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 がフックをインストールし、シェルコマンドを書き換えて、その出力が AI ツールに届く前に sqz を経由するようにします。アドバイザリー型のクライアントでは、エージェントに対し、出力を sqz compress にパイプするか、sqz MCP ツールを使うよう指示します。以下の表に、各クライアントのティアを示します。

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

圧縮されるもの：

• シェル出力：コマンドごとのフォーマッター（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 ブロック、認証情報の行：安全モードに振り分けられ、サイズにかかわらず変更せずに渡され、キャッシュされることもありません。シェルフックでは、コマンドごとのフォーマッターがテスト実行の残りの部分を要約する場合があります
• プロンプトと AI の応答 — sqz ではなく、AI ツールが制御します

対応ツール

ツール	統合	セットアップ
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	~/.copilot が存在する場合、preToolUse フック（透過的）	sqz init
Copilot コーディングエージェント（CI）	リポジトリレベルのフック。クラウドサンドボックス内で自己ブートストラップします	sqz init --ci + コミット
任意の CI パイプライン	setup-sqz アクション — LLM のステップ前にログを圧縮します	uses: ojuschugh1/setup-sqz@v1
任意の MCP サーバー	sqz-mcp proxy でラップし、ツールの結果を圧縮します	下記を参照
VS Code	拡張機能	Marketplace からインストール
JetBrains	プラグイン	Marketplace からインストール
Chrome	ブラウザー拡張機能	ChatGPT、Claude.ai、Gemini、Grok、Perplexity
Firefox	ブラウザー拡張機能	同じサイト

透過的なクライアントには、シェルコマンドを自動的に sqz 経由でルーティングするフックがあります。アドバイザリー型のクライアントでは、エージェントが出力を sqz compress にパイプするか、sqz MCP ツールを呼び出した場合にのみ、sqz によってトークンを節約できます。クライアント組み込みのシェルツールやファイルツールは、sqz を経由しません。sqz doctor で各クライアントのティアを確認できます。

あらゆる MCP サーバーを圧縮

sqz-mcp proxy はエージェントと任意の stdio MCP サーバーの間に入り、返される内容を圧縮します。ツールの結果は sqz の全パイプラインを通り（繰り返し出現する内容は参照を重複排除し、スタックトレースやシークレットにはセーフモードを適用し、エラー結果は変更しません）、冗長なツールの説明は短縮されるため、tools/list がコンテキストウィンドウを圧迫しなくなります。プロキシは sqz_expand ツールを挿入するので、エージェントはキャッシュされた元の内容をバイト単位で正確に復元できます。認証情報、スタックトレース、またはマイグレーションに言及する結果はキャッシュされません。

MCP 設定でコマンドの先頭に付けると、サーバーをラップできます。

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

フラグ：--lazy-tools はすべてのツールの説明を1文に短縮し、必要に応じて元のドキュメント全文を提供する sqz_tool_help ツールを挿入します（一部の MCP サーバーでは tools/list だけで 10～40k トークンを消費します）。--no-desc は説明をそのまま保持します。--no-cache は何も保存しないため、重複排除の参照を送信せず、sqz_expand ツールも追加しません。クライアントからは通常の MCP サーバーとして認識されるため、あらゆる MCP クライアント（Claude Code、Cursor、Windsurf、Zed、Codex、Kiro、…）で動作します。サーバー独自の 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 が同じ内容を2回検出すると、全文の代わりにコンパクトな §ref:HASH§ トークンを返します。ほとんどのモデルでは問題なく処理できますが、一部のモデル（例：GLM 5.1）は参照形式を解析できず、ループすることがあります。回避策は4つあります。

# 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）にインデックス化され、外部に送信されることはありません。エージェントがコンテキストを圧縮し、1時間前のエラーメッセージを失った場合、コマンドを再実行する代わりに検索できます。

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

エージェントには、同じ機能が sqz_recall MCP ツールとして提供されます。

独自の削減量を追跡

シェルでいつでも sqz gain を実行すると、日ごとの内訳を確認できます（出力例については上記の「トークン削減」セクションを参照してください）。累積レポート全体を確認するには 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 を追加すると、どのコマンドが最も多くのトークンを消費しているかを正確に確認できます。

$ 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 トークン数を集計します。長い区切り線のように、同じ文字種が2 KBを超えて連続する場合は、2 KB単位でカウントされます。そのため、約1％に加えて4トークン程度の誤差が生じることがあります。

正直なコストと後悔の評価

トークンの削減が、そのまま請求コストの削減につながるとは限りません。プロバイダーのプロンプトキャッシュを利用すると、コンテキストの大部分は約90％割引で再送されます。また、エージェントが必要としていた情報を削る圧縮は、代わりに余分なターンを必要とします （arXiv:2607.12161）。sqzは曖昧な説明で済ませず、両面を測定します。

• sqz stats --cost は、プロンプトキャッシュを利用した課金モデル（キャッシュへの書き込みは1回あたり×1.25、以降の各ターンでのキャッシュ読み取りは×0.10）に基づいて、節約額をドルで推定します。すべての前提は表示され、変更も可能です（--price-in、--reread-turns、--cache-write-mult、--cache-read-mult）。これは保守的な推定です。キャッシュを利用しない場合、同じ節約量でも、各ターンで入力料金の全額が請求されます。
• sqz stats は、後悔を示すシグナルを報告します。すばやい再実行（エージェントが2分以内にバイト単位で同一の出力を再生成した場合。繰り返しても何も得られていません。Claude CodeのPostToolUseフックは参照を返さないため、その繰り返しは通常の圧縮としてカウントされます）と、参照の展開（元のバイト列に復元された§ref§トークン）です。どちらも「圧縮によって、モデルが必要としていた情報が削られた」ことを示す指標です。特定のコマンドが何度も現れる場合は、そのフォーマッターの改善が必要です。問題を報告してください。

sqzの設計では、調査で測定された失敗パターンをすでに回避しています。圧縮は決定論的でクエリに依存しないため（プロバイダーのプロンプトキャッシュが無効になることはありません）、新しいツール出力だけを対象とし（履歴を書き換えることはありません）、後続の出力を伴うコマンド、サーバーを実行するコマンド、バックグラウンドでジョブを実行するコマンドはそのまま残します（Claude Codeでバイパスモード以外の場合、PreToolUseフックはパイプライン、ループ、ヒアドキュメントを記述どおりに維持し、PostToolUseフックは正常終了後にその出力を圧縮します）。コマンドをまとめたリストやパイプライン（Gemini CLI、Copilot CLI、バイパスモードのClaude Code）では、コマンドごとのフォーマッターをスキップします。また、16トークンの純増益ゲートにより、マーカー自体のコストを回収できない圧縮もスキップします。書き換えによって元のコマンドとは異なるコマンド群が実行される可能性がある場合も、コマンドは記述どおりに維持されます。ls ${DEST:?}; echo nextでは、lsだけをパイプにつなぐと、展開の失敗でシェルが停止した後に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

統計情報は~/.sqz/sessions.dbのSQLiteにローカル保存され、マシンの外部に送信されることはありません。

圧縮の仕組み

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
   クラウド	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 など）の列が揃った出力は、連続する余白が2つのスペース区切りに圧縮されます。検出条件は厳格で、インデントされた行、コード、YAML、JSON は対象になりません。

3. 構造的な要約：エンジンには、コードファイルをインポート、関数シグネチャ、呼び出しグラフに縮約する API があります。フックと MCP の経路ではこれを使用せず、ソースを完全な形で提供します。

4. 重複排除キャッシュ：SHA-256 のコンテンツハッシュを使用し、セッションをまたいで保持されます。モデルがすでに持っているものとバイト単位で同一の出力は、13トークンの参照になります。モデルがすでに完全な形で持っているファイルの行範囲（sed -n '40,80p'、offset／limit を指定した sqz_read_file）は §ref:HASH:L40-80§ になります。小さな編集後の再読み込みでは、sqz MCP ツールを通じて、変更された行とその両側にある変更されていない行を1行ずつ返します（シェルフックは編集後のファイルを再送信します）。ファイル全体にわたる編集の場合は、ファイル全体が返されます。参照が提供されるのは、元の内容がまだコンテキスト内にある間（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 コードだけが除去されます。また、これらはキャッシュされません。シェルフックでは、コマンドごとのフォーマッターが先に実行されます。要約の対象となるのは、該当する内容を含む各段落のすべての行を変更せずに保持できる場合だけです。そのため、トレースを含むテスト実行の残りの部分は要約されることがあります。それ以外の場合は、出力全体がそのまま通過します。これらの構造の外でパスワード、キー、トレース、マイグレーションに言及するだけの出力は通常どおり圧縮されますが、キャッシュされません。そのため、非可逆の処理段階で削除された内容は復元できません。

いずれかの段階で panic が発生した場合、sqz compress は入力を変更せずに出力し、stderr に1行を出力して、コマンドの終了ステータスを維持します。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 が永続化するすべてのデータ（統計、重複排除キャッシュ、セッション）は、デフォルトで 1 つの SQLite ファイル ~/.sqz/sessions.db に保存されます。プロジェクトごとに分けるには、SQZ_DB_PATH を設定してください。

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

すべての機能でこの設定が適用されます。シェルフック、sqz stats／gain／expand、MCP サーバー（MCP 設定の env に設定してください）が対象です。絶対パスを推奨します。相対パスは、プロセスの実行ディレクトリを基準に解決されます。親ディレクトリが存在しない場合は作成されます（~/.sqz と同様にモード 0700）。

プライバシー

• テレメトリーは一切ありません。データ送信やクラッシュレポートもありません
• 完全にオフラインで動作し、エアギャップ環境でも利用できます
• すべての処理はローカルで行われます

開発

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

ライセンス

sqz は、Apache License, Version 2.0 または MIT license のいずれかを、選択に応じて適用できます。

Copyright 2026 Ojus Chugh

2.0.0 までのリリースは、Elastic License 2.0 のもとで公開されていました。

貢献は、Contributor License Agreement に基づいて受け付けています。

リンク

• ドキュメント一覧
• AI コーディングエージェントが同じファイルを再読み込みするのを防ぐ方法
• MCP コンテキスト圧縮
• 品質ベンチマーク：圧縮率と情報保持の比較
• コンテキスト劣化とコンテキスト圧縮
• コンテキスト圧縮方式の選び方
• ホワイトペーパー：注入前のコンテキスト圧縮
• トークン削減ベンチマーク
• Discord
• 変更履歴
• MCP Registry 名：mcp-name: io.github.ojuschugh1/sqz

スター履歴

今日 sqz でトークンを節約できたなら、スターを付けると、ほかの人にも見つけてもらいやすくなります。共有したい場合は、sqz stats --share でご自身の数値を表示できます。

コントリビューター

コード、修正、アイデアを sqz に提供してくださった皆さんに感謝します。

修正のきっかけとなる詳細なバグレポートを送ってくださった皆さんにも感謝します。正確な再現手順は、リリースのたびにこのプロジェクトをより良くしてくれます。参加してみませんか？PR は迅速にレビューされます。まずは未解決の issueをご覧ください。

_{コントリビューター一覧は contrib.rocks で作成しました。}