mcpField
H
headroom

headroom

github.com/l3ad3r1エージェントワークフロー077 回インストール15 週間前に更新
リポジトリ

headroom について

headroom はエージェントのコンテキストを圧縮し、LLM に送る内容を減らすツールです。JSON、コード、テキストを判別し、元データをローカルに保存して必要時に取得できます。

主な機能

  1. 01ツール出力と会話履歴の圧縮
  2. 02JSON、コード、テキストの判別
  3. 03元データのローカル保存と取得
  4. 04圧縮量とトークン削減の確認
  5. 05CLI と MCP サーバーの提供

活用シーン

  1. 01長いログがコンテキストを占める場合
  2. 02検索結果や大きなファイルの圧縮
  3. 03必要なときだけ元データを取得

MCP 対応

headroom の MCP サーバーは、内容の圧縮、元データの取得、統計確認のツールをクライアントに公開します。`headroom mcp install` で登録するか、`headroom mcp serve` で起動できます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/l3ad3r1/hermes-skills --skill headroom

インストール後、Claude Code で/headroomを入力して読み込まれたか確認します。

同梱ファイルNOTICE.md

詳細

Headroom

AI エージェント向けのコンテキスト圧縮 — ツール出力、ログ、検索結果、RAG チャンク、ファイル、会話履歴をモデルに渡す前に圧縮することで、意味を保ちながら LLM に送信するトークンを 60～95％削減します。コンテンツの種類（JSON／コード／テキスト）を自動検出し、CCR（Compress-Cache-Retrieve）に対応しています。元のコンテンツはローカルにキャッシュされ、必要に応じて取得できます。

上流プロジェクト：headroom（chopratejas 提供、Apache-2.0）；PyPI では headroom-ai として公開されています。

使用する場面

  • ツールやコマンドが、コンテキストウィンドウを肥大化させるような大量の出力（冗長なログ、大きな JSON、長いファイル一覧、検索結果、大きなファイル）を返す場合。
  • ユーザーからコンテキストの圧縮、ペイロードの縮小、トークンの節約を求められた場合。
  • 大量のコンテンツをコンテキストに追加する前に圧縮してください。

セットアップ

pip install "headroom-ai[mcp]"      # or [all] for every compressor / extra

MCP サーバーを登録します（headroom_compress／headroom_retrieve／ headroom_stats を公開します）。

headroom mcp install        # auto-configures detected coding agents
# or run the server directly: headroom mcp serve

すべてのトラフィックを自動的に圧縮するには、プロキシを実行し、クライアントの接続先をプロキシに設定します。すべての API リクエストがローカルプロキシを経由するため、意図的に有効にしてください。

headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

ツール（MCP、mcp__headroom__* として表示）

  • headroom_compress — コンテキスト／コンテンツの塊を圧縮します
  • headroom_retrieve — 圧縮前の元のコンテンツを取得します（CCR）
  • headroom_stats — 圧縮統計／トークン削減量を表示します

大きな出力には headroom_compress を使い、圧縮された要約をコンテキストに保持してください。元の内容全体が本当に必要な場合に限り、headroom_retrieve を呼び出してください。

CLI の追加コマンド：headroom perf（削減量）、headroom output-savings、 headroom learn --verbosity、headroom update。環境変数による切り替え： HEADROOM_OUTPUT_SHAPER=1、HEADROOM_UPDATE_CHECK=off、HF_HUB_OFFLINE=1。

インストールに関する注意点と既知の問題

Windows でのソースビルドは失敗します。代わりに WSL2 内にインストールしてください。 headroom-ai にはRust 拡張機能（crates/headroom-py、maturin／cargo でビルド）が含まれています。Windows では最近の Python 用のビルド済みホイールがないため、pip／uv はソースからのコンパイルにフォールバックしますが、GNU 版の link（Git／coreutils 由来）が MSVC のリンカー link.exe を上書きすると失敗します（link: extra operand → could not compile target-lexicon → maturin failed）。Windows の Rust ツールチェーンの問題を解決する代わりに、ホイールを問題なくビルドできる Linux 側にインストールしてください。

# inside WSL2 Ubuntu (no sudo needed):
curl -LsSf https://astral.sh/uv/install.sh | sh      # if uv isn't present
uv tool install "headroom-ai[mcp]"                   # -> ~/.local/bin/headroom

その後、WSL を介して実行するよう設定し、Windows クライアントから MCP サーバーを登録します。

claude mcp add-json headroom \
  '{"command":"wsl.exe","args":["-d","Ubuntu","-e","bash","-lc","export PATH=$HOME/.local/bin:$PATH; exec headroom mcp serve"]}' \
  --scope user

Linux／macOS では pip install "headroom-ai[mcp]" がそのまま動作します。WSL のラッパーは不要なので、headroom mcp serve を直接登録してください。

クレジット

上流プロジェクト：headroom（chopratejas 提供、Apache-2.0）；PyPI では headroom-ai として配布されています。このスキルは、Agent Skills 形式で上流ツールを説明し、利用できるように設定するものです。ソースは同梱されていません。PyPI／上流リポジトリからインストールしてください。

スキル作成：Rinu（l3ad3r1）、Claude（Anthropic）との共同制作。

コメント

Markdown 対応