すべてのAIコーディングエージェントは同じ問題に直面しています：トークンコストです。ツールコールの出力、ファイル読み取り、ログスニペット — すべてがコンテキストウィンドウに詰め込まれ、トークン単位で課金されます。大規模コードベースでClaude Code、Cursor、Codexを実行しているチームにとって、このコストは現実的な金額に — そしてコンテキストウィンドウの頭痛に — なります。
Headroomは、AIエージェントとLLMプロバイダーの間に配置されるオープンソースのローカルファーストトークン圧縮レイヤーです。AIエージェントが読み取るすべてのもの — ツール出力、ログ、RAGチャンク、ファイル、会話履歴 — をAPIに到達する前に圧縮します。
Headroomとは#
Headroomは、JSONデータで60～95%、コーディングエージェントで15～20%のトークン削減を実現しながら、同一の回答と動作精度を維持するコンテキスト最適化エンジンです。完全に可逆的で — オリジナルデータはローカルにキャッシュされ、LLMが完全なデータを必要とするときにいつでも取得できます。
4つのモードで動作：
- プロキシモード — コード変更不要のドロップインプロキシ（
headroom proxy --port 8787） - エージェントラップ — Claude Code、Codex CLI、Cursorなど18以上のエージェントを1コマンドでラップ
- Python/TypeScriptライブラリ — コード内でインラインの
compress()呼び出し - MCPサーバー — 任意のMCP互換エージェントに圧縮ツールを公開
プロジェクトはPythonコア + Rust拡張（PyO3経由）で構築されており、AST解析と圧縮において柔軟性とネイティブパフォーマンスの両方を提供します。
Headroomが重要な理由#
トークン削減は現実的#
| データタイプ | 圧縮率 | 方法 |
|---|---|---|
| JSONツール出力 | 60–95% | SmartCrusher — ユニバーサルJSON圧縮機 |
| コードファイル | AST認識 | CodeCompressor（Python, JS/TS, Go, Rust, Java, C/C++, Perl） |
| 散文/テキスト | v2トランスフォーマー | Kompress-v2-base（エージェントトレースで学習） |
| 画像 | 40–90% | MLルーター + OCR（RapidOCR/SigLIP） |
| コーディングエージェントセッション | 15–20% | 全圧縮機の組み合わせ |
プロバイダーKVキャッシュセーフ#
HeadroomのLive-Zone圧縮は、新しく到着したバイト（新しいツール出力、最新のターン）のみを圧縮し、凍結されたプレフィックスをバイト単位で同一に保ちます。これは、プロバイダーのKVキャッシュ（Anthropicのプロンプトキャッシングなど）がバイト完全一致のプレフィックスに基づいてキャッシュするため、非常に重要です。プレフィックスを変更するとキャッシュが無効になります。Headroomはそれを決して行いません。
可逆的圧縮#
LLMがトリミングされたデータを必要とする場合、HeadroomのCCR（Cached Context Retrieval）システムは、オリジナルをSQLiteまたはRedisにローカル保存し、軽量な検索タグ（<<ccr:HASH>>）を注入します。エージェントはheadroom_retrieveを呼び出して、オンデマンドで元のペイロードを取得できます。
出力トークンも削減#
Headroomは送信するデータだけでなく、モデルが書き戻すデータも削減します：
- Verbosity steering — プロンプトに簡潔な指示を追加
- Effort routing — ファイル読み取りのようなルーチンステップで推論予算を削減
対応統合#
18以上のAIコーディングエージェント（headroom wrap経由）：
Claude Code、Codex CLI、Cursor、Aider、GitHub Copilot CLI、OpenCode、Cline、Continue、OpenClaw、Goose、OpenHands、Mistral Vibe、Oh My Pi、ZCode。
SDKとフレームワーク： Anthropic SDK、OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno、Strands Agents SDK、FastAPI/ASGIミドルウェア
インストール方法#
# Python（uv推奨）
uv tool install --python 3.13 "headroom-ai[all]"
# pip経由
pip install "headroom-ai[all]"
# TypeScript SDK
npm install headroom-aiクイックスタート#
プロキシモード（コード変更不要）#
headroom proxy --port 8787
# LLMクライアントを http://localhost:8787 に指定エージェントラップモード#
headroom wrap claude
# Claude Codeが自動的に圧縮された入力を送信
headroom unwrap claude # 元に戻すインラインライブラリ#
from headroom import compress
compressed = compress(large_json_payload)動作の仕組み#
Agent / App → Headroom Proxy / Library → LLM Provider- 入力受信 — 着信プロンプトメッセージまたはツールペイロードストリームをインターセプト
- CacheAligner — プロバイダーのKVキャッシュプレフィックスを壊す可能性のある揮発性コンテンツを検査・警告
- ContentRouter — コンテンツタイプを検出（Magika/ヒューリスティック分析）し、最適な圧縮機を選択
- CCR — 元の詳細文字列をローカル保存し、検索タグを注入
- 最適化されたペイロードをLLMに転送
headroom learn機能#
Headroomは、過去の失敗したセッションをローカルでマイニングし、エージェントメモリ設定ファイル（CLAUDE.local.md、AGENTS.md）に自動的に修正を書き込みます。これにより、エージェントは時間とともに自身の間違いについて学習します。
クロスエージェントメモリ#
同じマシン上の複数のAIコーディングエージェント間で動作する共有・重複排除済みコンテキストストア。Claude Code、Cursor、Codexがコンテキストを重複させることなく共通のメモリを共有できます。
比較#
| 機能 | Headroom | ネイティブプロバイダー圧縮 | プロンプトキャッシュプロキシ |
|---|---|---|---|
| 圧縮率 | 60–95%（JSON）, 15–20%（コード） | 変動（コンテキスト喪失） | なし（キャッシュのみ） |
| 可逆的 | ✅ CCR検索 | ❌ コンテキスト喪失 | ❌ |
| KVキャッシュセーフ | ✅ CacheAligner | ✅ 同一プロバイダー | ✅ 同一プロバイダー |
| 出力削減 | ✅ Verbosity steering | ❌ | ❌ |
| クロスエージェントメモリ | ✅ 共有コンテキストストア | ❌ | ❌ |
| 自己学習 | ✅ headroom learn | ❌ | ❌ |
| エージェント統合 | 18以上 | 変動 | 変動 |
| コード変更 | 不要（プロキシ/ラップ） | 不要 | 不要 |
まとめ#
Headroomは、AI支援開発における根本的な非効率性 — 冗長で未圧縮のデータをLLM APIに送信すること — を解決します。JSONで60～95%の圧縮、可逆的検索、KVキャッシュセーフな圧縮、コード変更不要の統合により、大規模にAIコーディングエージェントを使用するチームにとって最も実用的なコスト削減ツールの1つです。
Apache 2.0ライセンス、ローカルファースト、Python + Rustで拡張可能 — HeadroomはあらゆるAIエージェントワークフローへのドロップインアップグレードです。