distil

claude mcp add distil -- npx -y @munhq/distil

アカウントも API キーも設定も不要です。このパッケージは、プラットフォームに対応したバイナリを取得し、公開済みのチェックサムと照合する小さなラッパーです。Node を使わない場合に備えて、install.sh とビルド済みバイナリも用意しています。

---

キャッシュ書き込みはトークンの2％、請求額の28％です

これは主張ではなく、実測値です。実際のエージェントセッション13,814件、アシスタントのターン410,742件を、2026-08-29に再実行しました。リクエストのたびに履歴全体が再送されるため、そこに含まれる一意なトークンはそれぞれ550回課金されていました。

つまり、明白に思える対策である「履歴の圧縮」は、たいてい間違いです。履歴を編集すると、編集箇所以降のキャッシュ済みプレフィックスが無効になり、0.1倍の読み取りが1.25倍または2.0倍の書き込みに変わります。コンテキストのコストは、圧縮しても解消できません。トークンを取り込まないようにするしかありません。

この分野のツールはどれも、独自のテスト用データで測定した削減率を公表しています。しかし、実際のセッションのうちどれだけに手を加えられるのか、また、プロンプトキャッシュの料金を適用したときにその割合がどれだけのコストになるのかという分母は、どのツールも公表していません。distil は、エージェントが実際に作成したトランスクリプトを使って、その両方を測定します。

既存の成果と、そうでないもの。 以下のキャッシュ計算は新たな発見ではありません。Anthropic のコンテキスト編集のドキュメントには、ツールの結果を消去するとキャッシュ済みプレフィックスが無効になると記載されており、消去による効果がコストに見合うだけの大きさである場合にのみ実行するための clear_at_least も用意されています。損益分岐点のルールも公開されています。5分間のキャッシュでは、消去したトークン数に次の消去までのリクエスト数を掛けた値が、保持するトークン数の11.5倍を超える必要があります。この README の表は、このルールをそのまま再現しています。独立して導出しましたが、これは計算の検証であり、新たな貢献ではありません。

不足しているのは実測データです。どの情報源も、自分のワークロードで調整するよう勧めていますが、そのための手段を提供しているものも、実際の測定値を公表しているものもありません。このクレートは、そのギャップを埋めるためのものです。clear_at_least の値を選ぶため、あるいは一切消去しないと決めるために必要な数値を測定します。

測定結果の全容

2026-08-29 に、ローカルの Claude Code トランスクリプト 13,814 件を対象に測定しました — アシスタントのターン数は 410,742 回、重複を除いたテキストは 212.7M トークンです。distil-bench ~/.claude/projects を使えば、ご自身のコーパスでも再現できます。コーパスは増えていくため、小数点以下の数値より測定日が重要です。

	トークン数	割合
ツールの結果	127,371,430	59.9%
ツール呼び出し	38,065,121	17.9%
ユーザーテキスト	29,818,536	14.0%
アシスタントのテキスト	15,402,077	7.2%
思考	2,076,716	1.0%

この重複を除いた 212.7M トークンに対し、請求対象となった入力トークンは 116.9 billion でした — リクエストのたびに履歴全体を再送するため、各トークンは 550 回分の料金が発生しました。

実際のキャッシュ倍率（読み取りは 0.1x、5 分の TTL の書き込みは 1.25x、1 時間の TTL の書き込みは 2.0x）を適用すると、次のようになります。

	トークンの割合	コストの割合
キャッシュ読み取り	97.9%	71.8%
キャッシュ書き込み	2.0%	27.6%

キャッシュ書き込みはトークンの 2% を占める一方、請求額の 28% を占めます。 履歴を編集すると、編集箇所以降のキャッシュされたプレフィックスが無効になり、0.1x の読み取りが 1.25x または 2.0x の書き込みに変わります。そのため、書き換えによって無効化される範囲を次の値より小さくする必要があります。

残りのターン数	5m TTL	1h TTL
1	8.0%	5.0%
10	46.5%	34.5%
20	63.5%	51.3%
100	89.7%	84.0%

この表は、別の形で示した公開済みの損益分岐ルールです。どの行でも、5 分のティアでは cleared x turns / kept が 11.5 になります。この値を使って clear_at_least を選び、distil-bench を使って設定すべきターン数と末尾のサイズを見つけてください。これらはワークロードの特性であり、公開されている情報がほとんどない部分です。

履歴の単位ごとに見ると、残り 10 ターンの場合、そのまま保持するコストは 1.00、圧縮するコストは 2.15、最初から取り込まないコストは 0 です。コンテキストのコストから逃れるために圧縮することはできません。トークンを取り込まない選択だけが可能です。

このクレートを使う際の意味

履歴に触れないレイヤーは、この計算上有利です。CacheAlignLayer（安定したプレフィックスがキャッシュ可能な状態に保たれるよう、コンテンツを並べ替えます）と ScratchpadLayer（作業状態をウィンドウの外部に保持します）が該当します。

履歴を書き換えるレイヤー — MaskingLayer、SummarizationLayer、CompactionLayer — は、一般的なケースでは節約できる額よりもコストがかかります。これらを使うのは、コンテキストのオーバーフローという、ほかの選択肢ではリクエストが失敗し、キャッシュ料金との比較が意味をなさなくなる場面に限ってください。BudgetLayer は、まさにその場面のためにあります。

