概要
LLMのコンテキストを圧縮するライブラリ「headroom」をClaude Codeに導入した実測レポートで、構造化JSONで44.6%のトークン削減を確認しつつ、用途による向き不向きを解説しています。
詳細内容
### headroomの概要と仕組み
headroomはLLMに送信するコンテキストを事前に圧縮するミドルウェアです。データ型を判定する「ContentRouter」と、JSON用の「SmartCrusher」、コード用の「CodeCompressor」などの専用圧縮器を使い分けることで効率化を図ります。特筆すべきは可逆性で、原本をローカルに保持（CCR）し、LLMが必要とした際に`headroom_retrieve`で完全な情報を復元できる二段構えの設計です。
### 導入と検証結果
導入は非常に容易で、`headroom wrap claude`コマンドやProxy経由での利用が可能です。実際の計測では、100件のコード検索結果（構造化JSON）において**44.6%のトークン削減**という高い効果を示しました。一方で、400行の素のビルドログでは削減率が0%となり、汎用的な冗長テキストを単純なライブラリ呼び出しのみで縮めるのは難しいことも判明しました。
### 活用のアドバイス
「何でも縮む魔法」ではなく、ツール出力やRAGの検索結果など、型が決まったデータを大量に扱うワークロードで真価を発揮します。Claude Codeなどのエージェントでコンテキスト上限に悩む開発者にとって、特定のユースケースにおいて極めて有効な選択肢となります。導入前に自分のワークロードで効果を計測することが推奨されます。