headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

Headroom – AIエージェントのためのコンテキスト圧縮レイヤー

概要 – Headroomは、言語モデルベースのエージェントが送信する入力（ツール出力、ログ、RAGチャンク、ファイル、会話履歴）を圧縮し、モデルが書き出す出力もトリミングできるライブラリ、CLI、およびプロキシです。圧縮はすべてユーザーのローカルマシン上で行われ、処理のためにデータがリモートサービスに送信されることはありません。

重要性 – 大規模言語モデル（LLM）のAPIはトークン単位で課金されます。コーディングアシスタントのワークフローでは、1回の要求に数万トークン（例：長いログダンプや検索結果）が含まれることがあります。Headroomは、モデルの回答を変えることなく、実際のシナリオでトークン数を20‑60%削減します。処理はローカルで高速（10 K‑tokenのペイロードあたり1ミリ秒未満）に行われるため、レイテンシへの影響は無視できます。

コアコンポーネント

コンポーネント	役割
`compress(messages)` (Python / TypeScript)	チャットメッセージリストの圧縮版を取得するために、あらゆるコードから呼び出せるインライン関数。
`headroom proxy`	OpenAI互換のクライアントが接続できるローカルHTTPプロキシ（デフォルトで `--port 8787`）。コード変更は不要です。
`headroom wrap <agent>`	人気のコーディングエージェント（Claude、Codex、Grok、Cursor、Copilotなど）向けのワンコマンドラッパー。プロキシの起動、オプションのヘルパー（例：Serenaコードナビゲーションツール）のインストール、エージェントのHeadroom経由のルーティング設定を行います。
MCP server	あらゆる Multi‑Component Protocol クライアント向けにRPCエンドポイント（`headroom_compress`、`headroom_retrieve`、`headroom_stats`）を提供します。
エージェント間メモリ	異なるエージェント間で圧縮されたコンテキストを重複排除する共有ストア。Claude、Codex、Geminiなどが同じ圧縮ペイロードを再利用できます。
CCR (可逆圧縮)	元の非圧縮テキストはローカルにキャッシュされます。LLMが完全なコンテンツを必要とする場合、`headroom_retrieve`で要求できます。
`headroom learn`	失敗したセッションを分析し、修正プロンプトを抽出してMarkdownファイル（`CLAUDE.local.md`、`AGENTS.md`など）に書き出し、将来の実行に役立てます。

仕組み（概要）

ContentRouter が各データ（JSON、ソースコード、プレーンテキスト、画像）を検査し、適切な圧縮器を選択します。
SmartCrusher が汎用JSONを処理し、CodeCompressor が多くのプログラミング言語のASTを処理し、Kompress‑v2‑base（HuggingFaceモデル）が自然言語テキストを圧縮します。
CacheAligner がプロバイダーのKVキャッシュプレフィックスを壊す可能性のある揮発性フラグメントをマークし、圧縮がキャッシュヒットを妨げないようにします。
圧縮されたペイロードがLLMプロバイダー（Anthropic、OpenAI、Bedrockなど）に送信されます。モデルが後で完全なテキストを要求した場合、CCRがローカルキャッシュからオリジナルを取得します。
モデルの返信後、Headroomは出力を整形することも可能です。システムプロンプトに簡潔な指示を追加し、純粋な継続ターンにおけるモデルの「思考負荷」を軽減することで、実務上、出力トークンを約30%削減します。

クイックスタート (≈60秒)

# インストール (Python, CLI, およびオプションのプロキシ拡張機能)
uv tool install --python 3.13 "headroom-ai[all]"   # または pip install "headroom-ai[all]"
npm install headroom-ai                               # TypeScript SDKのみ

# ローカルプロキシのデプロイとエージェントのラップ (例: Claude Code)
headroom deploy               # ローカルサーバーと設定ファイルのセットアップ
headroom wrap claude          # プロキシを起動し、Claude Codeを介して起動

# 動作確認と節約量の確認
headroom doctor               # ヘルスチェック
headroom dashboard            # リアルタイムのトークン節約ビュー (プロキシ実行中のみ)

コード内でライブラリを直接呼び出すことも可能です：

from headroom import compress
from openai import OpenAI

msgs = [{"role": "user", "content": "Analyze these results"}]
compressed = compress(msgs, model="gpt-4o")
client = OpenAI()
resp = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
print(f"Saved {compressed.tokens_saved} tokens ({compressed.compression_ratio:.0%})")

エージェントの互換性

Headroomは、多くのコーディングアシスタント（Claude Code、Codex、Grok CLI、Cursor、Aider、Copilot CLI、VS Code Copilot、OpenHands、Mistral Vibe、Kimi CLI、ZCodeなど）に対して、すぐに使える wrap コマンドを提供しています。OpenAI互換のクライアントであれば、ローカルプロキシURLを指定するだけで使用可能です。

パフォーマンス測定

シナリオ	圧縮前トークン	圧縮後トークン	節約量
SREインシデントデバッグ	55,957	24,340	57 %
コード検索 (100件)	17,199	13,597	21 %
コードベース探索	58,801	33,895	42 %
GitHubイシューのトリアージ	46,067	32,429	30 %

レイテンシ: 10 K‑tokenのJSONペイロードでp50が0.21ミリ秒、100 Kトークンで1.4ミリ秒。一般的なLLMリクエストのレイテンシを大幅に下回ります。

精度: GSM8K、TruthfulQA、SQuAD v2、およびツール使用スイートでのベンチマークでは、モデル品質の測定可能な低下は見られませんでした（例：TruthfulQA 0.530 → 0.560、信頼区間内）。

利用シーン / スキップすべきシーン

適している場合 – 大量のツール出力、ログ、RAGチャンクを定期的に取り込むコーディングエージェントを使用している場合。既存のコードを変更せずにトークンコストを削減したい場合。可逆圧縮やエージェント間でのメモリ共有が必要な場合。

スキップすべき場合 – ワークロードがすでに小さい場合（短い会話ターン、密度の高い文章）、またはプロバイダー組み込みの圧縮機能のみに依存しており、エージェント間メモリが不要な場合。

制限事項と注意点

圧縮は、反復的または構造化されたデータ（JSON配列、ログ）に対して最も効果的です。純粋な文章や既に圧縮されたペイロードでは削減効果はほとんどありません。
min_input_words しきい値より短いブロックは、KVキャッシュプレフィックスを保持するためにそのまま残されます。
出力整形は、ホールドアウトセット (HEADROOM_OUTPUT_HOLDOUT) を予約しない限り推定値です。ダッシュボードは信頼区間を報告します。
ラップされたエージェントを使用するにはプロキシを実行し続ける必要があります。停止すると headroom unwrap を介して元の設定に戻ります。

詳細情報

ドキュメントとアーキテクチャ – https://docs.headroomlabs.ai/docs/architecture
モデルカード – https://huggingface.co/chopratejas/kompress-v2-base
ライブデモGIF – 10 K‑tokenのログが FATAL 行を保持したまま1.2 Kトークンに圧縮される様子を表示。
Discordコミュニティ – https://discord.gg/yRmaUNpsPJ

要約

Headroomは、ローカルで実行されるオープンソースの圧縮レイヤーであり、コーディングアシスタントのワークフローにおいてLLMとの間で送受信されるトークン数を大幅に削減します。ライブラリ、ドロップインHTTPプロキシ、または数十の人気エージェント向けワンコマンドラッパーとして機能し、1ミリ秒未満のオーバーヘッドで20‑60%のトークン節約を実現し、回答品質を損なうことはありません。