RegistryLayer と CodeModeLayer は、同じ機能を標準でより優れた形で実現する Anthropic の Tool Search Tool および Programmatic Tool Calling よりも前に作られたものです。標準機能を優先してください。

古いツールの結果をクリアする場合は、MaskingLayer よりもプロバイダーの clear_tool_uses コンテキスト編集を優先してください。これはサーバー側で実行され、clear_at_least を受け取り、依存関係を追加せずに API パラメーター 1 つで実現できます。API で提供されない動作が必要な場合に限り、ここでレイヤーを使ってください。

測定

cargo build --features bench --release

# Where tokens are, what they cost, and the break-even table
./target/release/distil-bench ~/.claude/projects --json baseline.json

# Sessions that called a given tool, against those that did not
./target/release/distil-bench ~/.claude/projects --split-by-tool mcp__codeindex__

# Export real traffic so other compressors run on the same input
./target/release/distil-bench ~/.claude/projects --export-sessions ./sessions --min-turns 40

外部ツールとの比較、公平性のルール、最初に誤った数値を生み出した 2 つのハーネスのミスについては、bench/README.md を参照してください。

保持

元のコンテキストで答えられた質問にモデルが引き続き答えられる場合に限り、その節約には意味があります。

# No LLM judge: file paths checked against ground truth from the transcript
python bench/artifact_retention.py ./sessions 12

# LLM-graded probes (recall / artifact / continuation / decision)
cargo build --features probe --release
./target/release/distil-probe <session.jsonl> --probes 6 --model qwen2.5:3b

プローブの分類体系は Factory.ai のものです。同社の記事では分類体系が定義されていますが、ハーネスは提供されていません。判定には Completer を使い、Summarizer は使いません — Summarizer は要約を前提とした枠組みを持ち込む可能性があり、プローブの形式と採点指示の両方を書き換えてしまうためです。

ライブラリーとして使う

use distil::{CacheAlignLayer, Ctx, EstimateCounter, Pipeline};

let pipeline = Pipeline::builder()
    .counter(EstimateCounter)
    .layer(CacheAlignLayer::generic())
    .build();

let mut ctx = Ctx::new(messages, tools, turn);
let result = pipeline.optimize(&mut ctx);
println!("{result}");

この例はコンパイル可能な状態で examples/readme_quickstart.rs に保存されています — cargo run --example readme_quickstart で実行できます。

すべてのレイヤーが Layer を実装し、tokens_before、tokens_after、詳細行を報告するため、それぞれを個別に測定できます。

機能

機能	追加される内容
corpus	トランスクリプトローダー（追加の依存関係なし）
bench	distil-bench。tiktoken が必要です
probe	distil-probe。HTTP 判定には proxy が必要です
tiktoken	chars/3.5 による推定ではなく、正確な BPE カウント
proxy	distil-proxy HTTP サーバー
mcp	distil-mcp MCP サーバー
metrics	Prometheus /metrics

インストール

./install.sh                       # binaries, the skill, and the MCP server
/plugin marketplace add munhq/distil
/plugin install distil             # Claude Code: skill and server in one step

install.sh は両方のバイナリをインストールし、見つかったすべての Claude ホームにスキルを配置し、ユーザースコープで MCP サーバーを登録します。プラグインがすでにインストールされている場合は、プラグインがサーバーを宣言し、スキルも同梱しているため、バイナリのみをインストールします。

プラグインは npx -y @munhq/distil を使ってサーバーを起動するため、Node が必要です。プラグイン相対パスは使用できません。Claude Code は ${CLAUDE_PLUGIN_ROOT} を展開しますが、それ以外のクライアントは展開しないため、プラグインでこのパスを宣言すると、ほかのすべてのクライアントには存在しないリテラルパスが渡されます。Node がない場合に備えて、install.sh とビルド済みバイナリも引き続き提供しています。

プラットフォームのサポート

プラットフォーム	バイナリ	スクリプト
Linux x86_64 / arm64	リリース済み、テスト済み	対応
macOS x86_64 / arm64	リリース済み、CI でビルド	対応
Windows x86_64 / arm64	リリース済み、CI でビルド	シェルが必要：Git Bash、MSYS2、または WSL

リリースでは 6 つのターゲットを公開しており、plugin/test_platform.sh はインストーラーとプラグインランチャーの両方をこのマトリクスに照らして検証するため、アセット名と要求される名前が食い違うことはありません。install.sh とランチャーは bash スクリプトのため、Windows ではシェルが必要です。cmd と PowerShell では実行できません。Linux バイナリは静的 musl ビルドのため、対応する glibc は必要ありません。

注意事項

コーパスは、ある開発者のマシンに由来するものです。発見されたのは比率であり、絶対的な合計値は個人のものです。カウントには cl100k_base を使用しており、Claude のトークナイザーを数パーセント以内で近似します。損益分岐モデルはキャッシュのブレークポイントが 1 つだけだと仮定しているため、末尾部分だけを書き換える場合のコストは表の値より小さくなります。これは精度を高めるものですが、結論を覆すものではありません。

コントリビューション

ビルドとテストの手順、ベンチマークの変更時に守るべきルール、レビュー前にプルリクエストで必要な内容については、CONTRIBUTING.md を参照してください。脆弱性は非公開で報告してください — SECURITY.md。

ライセンス

MIT。詳しくは LICENSE を参照してください。