HeadroomでLLMトークンを最大95%削減する

AIコーディングの請求書を見て、驚いた経験はありませんか。ツール出力やログがコンテキストを埋め尽くし、使っていないトークンまで課金されるのが現状です。

この記事では、NetflixのシニアエンジニアTejas Chopra氏が開発したオープンソース「Headroom」の仕組みと、CursorやClaude Codeと組み合わせてLLMコストを下げる手順を解説します。

この記事でわかること

• Headroomがトークンを60〜95%削減できる理由
• ローカルプロキシ経由でCursorやClaude Codeを動かす手順
• 類似ツールとの違いと導入時の注意点

https://github.com/chopratejas/headroom

LLMコストが膨らむ本当の原因

Claude CodeやCursorで開発すると、会話そのものよりツール出力がコンテキストを占めます。データベースのMCP（Model Context Protocol）クエリ結果、ログ検索、APIレスポンスのJSONなど、構造は同じでも行数だけが増えるデータが大量に送られます。

Chopra氏は自身のClaude Code利用で287ドルの請求を受け、内訳を調べたところコンテキストの約90%が冗長なデータだったと報告しています（参考）。500行のクエリ結果のうち必要なのは数行、エラーログは数千行の中の2行だけ、といったケースが典型です。

要約や単純な切り詰めでは、後から必要になった情報が失われます。Headroomは「圧縮可能なデータを、元に戻せる形で小さくする」という発想でこの課題に向き合っています。

Headroomとは何か

Headroomは、AIエージェントとLLMプロバイダの間に挟むコンテキスト最適化レイヤーです。ツール出力、ログ、RAG（Retrieval-Augmented Generation）の検索結果、ファイル内容、会話履歴を、LLMに届く前に圧縮します。処理はローカルで完結し、データは開発者のマシン内に留まります。

GitHubリポジトリは2026年1月に公開され、Apache 2.0ライセンスで提供されています。2026年6月時点でGitHubスター数は4万超、最新リリースはv0.26.0です。Netflixの公式プロジェクトではなく、Chopra氏の個人開発ですが、The Registerの報道では社内の複数チームが利用しているとされています（参考）。

仕組み：3段階の圧縮パイプライン

Headroomはリクエストごとに次の流れでコンテキストを処理します。

CacheAlignerでキャッシュ効率を改善

AnthropicやOpenAIはプロンプトキャッシュで入力トークンを割引しますが、日付やセッションIDがシステムプロンプトに含まれると、毎回キャッシュが無効になります。CacheAlignerは動的な部分を末尾へ移し、固定部分のプレフィックスを揃えてキャッシュヒット率を上げます。

ContentRouterで内容別に圧縮

コンテンツの種類を判定し、専用の圧縮器へ振り分けます。

• SmartCrusher：JSON配列やネストしたオブジェクトを統計的に圧縮。異常値やクエリに関連する行は残し、残りは統計情報に置き換えます
• CodeCompressor：Python、JavaScript、Go、Rust、Java、C++のAST（抽象構文木）を解析してコードを圧縮します
• Kompress-base：エージェントの利用ログで学習したHugging Faceモデルでテキストを圧縮します

CCRで元データを復元可能にする

CCR（Compress-Cache-Retrieve）は圧縮の可逆性を担う仕組みです。圧縮時に元データをローカル（SQLiteやRedis）へ保存し、圧縮後のテキストにマーカーを残します。LLMが詳細が必要になった場合、headroom_retrieveツール経由で元の全文を取得できます。要約と違い、情報を捨てずにトークン数だけを減らせる点が特徴です。

削減効果はどの程度か

公式ベンチマークでは、実際のエージェントワークロードで次の削減率が報告されています。

精度面では、GSM8K（数学）でベースラインと差分±0.000、TruthfulQA（事実性）で+0.030、BFCL（ツール利用）で32%圧縮時に97%の精度を維持したとされています。Open Source Summitでの発表では、利用者全体で推定70万ドル相当のコスト削減、2000億トークンの節約があったと紹介されています（参考）。

使い方：3つの導入モード

プロキシモード（コード変更不要）

最も手軽な方法です。ローカルでプロキシを起動し、エージェントのAPI接続先を差し替えます。

pip install "headroom-ai[proxy]"
headroom proxy --port 8787

Claude CodeならANTHROPIC_BASE_URL=http://localhost:8787、CursorなどOpenAI互換クライアントならOPENAI_BASE_URL=http://localhost:8787/v1を設定します。headroom wrap cursorやheadroom wrap claudeを使えば、環境変数の設定手順を案内してくれます。

ライブラリモード

PythonやTypeScriptアプリに直接組み込む場合はcompress(messages)を呼び出します。自前のエージェントやLangChain、LiteLLMなどのフレームワーク連携向けです。

MCPサーバーモード

headroom mcp installでMCPサーバーを登録すると、headroom_compress、headroom_retrieve、headroom_statsの3ツールがエージェントから使えます。Claude DesktopなどMCP対応クライアント向けです。

料金とライセンス

Headroom本体は無料のオープンソースです。圧縮処理はローカルで動くため、Headroom利用そのものに追加料金はかかりません。ただしLLMプロバイダへのAPI利用料は別途発生します。プロキシ経由でリクエストごとに2〜5ミリ秒程度の遅延が加わる点は、超低遅延が求められる用途では計測が必要です。

類似ツールとの違い

HeadroomはRTKを内部で利用しつつ、その下流のデータも圧縮する設計です。ホスト型の圧縮APIと違い、ソースコードやログを外部サーバーに送らない点がセキュリティ面でも有利です。

導入前に知っておきたいこと

Headroomは万能ではありません。すでに密度の高い独自コンテンツは圧縮余地が小さく、公式でも「無理に圧縮しない」と明記されています。サンドボックス環境でローカルプロセスが動かせない場合も利用できません。

一方で、MCPツールを多用する開発者、複数エージェントを並行運用するチーム、月額のトークン上限に達しやすい個人開発者には効果が出やすいツールです。まずはheadroom proxy --port 8787で起動し、headroom perfで削減量を確認するのが現実的な第一歩です。