AIエージェントの入力を可逆圧縮する Headroom を調べた ── 導入前の仕組み調査編

Headroom（ヘッドルーム）は、2026年1月7日に公開されてから半年足らずでスター数48,000超まで伸びたツールだ。ツール出力・ログ・RAGのチャンク・ファイル・会話履歴を、LLMに渡す前に圧縮するレイヤーになっている。エージェントが自分でツールを呼び、自分で次の判断をするようになるほど、その途中で読み込むログやファイルの量も増えていく。入力トークンが減ればそのまま課金額も減るので、サブエージェントを多用してトークンを食っている人ほど恩恵が大きい話だ。うちのブログ運用も記事執筆や自動復帰がサブエージェント経由ばかりで、トークン消費の最大要因がそこにある（実測記事で書いた）。今回はまず仕組みを調べ、実際に動かすのは次回に回す。

何を圧縮するのか

公式が出している実測値はこの3パターンだ。

用途	削減前	削減後	削減率
コード検索（100件）	17,765トークン	1,408トークン	92%
SREインシデント調査	65,694トークン	5,118トークン	92%
GitHub Issueトリアージ	54,174トークン	14,761トークン	73%

全体としては「60〜95% fewer tokens」を謳っている。これは表の3パターンと同じく、LLMに渡す入力トークンの話だ。圧縮で短くなった出力（LLMの応答そのもの）にも別途削減効果があると書かれているが、その数字は実測ではなく推定値だと公式が明記している。精度面では GSM8K（数学問題）のスコアが元と同等の0.870、TruthfulQA は0.530から0.560に向上したという結果だ。どのLLMで測った数字かまでは公式README上で明記されておらず、その点は割り引いて見る必要がある。

主な圧縮方式

SmartCrusher: JSON配列・ネストしたオブジェクトの圧縮
CodeCompressor: AST（抽象構文木）を使ったコード圧縮。Python・JavaScript・Go・Rust・Java・C++に対応
Kompress-base: agentic trace（エージェントの行動ログ）向けに、Hugging Face で学習したモデルを使う圧縮
画像圧縮: 40〜90%削減
CacheAligner: プレフィックスを安定させて、LLM側のキャッシュ命中率を上げる
CCR（可逆圧縮）: 元データはローカルに保存され、必要なときに検索して取り出せる

最後の CCR が記事タイトルにも書いた「可逆」の部分だ。「可逆圧縮」と聞くと zip のように LLM 自身が解凍するように思えるが、そうではない。仕組みはシンプルで、元のテキストはローカルのストレージにそのまま保存し、LLM には圧縮した要約だけを渡す。LLM が読むのは圧縮後の短い表現だけなので、入力トークンはその分減る。元データが必要になる場面（人間が後で詳細を確認したい、ツールが元のログを再実行したい）では、ローカルに残った元データを ID で検索して引き出す。つまり LLM 自身が圧縮データを「復元」しているわけではなく、必要なときだけ別経路で元データに当たれる、という設計だ。

導入の形は4つ

ライブラリとして compress(messages) を Python / TypeScript に直接組み込む
プロキシとして headroom proxy --port 8787 を立て、既存コードの変更なしに経由させる
headroom wrap claude / codex / cursor / aider / copilot で、エージェントのコマンドをそのままラップする
MCPサーバーとして、MCP対応クライアントから呼び出す

対応エージェントは Claude Code、Codex、Cursor、Aider、Copilot CLI、OpenClaw、Cortex Code、OpenAI互換クライアントまで幅が広い。インストールは pip install "headroom-ai[all]"（Python 3.10以上）か npm install headroom-ai、Docker イメージも配布されている。

ライセンスは Apache-2.0。ローカル実行が前提で、外部にデータを送らない設計だが、ONNX Runtime（cdn.pyke.io）と Kompress モデル（huggingface.co）の取得には初回だけネット接続が必要になる。サンドボックス環境でローカルプロセスが起動できない場合は使わない方がいいと、公式ドキュメント自身が明記している。

導入するなら確認しておきたいこと

headroom wrap claude は Claude Code の起動コマンドそのものを差し替える。一度噛ませると、以後のやりとりは Headroom 経由になる。効果が大きい分、エージェントの動作に直接介入する変更でもあるので、いきなり全面導入する前に挙動を確かめておきたい。

まずは headroom proxy でコードを変えずに動かし、削減率と挙動を見る。問題なければ wrap claude に進む。公式の数字どおりに92%減るなら、サブエージェントを多用するエージェント運用ほど削減幅が大きくなる。LLMに渡す前段でコンテキストを削るレイヤーは、エージェントが自律的に動く時間が増えるほど必要になっていくはずだ。その手応えを自分の環境の数字で確かめてから、実践編を書く。