headroomの使い方完全ガイド【インストールから応用まで】

大規模言語モデル（LLM）を活用した開発は、現代のAIアプリケーションの主役です。しかし、そこには常に「トークン数」という課題がつきまといます。LLMへの入力が長くなると、APIコストは増大し、応答速度は低下し、モデルが重要な情報を「見落とす」可能性も高まります。

想像してみてください。あなたは複雑なコードベースを分析するAIアシスタントを開発しています。アシスタントは、大量のログファイル、複数ソースからのRAG（Retrieval-Augmented Generation）チャンク、そして過去の会話履歴を参照しながら、ユーザーの質問に答える必要があります。

headroomがない世界では、

長大な入力プロンプトがLLMに送られ、高額なAPI料金を請求されます。
応答が返ってくるまでに時間がかかり、開発やデバッグの効率が落ちます。
重要な情報がプロンプトの途中で「埋もれて」しまい、LLMが適切な回答を生成できないことがあります。
コンテキストウィンドウの制限に頻繁にぶつかり、情報の取捨選択に頭を悩ませます。

headroomがある世界では、

LLMに送られるトークン数が劇的に削減され、APIコストを大幅に抑制できます。
プロンプトが短くなることで、LLMの応答速度が向上し、開発体験が快適になります。
重要なコンテキストは保持されたまま圧縮されるため、LLMはより正確な回答を生成しやすくなります。
長文の入力にも臆することなく、より多くの情報をLLMに与えられます。

headroomは、このようなLLM開発におけるトークンの課題を解決するために誕生しました。あなたの開発プロセスをよりスムーズに、より経済的に変える強力なツールとなるでしょう。

headroomとは

headroomは、AIエージェントやLLMに送られるプロンプトのトークンを、大幅に圧縮するレイヤーです。具体的には、ツール出力、ログ、RAGチャンク、ファイル、会話履歴など、あらゆる入力データをLLMに届く前に最適化します。これにより、60%から95%ものトークン削減を実現しながら、LLMの回答品質を維持できます。

その仕組みは非常にシンプルです。あなたのアプリケーションとLLMプロバイダーの間にheadroomが介在し、送信されるプロンプトを「圧縮」します。

 あなたのエージェント / アプリケーション
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, あなた自身のコードなど…)
        │   プロンプト・ツール出力・ログ・RAG結果・ファイル
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (ローカルで実行 — あなたのデータはここに留まります)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-base  (テキスト, HF)  │
    │                                                    │
    │  クロスエージェントメモリ・headroom learn・MCP      │
    └────────────────────────────────────────────────────┘
        │   圧縮されたプロンプト + 検索ツール
        ▼
 LLMプロバイダー  (Anthropic・OpenAI・Bedrock など)

headroomは、入力コンテンツの種類を自動的に検出し、最適な圧縮アルゴリズムを選択します。例えば、JSONデータにはSmartCrusher、コードには抽象構文木（AST）ベースのCodeCompressor、一般的なテキストにはKompress-baseなどのモデルを使用します。さらに、オリジナルのプロンプトはローカルにキャッシュされ、必要に応じてLLMがheadroom_retrieveツールを呼び出して元の情報を取得できる「可逆圧縮（CCR）」機能も備えています。

このツールは、以下の3つの主要な利用形態を提供します。

ライブラリ: PythonやTypeScriptのコードに直接組み込み、メッセージを圧縮します。
プロキシ: アプリケーションのコード変更なしに、透過的にトークンを圧縮するサーバーとして機能します。
エージェントラップ: 特定のコーディングエージェント（Claude、Codexなど）をコマンド一つで最適化します。

headroomは、LLM開発におけるトークン管理の複雑さを解消し、より効率的でコスト効果の高いAIアプリケーション構築を可能にするために生まれました。

インストール方法

headroomのインストールは非常に簡単です。PythonとNode.js/TypeScriptの両方に対応しています。Python 3.10以降のバージョンが必要です。

Pythonの場合

仮想環境（venvなど）の使用を強く推奨します。これにより、プロジェクトごとに依存関係を管理できます。

まず、仮想環境を作成してアクティブ化します。

