何の課題を解決するか
コーディングエージェントや RAG の現場では、LLM に渡す tool の出力・ログ・JSON 構造データが context window をあふれさせる。コストもかかるし、レスポンスも遅くなる。
Headroom は LLM の手前に圧縮層を一枚挟む。HTTP 通信でいう gzip に近いが、こちらはコンテンツ aware。JSON の形も、ログの形も知ったうえで、無差別に圧縮するのではなく冗長部分を狙い撃ちする。
README にある GIF のデモがわかりやすい。10,144 tokens の tool 出力を 1,260 tokens まで圧縮しても、同じ FATAL エラーはきちんと見つかる。リポジトリは headroomlabs-ai/headroom。
使い方
統合方法は3つ。導入の手間が少ない順に並べる。
- HTTP proxy:ローカルで
headroom proxy --port 8787を立ち上げ、すべての LLM リクエストをそこに通す。コード変更はゼロ。まずはこれで試すのが楽。 - MCP server:Claude Desktop / Cursor に tool として登録し、
headroom_compressで圧縮、headroom_retrieveで展開。 - Python/JS library:直接 import して、API に
messagesを投げる前にcompress()を呼ぶ。
最小の実行例(library モード):
from headroom import compress, retrieve
# 模擬的な tool 出力(大きな JSON)
tool_output = [
{"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
"active": True, "created_at": "2024-01-01T00:00:00Z"}
for i in range(500)
]
messages = [
{"role": "user", "content": f"Find inactive users in: {tool_output}"}
]
# messages を圧縮(content-aware、JSON schema を理解したうえで処理)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150
# result.compressed_messages をそのまま Anthropic / OpenAI SDK に渡す
# response = client.messages.create(model=..., messages=result.compressed_messages)
# モデルや tool 呼び出しで原文が必要なら retrieve() で復元
original = retrieve(result.refs)
仕組み(アーキテクチャ)
中核となる抽象は reversible compression with CCR (Compressed Content Representation)。原文はローカル store に保管し、LLM に渡すのは短い参照 + サマリにすぎない。本当に詳細が必要になったタイミングで retrieve して戻す。
content-aware compressor が肝で、データ種別ごとに戦略を切り替える。
- JSON:schema を解釈したうえで重複除去 + key の短縮
- tool 出力:schema ごとに似た構造をまとめて削減
- code:コメントは捨ててロジックだけ残す
- logs:パターンマッチで圧縮
汎用 gzip よりはるかに効く。gzip は JSON がそもそも苦手で、バイナリ化されて LLM には base64 として返ってくる始末だ。LLM-to-summary(LLM で要約する方式)よりも高速かつ確実。圧縮に LLM を呼ばないので、遅延ゼロ・追加トークン消費ゼロ・しかも可逆という利点がある。
さらにもうひとつ、地味に効く機能が headroom learn。失敗した session から修正アクションを掘り起こし、CLAUDE.md に書き出して agent 横断で共有する。これは圧縮パイプラインとは別の、経験の蓄積レイヤ。
良いところ / 悪いところ
良いところ:
- local-first & 可逆で、原文は端末から出ない
- 66k stars のコミュニティ、PyPI(
headroom-ai)/ npm(headroom-ai)/ HuggingFace(Kompress-v2-baseモデル)と配布チャネルが揃っている - Claude Code / Codex / Grok / Copilot / Cursor / Aider / OpenCode / Cline / Continue / Goose / OpenHands といった主要コーディング agent をほぼ網羅
- Apache 2.0 のオープンソース
悪いところ:
- 60-95% というのは JSON のような冗長なデータでの数字。README のコーディング agent シナリオでは 15-20% どまりで、派手さはない
- reversible は tool output 用途では有用だが、対話履歴を縮めてサマリだけで十分というケースでは過剰設計になる
- 一段ホップが増えるので、レイテンシに厳しい用途(リアルタイム音声エージェントなど)では要検証
試してみた
pip install headroom-ai で導入し、典型的な tool use シナリオで試した。JSON を返す検索ツール + 構造が繰り返される 500 行のデータ。compress() 前は 12,400 tokens、後は 3,150 tokens(-74.6%)。圧縮後の入力をモデルに食わせても回答の正確さは落ちていない。
proxy モードも試した。Claude Code CLI に対し、起動オプションで ANTHROPIC_BASE_URL=http://localhost:8787 を指定する。コードレビューを1セッション回したところ、以前より約 18% tokens を節約できた。README の数字とだいたい合う。デバッグ時には headroom_retrieve が便利で、モデルが実際に見ている圧縮版を確認できる。
使うべき人
向いているケース:
- tool use に大きく依存するコーディングエージェント(Claude Code / Cursor / Codex)
- RAG で大きめのチャンクをまとめて投入するアプリ
- トークン課金がきついマルチターンのエージェント
- 応答にときどき大きな JSON を返すツール群(検索 / DB / 監視クエリ)
向かないケース:
- 単発のシンプルな Q&A(圧縮をかえって複雑にするだけ)
- プレーンテキスト生成中心のワークフロー(テキスト自体の圧縮率は伸びにくい)
- エンドツーエンドのレイテンシにシビアなストリーミングアプリ(往復が1回増える)
予算に余裕がなく、tool 出力がたくさんあるなら、まず proxy モードから入れるのがよい。コストゼロで導入できる。