Claude CodeなどのAIエージェントを日常的に使っていると、あっという間に制限に引っ掛かることがありませんか？
Netflixのシニアエンジニアがオープンソースとしてリリースした「Headroom」というトークン削減ツールが、数日で 6k stars・400 forks を超えて(2026/06/03現在)話題になっています。
ちなみに公式ベンチマークによると、ビルドログなら93.9%、JSONなら90.6%のトークン削減を達成しています（ただし実運用の中央値は4.8%――この数字のギャップについては後述します）。
Headroomリポジトリ: https://github.com/chopratejas/headroom
3行まとめ
- HeadroomはAIエージェントへ送るコンテキストを圧縮してトークン消費を削減するOSS
- JSON・DB結果・ログでは大きな効果が期待できる
- ソースコードから設計書を生成する、設計書からコードを生成するといったコード中心のワークフローでは効果は限定的
トークンコストが膨らむ、本当の原因
Claude CodeなどのAIエージェントがなぜ高くつくのか、ちょっと調べてみると意外な事実がありました。
コストの主犯は「出力トークン」ではなく 「入力トークン」 です。
AIエージェントは会話文だけでなく、こういったものを次々とコンテキストに積み込みます。
- データベースのクエリ結果（500行とか普通に返ってくる）
- ビルドログやエラーログ
- APIのレスポンスJSON
- RAGで引っ張ってきたドキュメントの断片
- ファイルツリー
そして、これらの 多くは人間なら一瞬で構造を読み飛ばせる反復的なデータ です。
でも、LLMはそれを全部読みます。全部課金されます。
Headroomを作ったTejas Chopra氏自身、通常の開発作業でClaude Codeの月額が287ドルに達し、内訳を調べると不要なDBの行やネストしたJSONが大量にコンテキストを埋めていたことに気づいたそうです。Headroom導入後は約110ドルまで下がったと報告しています（自己申告の数値なので参考値として）。
Headroomって何をするツールなのか
一言でいうと、LLMにデータが届く前に、コンテキストを圧縮するレイヤーです。
「要約」とは違います。大事なのは、データの種類に応じて圧縮の方法を変えるという設計です。
AIエージェント（Claude Code, Cursor, Codex...）
↓ ツール出力・ログ・RAG結果・ファイル
┌──────────────────────────────┐
│ Headroom（ローカルで動作） │
│ ContentRouter が種類を判定 │
│ ├─ SmartCrusher （JSON） │
│ ├─ CodeCompressor （AST） │
│ └─ Kompress-base （テキスト）│
└──────────────────────────────┘
↓ 圧縮済みプロンプト
LLMプロバイダー（Anthropic・OpenAI...）
たとえば500行のJSON配列があったとします。人間なら列の構造を一瞬確認して、あとはエラーや異常値のある行だけ探しますよね。HeadroomのSmartCrusherも同じ発想で、先頭・末尾・重要度が高い項目やエラー行を残し、反復的な部分を統計的な表現に置き換えます。
定量的な削減データ（公式ベンチマーク）
詳細データ：Benchmarks | Headroom
コンテンツ種別ごとの削減率
| コンテンツ | 削減前 | 削減後 | 削減率 | 処理時間 |
|---|---|---|---|---|
| JSON配列（100件） | 3,163 tokens | 297 tokens | 90.6% | 1ms |
| JSON配列（500件） | 9,526 tokens | 1,614 tokens | 83.1% | 2ms |
| シェル出力（200行） | 3,238 tokens | 469 tokens | 85.5% | 1ms |
| ビルドログ（200行） | 2,412 tokens | 148 tokens | 93.9% | 1ms |
| grep結果（150件） | 2,624 tokens | 2,624 tokens | 0%（意図的） | <1ms |
| Pythonソース（480行） | 2,958 tokens | 2,958 tokens | 0%（意図的） | <1ms |
| 合計 | 23,921 | 8,110 | 66.1% | 5ms |
grepとコードが0%なのは仕様です。「すでにコンパクトな形式を余計に変えると正確性が壊れる」という判断で、あえて圧縮しない設計になっています。
精度への影響
100件のJSONログ（67番目にFATALエラーが埋まっているテスト）では、10,144 tokens → 1,260 tokens（87.6%削減）で正解率4/4を維持。なお、F1スコアが0.85→0.87という数値は別のQA精度ベンチマークの結果であり、JSON圧縮の話とは分けて読む必要があります。HTMLノイズ除去でLLMが本質的なコンテンツに集中しやすくなるためと説明されています。
⚠️ 実運用の数字は異なる（ここが重要）
「60〜95%削減」という宣伝文句と実態のギャップを正直に書いておきます。
公式がプロキシの実運用50,000+セッション（250+インスタンス、2026年3〜4月）から集計した数字がこちらです。
| パーセンタイル | 実際の削減率 |
|---|---|
| P25 | 4.8% |
| 中央値（P50） | 4.8% |
| P75 | 6.9% |
| 平均 | 11.3% |
中央値はわずか 4.8% です。
なぜかというと、実際のセッションには「短い会話ターン」が大量に混ざるからです。公式ドキュメントも「ファイル読み込みやシェル出力が多いヘビーなツール使用セッションでは40〜80%になる」と説明しています。
つまり、効果は使い方次第で大きく変わるということです。
コスト換算
圧縮処理の時間コストと節約できるトークンコストを比較したところ、検証した5シナリオのうち大半で、Headroomの導入効果（メリット）がコストを上回ります。プロキシのオーバーヘッド中央値は52msで、LLMの推論時間（2〜10秒）と比べると無視できるレベルです。
使い方の選択肢が豊富
自分のワークフローに合わせて選べます。
github内のREADMEから抜粋すると
1. CLIラッパー（最も手軽）
pip install "headroom-ai[all]"
# 既存のエージェントをそのままラップ
headroom wrap claude
headroom wrap cursor
headroom wrap codex
2. プロキシとして使う（コード変更ゼロ）
headroom proxy --port 8787
OpenAI互換のプロキシとして起動するので、エンドポイントのURLを変えるだけで既存のコードがそのまま動きます。
3. Pythonライブラリとして組み込む
from headroom import compress
compressed = compress(messages, model="claude-sonnet-4-6")
# あとは通常のAPIコールと同じ
4. MCPサーバーとして
headroom mcp install
MCP対応クライアントからheadroom_compress、headroom_retrieveなどのツールとして利用できます。
「可逆圧縮（CCR）」という仕組みが面白い
Headroomの特徴的な機能に CCR（Compress, Cache and Retrieve） があります。
圧縮前の原文をローカル（RedisやSQLite）に保存しておいて、LLMが詳細を必要とした場合にMCPツール経由で元データを取得できるという設計です。
これが単純な要約・切り捨てとの大きな違いです。
- 要約: 後から必要になるかもしれない1行を消すリスクがある
- 切り捨て: ログの中間にあるエラーや外れ値を落としやすい
- CCR: まず圧縮版を渡して、必要なら元データへ戻れる
「ローカルファースト」を掲げているのもここが理由で、社内ログや機密データを外部サービスへ送る必要がありません。
こんな時には効果が出やすい
公式ドキュメントでも「効く場所は偏っている」とはっきり書かれています。
効果が出やすい：
- JSON-heavyなAPIレスポンスを扱う
- データベースの行をよく読み込む
- 構造化ログやビルド・テスト出力がある
- 長いエージェントセッションを使う
- 複数エージェント（Claude Code + Codexなど）を組み合わせている
効果が薄い：
- 短い会話のみ
- コードだけのセッション
- 単発の問い合わせ
こんな時には効果が出にくい
公式のLimitationsページに「効かないケース」が正直に書かれているので、よく話題になる2つのユースケースについてまとめておきます。
ソースコードから設計書を生成する
コードを読み込ませてLLMに設計書を書かせるパターンは、ほぼ効果なしです。
公式ドキュメントによると、ソースコードは「正確性を保つため圧縮しない」設計になっています。さらに、「analyze」「review」「explain」「fix」「debug」などのキーワードが直近のメッセージに含まれると、会話内の全コードが自動的に保護されます。設計書生成の文脈ではこれらのキーワードがほぼ確実に含まれるため、圧縮は発動しません。
設計書からコードを生成する
設計書（テキスト・ドキュメント）を入力としてコードを生成するパターンも、効果は薄いです。
RAGで取得してきたドキュメントは現時点ではパススルー（圧縮ゼロ）、直接貼り付けたプレーンテキストでも43〜46%の削減にとどまります。加えて、テキスト圧縮は処理時間がかかるため「コスト削減にはなるがレイテンシは増える」とドキュメントに明記されています。
コードや設計書を主体とするワークフローは、Headroomの設計上の対象外に近いです。
⚠️ 企業利用前に確認したいセキュリティの話
「proxy/wrapモードだと外部に情報が流れるのでは？」というツイートを見かけたので、ここはちゃんと調べてみました。
結論：Headroom自体がデータを外部サーバーに送っているわけではない
圧縮処理自体はローカル完結
READMEには Headroom (runs locally — your data stays here) と明記されており、圧縮・変換の処理はすべてローカルで完結します。ツール出力やログをHeadroomが外部サーバーで処理しているわけではありません。
ただし、前提として「圧縮後のデータはLLMプロバイダー（Anthropic・OpenAIなど）に送られる」のは当然ですが、それはHeadroom導入前も同じです。Headroomが追加する情報漏えいルートはありません。
⚠️ 注意点①：匿名テレメトリがデフォルトでON
公式の設定ドキュメントに、こういう環境変数が記載されています。
HEADROOM_TELEMETRY デフォルト: on（匿名テレメトリ）
何が送られているかの詳細な説明はドキュメントに明記されていませんが、「匿名の使用統計」と思われます。気になる場合は明示的にオフにできます。
export HEADROOM_TELEMETRY=off
企業のセキュリティポリシーによっては、デフォルトのままにせずオフにすることを検討すべきでしょう。
⚠️ 注意点②：デフォルト設定でLAN全体に公開されるケースがある
ドキュメントには --host 0.0.0.0 という起動オプションの例が記載されています。これはローカルホストだけでなくLAN上の全インターフェースにプロキシをバインドするという意味です。
headroom proxy \
--port 8787 \
--host 0.0.0.0 \ # ← LAN全体に公開される
...
環境変数のデフォルトは HEADROOM_HOST: 127.0.0.1（ローカルホストのみ）となっているので、コマンドオプションのサンプルをそのままコピペしなければ問題ありません。ただし、共有開発サーバーやDockerで動かす場合は意図せずLAN公開にならないよう注意が必要です。
「外部に情報が行く」ツイートの真偽
元のツイートの主張は 誤解だが注意も必要 という感じです。
- ❌ 誤り：Headroom自体がデータを外部サーバーに送っているわけではない
- ✅ 正しい懸念：デフォルトでテレメトリがオンになっている点は確認が必要
- ✅ 正しい懸念：設定次第でLAN公開になりうる点は注意が必要
- ✅ 正しい懸念：headroomlabs.aiのダッシュボードに「コミュニティ全体の節約トークン数」が集計表示されている可能性があるが、ここは推測を含むため断定しない
企業のセンシティブなログや機密DBの結果を扱う場合は、導入前にセキュリティチームと確認することをお勧めします。
さいごに
AIエージェントが日常の開発フローに入り込んできた今、「賢いモデルを使うか」という話と同じくらい「モデルに毎回何を読ませているか」が重要になってきています。
Headroomはその問題に対して、ローカル・可逆・マルチエージェント対応という方向性で切り込んでいます。数日でこれだけStarが集まったのも、同じ課題を感じている開発者が多いことの表れだと思います。
私もそのうち実際に試してみようと思っています。試した方がいれば感想をコメントで教えてください！