python3.10 -m venv .venv
source .venv/bin/activate

次に、headroomをインストールします。[all]オプションを含めることで、プロキシ、機械学習モデル、コード圧縮、メモリ管理など、すべての機能に必要な依存関係をインストールできます。

pip install "headroom-ai[all]"

特定の機能のみが必要な場合は、例えばプロキシ機能だけをインストールすることも可能です。

pip install "headroom-ai[proxy]"

Node.js / TypeScriptの場合

npmまたはyarnを使ってインストールします。

npm install headroom-ai
# または
yarn add headroom-ai

これでheadroomを使用する準備が整いました。

基本的な使い方

headroomは、用途に応じていくつかのモードで利用できます。ここでは、最低限これだけ知っていれば使える基本的なコマンドと、その役割について説明します。

1. 圧縮効果の確認: `headroom perf`

まず、headroomがどれほどの圧縮効果をもたらすかを確認しましょう。このコマンドは、サンプルデータに対して圧縮を実行し、トークン削減率を表示します。

headroom perf

このコマンドを実行すると、以下のような出力が得られます。

# 例:
# 10,144 → 1,260 tokens — same FATAL found.
# Savings: 87.5%

これは、元の10,144トークンが1,260トークンに圧縮され、87.5%の削減が達成されたことを示します。この手軽な方法で、headroomの強力な効果を実感できます。

2. プロキシとして利用: `headroom proxy`

既存のアプリケーションのコードを変更することなく、headroomの圧縮機能を適用したい場合に最適です。アプリケーションのLLM呼び出し先をheadroomプロキシのポートに向けるだけで、透過的にトークンが圧縮されます。

headroom proxy --port 8787

このコマンドを実行すると、headroomはローカルのポート8787でプロキシサーバーとして起動します。あなたのアプリケーションがLLM API（例えばOpenAIのapi.openai.com）にリクエストを送る際、そのエンドポイントをhttp://localhost:8787に設定し、元のLLMエンドポイントをheadroomプロキシに伝えます。

例えば、Pythonのopenaiライブラリを使用している場合、環境変数でエンドポイントを上書きできます。

export OPENAI_API_BASE=http://localhost:8787/v1
export OPENAI_API_KEY=sk-... # 元のAPIキー

この設定により、openai.ChatCompletion.createなどの呼び出しがheadroomプロキシを経由し、トークンが圧縮されてから実際のOpenAI APIに転送されます。

3. エージェントをラップ: `headroom wrap`

特定のコーディングエージェント（Claude Code、Codex、Aider、Copilotなど）を使用している場合、headroom wrapコマンドで簡単に統合できます。

headroom wrap claude

このコマンドを実行すると、指定されたエージェントがheadroomの圧縮レイヤーを介して動作するように設定されます。エージェントの起動コマンドを直接変更する必要はありません。例えば、headroom wrap claudeを実行した後に通常通りClaude Codeエージェントを起動すると、そのエージェントからのLLM呼び出しが自動的に圧縮されます。

4. ライブラリとして利用: `from headroom import compress`

PythonやTypeScriptのコード内で、特定のメッセージやコンテキストを直接圧縮したい場合に便利です。

Pythonの例:

from headroom import compress

def send_to_llm(messages):
    # LLMに送信する前にメッセージを圧縮
    compressed_messages = compress(messages)
    print(f"Original tokens: {len(str(messages))} -> Compressed tokens: {len(str(compressed_messages))}")
    # ここでLLM APIにcompressed_messagesを送信
    # llm_client.chat.completions.create(messages=compressed_messages, ...)
    return compressed_messages

# 例えば、LangChainやLlamaIndexのメッセージリスト
long_context_messages = [
    {"role": "system", "content": "あなたは優秀なプログラマーです。"},
    {"role": "user", "content": "この大規模なログファイルから、致命的なエラーを特定してください。\n" + "a" * 5000}
]

compressed_output = send_to_llm(long_context_messages)
print(compressed_output)

この方法では、圧縮のタイミングと対象を細かく制御できます。

便利な使い方・応用例 3選

