headroomlabs-ai/headroom

これは何？

主な機能

• 01コンテンツの種類に応じて、JSON、コード、文章向けの圧縮器を選択するルーティング。
• 02圧縮は可逆で、元データをローカルにキャッシュし、必要に応じて取得可能。
• 03コード変更不要のプロキシと、人気のコーディングエージェント向けのワンコマンドラッパー。
• 04インラインで利用できるcompress()を備えたPython／TypeScriptライブラリ。
• 05compress、retrieve、statsツールを備えたMCPサーバー。
• 06ローカルで処理するため、プロンプトやファイルの内容を圧縮サービスに送信しない。

ユースケース

• ツール出力の多い長時間セッションで、Claude CodeやCursorなどのコーディングエージェントのトークンコストを削減する。
• デバッグのためにモデルへ送る前に、ログダンプや大規模なJSON検索結果を圧縮する。
• 既存のLangChainまたはLiteLLMのパイプラインで、取得したRAGチャンクを小さくする。
• 複数のエージェントを1つの共有プロキシとメモリレイヤー経由で利用する。

クイックスタート

1. 1

   uvでCLIをインストールする

   uv tool install --python 3.13 "headroom-ai[all]"
2. 2

   またはpipでPythonパッケージをインストールする

   pip install "headroom-ai[all]"
3. 3

   ポート8787でドロップインプロキシを起動する

   headroom proxy --port 8787
4. 4

   ヘルスチェックでインストールを確認する

   headroom doctor

使う前に知っておきたいこと

• !削減効果は大きく異なります。文章や、もともと圧縮率の高い出力では、ほとんど圧縮されません。
• !READMEに記載された圧縮ベンチマークは自己申告によるもので、特定のシード済みシナリオで実行されています。

トピック

よくある質問

headroom とは？

LLMに渡す前にツール出力、ログ、ファイル、RAGチャンクを圧縮するライブラリ、プロキシ、MCPサーバー。 Headroomは、AIエージェントやLLMアプリケーション向けのコンテキスト圧縮レイヤーです。ツール出力、ログ、RAGチャンク、ファイル、会話履歴をモデルに送る前に圧縮し、ユーザーのマシン上でローカルに処理します。コンテンツルーターが各ペイロードの種類を判別し、JSONにはSmartCrusher、ソースコードにはASTを考慮したCodeCompressor、文章にはKompress-v2-baseモデルを使います。

headroom は無料で使えますか？ライセンスは？

headroom は Apache-2.0 ライセンスのオープンソースです。商用製品で使う前にライセンス条件を確認してください。

headroom は今もメンテナンスされていますか？

活発にメンテナンス中。headroom の最終コミットは 2026年10月17日 です。

headroom は何に使えますか？

ツール出力の多い長時間セッションで、Claude CodeやCursorなどのコーディングエージェントのトークンコストを削減する。 デバッグのためにモデルへ送る前に、ログダンプや大規模なJSON検索結果を圧縮する。 既存のLangChainまたはLiteLLMのパイプラインで、取得したRAGチャンクを小さくする。 複数のエージェントを1つの共有プロキシとメモリレイヤー経由で利用する。

headroom のインストール方法は？

uvでCLIをインストールする: uv tool install --python 3.13 "headroom-ai[all]" またはpipでPythonパッケージをインストールする: pip install "headroom-ai[all]" ポート8787でドロップインプロキシを起動する: headroom proxy --port 8787 ヘルスチェックでインストールを確認する: headroom doctor

headroom はどこで入手できますか？

ソースコードとインストール手順は GitHub にあります：https://github.com/headroomlabs-ai/headroom