headroom は LLM にコンテキストを送る前に、その中身を圧縮してくれるミドルウェア（処理の間に挟まる中間層）だ。ツール出力・ログ・ファイル・RAG の検索結果・会話履歴みたいに、プロンプトに積まれて膨らみがちなテキストを手前で削ってくれる
仕組みはシンプルで、まず ContentRouter が「これは何のデータか」を型判定する。それから JSON なら JSON 用、コードならコード用、と専用の圧縮器に振り分けてから縮める
可逆性も用意されてて、原本はローカルに保持される。LLM が「ここ元の全文が欲しい」となったら headroom_retrieve で取り戻せるようになってる。つまり消すんじゃなく、いったん畳んで必要なら戻せる仕組みだね
要するに、Claude や GPT に渡す手前で長いテキストを賢く間引いてくれる中継ぎ、と思えばいい
X で毎日 AI 情報を配信してるコムテです。Claude Code テクニックを配信しています
今回は headroom を実際に Claude Code 環境に入れて、自分の手元でトークン数を計測してみた。結論から言うと、効くデータと効かないデータがはっきり分かれた。何でも縮むツールじゃないっていうのが正直なところ
ぶっちゃけ、万人向けの「とりあえず入れとけ」ツールではないかな。トークン爆食いの自覚があるエージェント運用者が、自分の数字で確かめて入れる道具
仕組み
中身をもう少し分解しておく。headroom の処理はざっくり 型判定 → 専用圧縮 → 可逆保存 の流れで、実際は KV キャッシュのプレフィックスを揃える CacheAligner なんかも前段に噛んでる
中心になるのが ContentRouter で、これがデータの型を見分ける。次に型ごとの専用圧縮器に流す。ここが headroom の肝になる部分だ
| 圧縮器 | 担当するデータ |
|---|---|
| SmartCrusher | 構造化された JSON |
| CodeCompressor | AST（構文木）対応のコード |
| Kompress-base | 学習モデルによる汎用圧縮 |
最後に CCR が復元性を担保する。LLM に渡す圧縮ペイロード自体は情報が間引かれてる（lossy）。ただし原本はローカルにそのまま残ってて、LLM が必要になったら headroom_retrieve で完全復元できる。畳んだ表現を渡しつつ元データは手元に温存する、という二段構えになってる
Claude Codeへの組み込み方
導入はかなり手軽な部類だ。一番ラクなのは headroom wrap claude のワンコマンドで、Claude Code を headroom 越しに起動するやり方
もう一つは proxy（中継サーバー）を headroom proxy --port 8787 で立てて、Claude Code の ANTHROPIC_BASE_URL をそのポートに向けるパターン。これならコード側を一切いじらずに差し替えできる。ゼロコードで挟めるのは地味に強い
headroom wrap claude一発でラップ- proxy 経由なら
headroom proxyを立ててANTHROPIC_BASE_URLを向けるだけ - MCP として入れるなら
headroom mcp install - SDK ラッパーは Anthropic / OpenAI / Vercel AI SDK / LangChain 対応
選択肢が広いから、自分のスタックに合わせて挟み方を選べるのがいい
proxy を挟むと、全プロンプトとツール出力がローカルの proxy・CCR ストアを通る。原本がローカルに残る local-first 設計だから外部送信はないけど、機密を扱うなら原本ストアの置き場所と権限だけは把握しておきたい
proxy や wrap を使うには fastapi などの extras が要る。pip install "headroom-ai[all]" で全部入れるのが無難。実際に自分が base 単体で入れたら、CLI が fastapi 不足で動かなかった。試すときは最初から [all] 推奨
実際にインストールして計測した
ここからが本題で、/tmp に隔離した venv（独立した Python 環境）を作って計測した。インストールは pip install "headroom-ai[all]"。Python 3.10+ か TypeScript、圧縮エンジンの一部は Rust 実装、ライセンスは Apache 2.0。作者は Tejas Chopra で英語圏の OSS だね
計測は最小呼び出しの one-liner でやった。compress を呼んで前後のトークン数を比べるだけのシンプルな構成
まず構造化 JSON のツール出力。コード検索100件を想定したデータを食わせた
| 項目 | 値 |
|---|---|
| 圧縮前 | 11,570 トークン |
| 圧縮後 | 6,414 トークン |
| 削減率 | 44.6% |
| ウォーム時のレイテンシ | 約100ms |
これは SmartCrusher が効いた結果だ。構造化された JSON は型がはっきりしてるぶん、専用圧縮器がガツンと刺さる。44.6% は素直にでかい
それで次が問題で、冗長なビルドログ400行を食わせたら削減率は 0% だった。デフォルトの compress() では一切縮まなかったってこと
0% のとき裏で何が起きてたかというと、Kompress-base の初回ロードに約75秒かかってた。さらに HF（Hugging Face）認証なしの警告も出てた。テキストモデルは初回のモデル読み込みが重いから、初手はもっさりする
つまり、構造がはっきりしたデータには劇的に効くけど、素の冗長テキストには最小呼び出しだと無風、という結果だった
作者ベンチと自分の結果のズレ
ここで気になるのが、作者が出してるベンチとの差だ。先に言っておくと、以下の数字は全部 作者ベンチ・ワークロード依存の値で、自分の 0% とは前提条件が違う
| ワークロード | 作者ベンチの圧縮率 |
|---|---|
| コード検索 | 92% |
| SRE | 92% |
| issue triage | 73% |
| コードベース探索 | 47% |
精度面も出てて、作者ベンチではベースライン比で GSM8K が同等、TruthfulQA はむしろ微増、SQuAD は19%圧縮時で97%を保ってる、とされてる。python -m headroom.evals suite --tier 1 で再現できるらしい
じゃあなんで自分のログは 0% だったか。これは欠陥じゃなくて条件の違いだと見てる。自分がやったのはライブラリ最小呼び出しの compress one-liner で、作者ベンチは proxy / wrap のフル構成での測定
つまり同じ headroom でも、最小呼び出しとフル構成では振る舞いが変わる。ログ系を縮めたいならフル構成で適切な圧縮器に乗せる必要がありそう、ということ。ここは自分がフル構成まで測ってないから、断定じゃなく推測として置いておく
レイテンシも正直に書いておく。ウォーム時で 15〜200ms くらい、テキストモデルの初回ロードはもっとかかる（自分の計測で約75秒）。常時挟むなら、このウォームアップ込みで考えたほうがいい
構造化データなら 44.6%、作者ベンチでは最大92%。LLM に渡す表現は間引かれるけど、原本はローカルに残るから必要なら headroom_retrieve で完全復元できる。圧縮の前提を理解して使えば、コンテキスト節約の効果はちゃんと出るツールだ
どういう人に向くか
総合すると、headroom は「何でも縮む魔法」じゃなくて「型のハマるワークロードで効く道具」だ。向き不向きをまとめておく
- 向く ツール出力や RAG 結果など構造化 JSON を大量に積む人
- 向く コード検索・SRE・issue triage 系の定型データを扱う人
- 微妙 素の冗長ログを最小呼び出しでサクッと縮めたい人
- 微妙 初回75秒のウォームアップを許容できない短時間用途
Claude Code でコンテキスト上限と戦ってるなら、proxy か wrap で挟んで自分のワークロードで一度計測するのがいい。効くデータかどうかは、結局あなたの手元のデータ次第
導入も計測も難しくないから、まずは隔離 venv で [all] 入れて one-liner で測ってみるのがおすすめ
