はじめに
Claude Code や Codex などの AI エージェントを使っていると、コンテキストウィンドウとトークン消費が悩みの種になります。ツールの実行結果、ログ、ファイル、RAG で取ってきたチャンク、会話履歴のすべてがトークンとしてカウントされ、コストとレイテンシに影響します。
この課題に対するアプローチのひとつが Headroom という OSS です。この記事では Headroom の概要と基本的な使い方をまとめます。
Headroom とは
Headroom は、AI エージェントが読み込むあらゆるコンテンツ（ツール出力、ログ、RAG チャンク、ファイル、会話履歴）を LLM へ届く前に圧縮する OSS です。ローカルで動作するため、データが外部に送信されることはありません。
公式では以下の削減効果が示されています。
| ワークロード | Before | After | 削減率 |
|---|---|---|---|
| コード検索（100件） | 17,765 | 1,408 | 92% |
| SRE インシデントのデバッグ | 65,694 | 5,118 | 92% |
| GitHub Issue のトリアージ | 54,174 | 14,761 | 73% |
| コードベースの探索 | 78,502 | 41,254 | 47% |
JSON データだと 60〜95%、コーディングエージェント全体で 15〜20% のトークン削減を謳っています。GSM8K や TruthfulQA といったベンチマークで精度がほぼ変わらないとされています。
3つの利用形態
Headroom は用途に応じて 3 つの形態で使えます。
| 形態 | 使いどころ |
|---|---|
| ライブラリ | Python / TypeScript の自作アプリに compress() を組み込む |
| プロキシ | 既存アプリのコードを変更せず、リクエストを経由させて圧縮 |
| MCP サーバー | MCP クライアントから headroom_compress などのツールとして呼び出す |
さらに headroom wrap claude のようなコマンドで、対応エージェントをラップして起動するだけで裏でプロキシが立ち上がる仕組みも提供されています。
仕組み
内部では、コンテンツの種類を判別してから、それぞれに合った圧縮器を通す構成になっています。
各コンポーネントの役割は次のとおりです。
- ContentRouter：コンテンツタイプを検知し、適切な圧縮器を選ぶ
- SmartCrusher：JSON（配列・ネスト・混在型）の圧縮を担当
- CodeCompressor：AST を解析してコードを圧縮（Python、JS/TS、Go、Rust、Java、C/C++、Perl 対応）
- Kompress-v2-base：エージェントのトレースで学習した独自のテキスト圧縮モデル（HuggingFace で公開）
-
CCR（Compressed Context Retrieval）：可逆圧縮の仕組み。オリジナルはローカルにキャッシュされ、必要になれば LLM が
headroom_retrieveで取り出す
要約のように情報を捨てるのではなく、圧縮したオリジナルを後から復元できる設計になっています。
CCR により、LLM が圧縮された内容の詳細を知りたくなった場合には、ツール呼び出しでオリジナルを取得できます。要約ベースの手法にありがちな「後から詳細が参照できない」問題を回避できます。
インストール
インストール方法は複数用意されています。CLI とライブラリの両方を使うなら Python 版を選ぶことになります。
# Python（CLI + ライブラリ、推奨）
pip install "headroom-ai[all]"
# uv を使う場合
uv tool install --python 3.13 "headroom-ai[all]"
# TypeScript SDK（ライブラリのみ、CLI は含まれない）
npm install headroom-ai
# Docker
docker pull ghcr.io/headroomlabs-ai/headroom:latest
基本的な使い方
1. エージェントをラップして起動する
一番手軽な導入方法が headroom wrap です。対応するエージェントを指定するだけで、裏でプロキシが立ち上がり、圧縮が有効な状態でエージェントセッションが起動します。
headroom wrap claude
対応エージェントは Claude Code、Codex、Grok CLI、Aider、Copilot CLI、VS Code Copilot、Cline、Continue、Goose、OpenHands、Kimi CLI など多岐にわたります。Cursor と ZCode はプロキシを起動して接続先 URL を表示する半自動対応です。
不要になったら headroom unwrap <tool> で元に戻せます。
2. プロキシとして起動する
コードを変更せず任意のクライアントから利用したい場合は、プロキシとして起動して OpenAI 互換のエンドポイントを向けます。
headroom proxy --port 8787
これで http://localhost:8787 を LLM のエンドポイントに設定すれば、そこを通るリクエストが圧縮対象になります。
3. ライブラリとして呼び出す
自作のアプリに組み込む場合はライブラリとして直接呼び出せます。
from headroom import compress
messages = [
{"role": "system", "content": "..."},
{"role": "user", "content": "..."},
]
compressed = compress(messages, model="claude-3-5-sonnet")
TypeScript 版もほぼ同じインターフェースです。
import { compress } from "headroom-ai";
const compressed = await compress(messages, { model: "claude-3-5-sonnet" });
Anthropic SDK、OpenAI SDK、Vercel AI SDK、LangChain、LiteLLM 向けのアダプタも公式に用意されているので、既存の実装に差し込みやすくなっています。
4. 動作を確認する
セットアップ後は動作確認用のコマンドで状態を確認できます。
headroom doctor # ヘルスチェック
headroom perf # パフォーマンス確認
headroom dashboard # ライブの節約ダッシュボード（プロキシ稼働中）
出力トークンも削減できる
Headroom はプロンプトの圧縮だけではなく、モデルが返してくる側のトークンも削減する仕組みを持っています。特に Opus クラスのモデルでは出力コストが入力の 5 倍になるため、こちらの削減効果も大きいです。
具体的には、システムプロンプトの末尾に簡潔な指示を追加してモデルの前置きや同じコードの再掲を抑制したり、ツール実行結果を受け取っただけのターンでは thinking effort を下げたりします。
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
デフォルトはオフなので、必要に応じて有効化します。
メリットと注意点
メリットと注意点を整理します。
メリット
- ローカル動作：データが外部サービスに送信されない
- 可逆圧縮：オリジナルがローカルに保存され、必要なら取り出せる
- 導入方法が柔軟：ライブラリ、プロキシ、MCP、エージェントラップから選べる
- 多くのエージェントに対応：Claude Code、Codex、Cursor、Copilot など
注意点
- CLI は Python 版のみ：npm 版はライブラリだけなので混同しないよう注意
- ローカルプロセスが必要：サンドボックス化された環境や、ローカルで別プロセスを立てられない環境では使えない
- ML モデルの取得が必要：Kompress-v2-base は HuggingFace からダウンロードされる。SSL インスペクションのある企業ネットワークだと追加設定が必要になる
まとめ
この記事では、AI エージェント向けのコンテキスト圧縮ツール Headroom について、概要と基本的な使い方をまとめました。
AI エージェントを日常的に使っていてトークン消費が気になっている場合、まずは headroom wrap で試してみるのが手軽だと思います。