headroomは、単なるトークン圧縮ツールにとどまらず、LLM開発のさまざまな側面でその真価を発揮します。ここでは、実際の開発シーンに役立つ応用例を3つ紹介します。

応用例1: RAGシステムでのコンテキスト最適化

RAG（Retrieval-Augmented Generation）システムでは、外部の知識ベースから関連ドキュメントを検索し、その内容をプロンプトに含めてLLMに渡します。しかし、検索結果が大量になると、プロンプトのトークン数が膨大になりがちです。headroomは、RAGで取得したチャンクをLLMに渡す前に圧縮することで、この問題を解決します。

from headroom import compress
from typing import List, Dict

# 例えば、LlamaIndexやLangChainで取得したRAGチャンクのリスト
def get_retrieved_chunks(query: str) -> List[Dict]:
    # 実際にはここで検索ロジックが実行され、関連チャンクが取得される
    return [
        {"type": "document", "content": "RAGシステムは、検索と生成を組み合わせたAIモデルです。" + "a" * 1000},
        {"type": "log", "content": "ログエントリー: 2023-10-27 FATAL: データベース接続エラー。" + "b" * 800},
        {"type": "code", "content": "def calculate_sum(a, b):\n    return a + b\n" + "# 複雑な関数定義" * 50},
    ]

def process_rag_query(user_query: str):
    retrieved_chunks = get_retrieved_chunks(user_query)

    # チャンクをheadroomで圧縮
    compressed_chunks = [compress([{"role": "system", "content": chunk["content"]}]) for chunk in retrieved_chunks]

    # 圧縮されたチャンクとユーザーの質問を組み合わせて最終プロンプトを作成
    final_messages = [
        {"role": "system", "content": "以下の情報に基づいて質問に答えてください。"},
    ]
    for chunk in compressed_chunks:
        final_messages.extend(chunk) # 圧縮後のメッセージ形式に合わせる
    final_messages.append({"role": "user", "content": user_query})

    # ここでLLMにfinal_messagesを送信
    print(f"RAGシステムに送信される最終プロンプト (一部圧縮済み):\n{final_messages}")
    # llm_client.chat.completions.create(messages=final_messages, ...)

# 実行例
process_rag_query("データベース接続エラーの解決策について教えてください。")

この例では、各チャンクを個別に圧縮し、それらを最終プロンプトに組み込んでいます。これにより、RAGの精度を維持しつつ、トークンコストを大幅に削減できます。

応用例2: コードエージェントのログ・出力削減

コーディングアシスタントやエージェントは、デバッグ情報、コンパイルエラー、テスト結果など、大量のログやツール出力をLLMに送ることがよくあります。headroomの出力トークン削減機能は、これらの冗長な情報をトリミングし、LLMが「書く」トークンも最適化します。

# 例えば、Aiderというコーディングエージェントを使用している場合
# 通常の起動方法
# aider

# headroomでラップして起動する場合
headroom wrap aider

headroom wrapコマンドは、エージェントが生成する出力（LLMが記述するコードや思考プロセスなど）もheadroomが分析し、定型的な部分や冗長な思考ステップを削減するように設定します。これにより、LLMからの応答がより簡潔になり、出力トークン数も削減されます。エージェントの既存のワークフローに最小限の変更で、大きな効果を得られます。

応用例3: クロスエージェントメモリによる重複排除と学習

headroomは、異なるエージェント間で共有されるメモリストアを持つことができます。これにより、複数のエージェントが同じコンテキストを参照する場合に、重複した情報の送信を回避し、より効率的なトークン利用が可能です。さらに、headroom learn機能は、失敗したセッションから学習し、将来の圧縮を改善します。

例えば、複数の開発エージェントが同じプロジェクトリポジトリの異なる部分で作業しているとします。各エージェントはそれぞれのリポジトリの構造や共通ライブラリの情報をLLMに送る必要がありますが、これらの情報は多くの場合重複します。headroomのクロスエージェントメモリは、これらの共通情報を一度だけLLMに送るように調整し、その後の参照は圧縮された形式で行います。

