ツール

Headroom:LLM 呼び出しに圧縮層をかぶせてトークンを 60-95% 削減

GitHub で 66k stars を誇るトークン圧縮ミドルウェア。library / proxy / MCP の3方式で統合でき、JSON データなら 60-95% のトークンを削れる。

文字サイズ

何の課題を解決するか

コーディングエージェントや 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 モードから入れるのがよい。コストゼロで導入できる。


参考:Headroom GitHub リポジトリ

出典: https://github.com/headroomlabs-ai/headroom