Headroom：エージェントが読むツール出力・ログ・ファイルをLLMに渡す前にローカルで圧縮し、必要なら原文を取り戻せるツール

headroomlabs-ai/headroomはPythonで書かれたオープンソースのプロジェクトで、Apache-2.0ライセンスです。2026年1月7日に作成され、最後のプッシュは10月13日、執筆時点でスターは約75,257、フォークは5,838です。売り込みは一文です。AIエージェントが読むすべて、つまりツール出力、ログ、RAGの断片、ファイル、会話履歴を、LLMに届く前に圧縮し、答えは同じまま、トークンは一部だけにするというものです。READMEは、圧縮は自分のマシンで行われ、圧縮のためにプロンプトやファイルの内容がどこかに送られることはないと強調しています。狙うのは、エージェントの利用でよくある無駄です。検索が100件の結果を返す、ログが同じ行を千回繰り返す、そのすべてがコンテキストに入り、ウィンドウを占め、トークンで課金されます。 構成は3つの部品です。ContentRouterが内容の種類を判定して圧縮器を選びます。JSONにはSmartCrusher、ソースコードには構文木に基づくCodeCompressor、通常のテキストにはKompress-v2-baseです。CacheAlignerは、事業者のKVキャッシュの先頭部分を壊す変わりやすい内容に印を付けるだけで、プロンプトは書き換えないとREADMEは述べています。要になるのがCCR、つまり可逆圧縮で、原文はローカルにキャッシュされ、モデルが全文を必要とするときにheadroom_retrieveを呼んで取り戻せます。これは圧縮でよくある心配、情報が失われないかに答えるものです。組み込みも柔軟です。コードでcompress(messages)を呼ぶ、headroom proxyでアプリのコードを変えずにプロキシを動かす、headroom wrapでClaude Code、Codex、Cursor、Aiderなど多数のコーディングエージェントを包む、あるいは3つのツールを持つMCPサーバーとして使えます。

関連する機能もいくつかあります。一つはエージェント間で共有する記憶で、Claude、Codex、Gemini、Grokで一つのストアを使い、自動で重複を除きます。もう一つはheadroom learnで、失敗したセッションを分析し、修正をCLAUDE.local.md（既定でgit管理外）、CLAUDE.md、AGENTS.md、GEMINI.md、GROK.mdに書きます。三つ目は出力トークンの削減です。送るものを小さくするだけでなく、モデルが書き返すものもプロキシ側で削ります。方法は二つで、「冗長さの誘導」はシステムプロンプトの末尾に「簡潔に、文脈を繰り返さない」という短い注意を足し、プロンプトキャッシュが効くようにします。「推論強度のルーティング」は、ファイル読み込みなどツール結果の後にモデルが作業を再開するだけの回では思考の強さを下げ、新しい質問やエラーでは全力を保ちます。READMEはOpus級モデルでは出力が入力の5倍のコストだと述べており、この部分には実益があります。 数値では、READMEの基準は実際のMCPサーバーの出力形式から作ったシード固定の4つの場面です。コード検索（100件）は17,199から13,597トークンで21%の節約、SRE障害調査は55,957から24,340で57%、コードベース探索は58,801から33,895で42%、GitHub課題の仕分けは46,067から32,429で30%です。プロジェクトは、節約は内容の繰り返しの多さに比例すると述べています。繰り返しのJSON配列やログ行は遅延の基準で90%を超え、文章やもともと密な出力はほとんど圧縮されません。圧縮は速く、10Kトークンのjson検索結果で中央値0.21ミリ秒、100Kトークンで1.4ミリ秒です。精度はN=100で、GSM8Kは基準もHeadroomも0.870、TruthfulQAは0.530から0.560ですが、プロジェクト自身が信頼区間内だとしており、差は検出できないと読むべきです。SQuAD v2は97%（圧縮19%）、BFCLは97%（圧縮32%）です。

安全に使うには、まず、数字はすべて小さな標本によるプロジェクト自身の基準です。本番に入れる前に、自分の実際のトラフィックでheadroom savingsを実行して節約率を確かめ、すでに簡潔な出力に大きな効果は期待しないでください。次に、headroom wrapは薄い包みだけではありません。ローカルのプロキシを起動し、包んだプロジェクトに意味的なコード探索のためのSerenaを入れます。Claude Codeでは~/.claude.jsonにローカル範囲のMCPサーバーを登録します。戻すにはheadroom unwrapを使い、不要ならフラグで省略できます。三つ目に、原文はローカルにキャッシュされますが、モデルが見るのは圧縮後の文章なので、エージェントの挙動をデバッグするときはその点を忘れないでください。全体として、考え方が明快で、可逆で、試しやすいコスト削減ツールであり、まずテスト環境で評価するのに向いています。