また、headroom learnコマンドを実行することで、過去のセッションデータ（例えば、LLMが誤った回答をしたプロンプトとレスポンス）を分析し、より効果的な圧縮戦略やコンテキストの優先順位付けを学習させることができます。学習結果は、CLAUDE.mdやAGENTS.mdといったファイルに書き込まれ、headroomの動作に反映されます。

# 過去のセッションから学習し、圧縮戦略を改善
headroom learn

この学習プロセスにより、headroomは時間とともにさらに賢くなり、あなたの特定のユースケースに最適化された圧縮を提供します。

他ツールとの組み合わせ

headroomは、既存のLLM開発ツールやフレームワークとシームレスに連携できるように設計されています。ここでは、相性の良いツールと組み合わせ方を紹介します。

1. LangChain / LlamaIndex

これらのフレームワークは、LLMアプリケーション開発のデファクトスタンダードとも言えます。RAG、エージェント、チェーンなど、複雑なワークフローを構築する際にheadroomを組み込むことで、トークン効率を劇的に向上させられます。

組み合わせ方: LangChainやLlamaIndexでは、LLMへの最終的なプロンプト（messages）が構築される直前に、headroomのcompress関数を適用します。

from langchain_core.messages import HumanMessage, SystemMessage
from headroom import compress
from openai import OpenAI # 例としてOpenAIクライアントを使用

# 通常のLangChainメッセージリスト
raw_messages = [
    SystemMessage(content="あなたは優秀なAIアシスタントです。以下の情報に基づいて質問に答えてください。\n" + "a" * 2000),
    HumanMessage(content="このコードスニペットの問題点を指摘してください。\n" + "def buggy_function():\n    x = 1\n    y = 0\n    return x / y\n" + "b" * 1500)
]

# headroomでメッセージを圧縮
# LangChainのMessageオブジェクトを直接compress()に渡すことはできないため、辞書形式に変換
messages_as_dict = [{"role": msg.type, "content": msg.content} for msg in raw_messages]
compressed_messages_dict = compress(messages_as_dict)

# 圧縮されたメッセージを再度LangChainのMessageオブジェクトに変換（必要であれば）
# または、直接OpenAIクライアントに渡す
# compressed_langchain_messages = [
#     SystemMessage(content=compressed_messages_dict[0]['content']),
#     HumanMessage(content=compressed_messages_dict[1]['content'])
# ]

# LLMに送信
client = OpenAI()
try:
    response = client.chat.completions.create(
        model="gpt-4", # 圧縮されたトークンでも高性能モデルを利用しやすくなる
        messages=compressed_messages_dict
    )
    print(f"LLMからの応答: {response.choices[0].message.content}")
except Exception as e:
    print(f"LLM呼び出しエラー: {e}")

print(f"元のトークン数（概算）: {len(str(raw_messages))}")
print(f"圧縮後のトークン数（概算）: {len(str(compressed_messages_dict))}")

この方法で、LangChainやLlamaIndexが生成する複雑なプロンプトもheadroomで最適化できます。

2. 開発エージェント (Aider, Cursor, Copilot)

これらのコーディングアシスタントは、開発者の生産性を高めますが、裏側では大量のコード、ログ、コンテキストをLLMに送っています。headroom wrapコマンドを使えば、これらのエージェントのトークン効率を簡単に改善できます。

組み合わせ方: エージェントを起動する前に、単にheadroom wrapコマンドを付け加えるだけです。

# 例えば、Aiderをheadroom経由で起動
headroom wrap aider

# 例えば、Claude Codeをheadroom経由で起動
headroom wrap claude

これにより、エージェントがLLMとやり取りする際のすべてのプロンプトがheadroomによって自動的に圧縮されます。

3. Docker / Kubernetes

コンテナ化された環境でLLMアプリケーションをデプロイする場合、headroomをサイドカーコンテナとして、またはアプリケーションコンテナ内に組み込むことで、スケーラブルなトークン最適化を実現できます。

組み合わせ方:

サイドカープロキシ: アプリケーションコンテナの隣にheadroomプロキシを起動するコンテナを配置します。アプリケーションからのLLMリクエストは、まずサイドカーのheadroomプロキシを経由するように設定します。
アプリケーションに組み込み: アプリケーションのDockerイメージ内にheadroomライブラリをインストールし、コード内でcompress関数を直接呼び出します。

どちらの方法も、アプリケーションのポータビリティを維持しつつ、headroomのメリットを享受できます。

よくある設定・カスタマイズ

headroomは、様々な環境変数や設定ファイルを通じて、その動作を細かくカスタマイズできます。

1. 環境変数による設定

headroomの動作は、特定の環境変数を設定することで調整できます。

HEADROOM_EMBEDDER_RUNTIME: 埋め込みモデルの実行環境を指定します。
- pytorch_mps: Apple Silicon MacのGPU (MPS) を利用して、埋め込み処理を高速化します。GPUメモリのオフロードに役立ちます。

export HEADROOM_EMBEDDER_RUNTIME=pytorch_mps

HEADROOM_CACHE_DIR: 圧縮されたオリジナルデータがキャッシュされるディレクトリを指定します。デフォルトは一時ディレクトリなどです。

export HEADROOM_CACHE_DIR=/path/to/my/headroom_cache

HEADROOM_PROXY_TARGET: プロキシモードで実行する際に、リクエストを転送する実際のLLM APIエンドポイントを指定します。

export HEADROOM_PROXY_TARGET=https://api.openai.com/v1

2. 学習結果ファイル (`CLAUDE.md`, `AGENTS.md`)

headroom learnコマンドを実行すると、過去の失敗セッションやコンテキストの利用状況に基づいて、headroomの圧縮戦略を改善するための情報が生成されます。これらの情報は、CLAUDE.mdやAGENTS.mdのようなファイルに書き込まれます。

# CLAUDE.md (例)
# このファイルはheadroom learnによって生成されます。
# 以下のパターンは、特定のコンテキストを圧縮する際の優先度や除外ルールを定義します。

[context_patterns]
# ログファイルから特定のWARNレベルのメッセージは常に保持する
- pattern: "WARN: (.*)"
  action: "keep_uncompressed"

# 冗長なスタックトレースは積極的に圧縮する
- pattern: "Traceback (most recent call last):"
  action: "aggressive_compress"

[agent_specific_rules]
# Claudeエージェントは、特定の定型的な応答を省略する
- agent: "claude"
  output_trim_patterns:
    - "Okay, I will do that."
    - "Let's think step by step."

これらのファイルは、headroomがLLMとの対話から学習し、より賢く振る舞うための設定として機能します。手動で編集することも可能ですが、基本的にはheadroom learnに任せるのが良いでしょう。

3. Pythonライブラリのオプション引数

compress関数をライブラリとして使用する場合、より詳細な圧縮戦略を引数で指定できます。

from headroom import compress, CompressionStrategy

# 特定の圧縮戦略を指定
# 例えば、よりアグレッシブな圧縮を試みる場合
messages = [{"role": "user", "content": "非常に長いテキストデータ" * 100}]
compressed_messages = compress(messages, strategy=CompressionStrategy.AGGRESSIVE)

# コンテンツの種類を明示的に指定して、特定のコンプレッサーを強制する
# 例えば、JSONとして圧縮したい場合
json_data = [{"id": 1, "name": "item_a", "details": "長い説明" * 50}]
compressed_json = compress(json_data, content_type="json")

print(f"アグレッシブ圧縮後のメッセージ: {compressed_messages}")
print(f"JSON圧縮後のデータ: {compressed_json}")

CompressionStrategyには、DEFAULT、AGGRESSIVE、BALANCEDなどのオプションが用意されています。また、content_type引数でjson、code、textなどを指定することで、ContentRouterの自動検出を上書きできます。

これらの設定とカスタマイズを活用することで、あなたの特定のLLMアプリケーションやワークフローにheadroomを最適化し、最大の効果を引き出せます。

今日からできる実行プラン

headroomの導入は、たった3つのステップで始められます。今すぐトークンコストの削減とLLM応答の高速化を体験しましょう。

Step 1: インストールと基本動作確認

まずはheadroomをインストールし、その効果を手軽に確認してみましょう。

Python環境の準備: Python 3.10以上がインストールされていることを確認し、推奨される仮想環境を作成・アクティブ化します。
```
python3.10 -m venv .venv
source .venv/bin/activate
```
headroomのインストール: すべての機能を含む[all]オプションでインストールします。
```
pip install "headroom-ai[all]"
```
圧縮効果の確認: headroom perfコマンドを実行し、headroomがどれほどのトークンを削減できるかを確認します。
```
headroom perf
```
この結果を見て、headroomがあなたの開発にもたらす潜在的なメリットを実感してください。

Step 2: プロキシモードでの試用

既存のLLMアプリケーションにコード変更なしでheadroomを適用し、その効果を確かめます。

headroomプロキシの起動: 新しいターミナルウィンドウを開き、headroomプロキシを起動します。
```
headroom proxy --port 8787
```
アプリケーションのLLMエンドポイント設定: 既存のLLMアプリケーションがOpenAI APIを使用している場合、LLM呼び出しのエンドポイントをheadroomプロキシに向けるように設定します。環境変数を使用するのが最も手軽です。
```
export OPENAI_API_BASE=http://localhost:8787/v1
export OPENAI_API_KEY=sk-... # あなたの実際のOpenAI APIキー
```
LangChainなどを使用している場合は、LLMクライアント初期化時にopenai_api_baseパラメータを設定します。
アプリケーションの実行: 設定を変更したアプリケーションを通常通り実行します。LLMへのリクエストがheadroomプロキシを経由し、自動的に圧縮されます。プロキシのターミナルには、圧縮のログが表示されるはずです。

Step 3: ライブラリモードでの統合

より細かくトークン圧縮を制御したい場合や、新しいアプリケーションを開発する際には、headroomライブラリを直接コードに組み込みます。

既存のLLM呼び出し箇所の特定: あなたのアプリケーション内で、LLMにプロンプト（メッセージリストなど）を送信している箇所を特定します。

compress関数のインポートと適用: LLMに送信する直前に、headroom.compress関数を使用してプロンプトを圧縮します。

from headroom import compress

# 元のメッセージ
messages_to_send = [
    {"role": "system", "content": "長大なシステムプロンプト..."},
    {"role": "user", "content": "詳細なユーザー入力..."}
]

# headroomで圧縮
compressed_messages = compress(messages_to_send)

# 圧縮されたメッセージをLLMに送信
# llm_client.chat.completions.create(messages=compressed_messages, ...)

効果の測定と最適化: 圧縮前後のトークン数やLLMの応答品質を比較し、必要に応じてcompress関数のstrategy引数やcontent_type引数を使って調整します。

これらのステップを踏むことで、今日からあなたのLLM開発にheadroomを導入し、より効率的でコスト効果の高いAIアプリケーションを構築できるようになります。

headroomの使い方完全ガイド【インストールから応用まで】

headroomの使い方完全ガイド【インストールから応用まで】

headroomとは

インストール方法

Pythonの場合

Node.js / TypeScriptの場合

基本的な使い方

1. 圧縮効果の確認: headroom perf

2. プロキシとして利用: headroom proxy

3. エージェントをラップ: headroom wrap

4. ライブラリとして利用: from headroom import compress

便利な使い方・応用例 3選

応用例1: RAGシステムでのコンテキスト最適化

応用例2: コードエージェントのログ・出力削減

応用例3: クロスエージェントメモリによる重複排除と学習

他ツールとの組み合わせ

1. LangChain / LlamaIndex

2. 開発エージェント (Aider, Cursor, Copilot)

3. Docker / Kubernetes

よくある設定・カスタマイズ

1. 環境変数による設定

2. 学習結果ファイル (CLAUDE.md, AGENTS.md)

3. Pythonライブラリのオプション引数

今日からできる実行プラン

Step 1: インストールと基本動作確認

Step 2: プロキシモードでの試用

Step 3: ライブラリモードでの統合

参考文献

1. 圧縮効果の確認: `headroom perf`

2. プロキシとして利用: `headroom proxy`

3. エージェントをラップ: `headroom wrap`

4. ライブラリとして利用: `from headroom import compress`

2. 学習結果ファイル (`CLAUDE.md`, `AGENTS.md`)