Headroom 完全ガイド 2026：オープンソースツールで LLM トークンコストを 60-95% 削減

# フルバージョンをインストール（proxy、MCP、ML など全機能を含む）
pip install "headroom-ai[all]"

# または必要に応じてサブモジュールをインストール
pip install "headroom-ai[proxy]"   # プロキシモードのみ
pip install "headroom-ai[mcp]"     # MCP サーバーのみ
pip install "headroom-ai[ml]"      # 機械学習圧縮モデル

npm install headroom-ai

# バージョンと機能を確認
headroom --version

# パフォーマンステストを実行し、現在の環境での圧縮効果を確認
headroom perf

# Claude Code をラップ
headroom wrap claude

# Codex をラップ
headroom wrap codex

# Cursor をラップ
headroom wrap cursor

# Aider をラップ
headroom wrap aider

# GitHub Copilot CLI をラップ
headroom wrap copilot

$ headroom wrap claude

✅ Headroom proxy started on port 8787
✅ Claude Code config updated

To verify, run:
  claude "What is 2+2?"

You should see compression stats in the output.

# プロキシを起動、ポート 8787 でリッスン
headroom proxy --port 8787

from openai import OpenAI

# 元の設定
# client = OpenAI(api_key="sk-...")

# Headroom プロキシ経由に変更
client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:8787/v1"  # Headroom プロキシを指す
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "このコードを説明して"}]
)

from headroom import compress

messages = [
    {"role": "user", "content": "このログファイルを分析して"},
    {"role": "assistant", "content": "ログ内容を提供してください"},
    {"role": "user", "content": "[... 10000 行のログ ...]"}
]

# メッセージを圧縮
compressed = compress(messages, model="claude-3-sonnet")

print(f"元トークン: {compressed.original_tokens}")
print(f"圧縮後トークン: {compressed.compressed_tokens}")
print(f"節約: {compression.savings_percent}%")

# LLM に送信
response = anthropic_client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1024,
    messages=compressed.messages  # 圧縮後のメッセージを使用
)

import { compress } from 'headroom-ai';

const messages = [
  { role: 'user', content: 'Analyze this codebase' },
  { role: 'assistant', content: 'Please provide the files' },
  { role: 'user', content: '[... 50 files ...]' }
];

const compressed = await compress(messages, { model: 'gpt-4' });

console.log(`Saved ${compressed.savingsPercent}% tokens`);

from headroom import SmartCrusher

data = {
    "users": [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-01-02"},
        # ... 1000+ レコード
    ]
}

crusher = SmartCrusher()
compressed = crusher.compress(data)

# キーフィールドを保持し、冗長なメタデータを削除
# 元: 50,000 トークン → 圧縮後: 5,000 トークン (90% 節約)

from headroom import CodeCompressor

code = """
def calculate_total(items):
    '''Calculate total price with tax'''
    total = 0
    for item in items:
        if item.active:
            total += item.price * item.quantity
    tax = total * 0.08
    return total + tax
"""

compressor = CodeCompressor(language="python")
compressed = compressor.compress(code)

# 関数シグネチャ、制御フロー、重要変数を保持
# コメント、空白、非重要な実装詳細を削除

# 初回使用時にモデルが自動ダウンロード（約 500MB）
headroom proxy

# モデルキャッシュ場所: ~/.cache/headroom/kompress-base

# 共有メモリを有効化
headroom wrap claude --memory
headroom wrap codex --memory

# MCP サーバーをインストール
headroom mcp install

# 利用可能な MCP ツール：
# - headroom_compress: 任意のコンテンツを圧縮
# - headroom_retrieve: 生データを取得
# - headroom_stats: 圧縮統計を表示

// claude_desktop_config.json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}

headroom wrap claude
claude "ユーザー認証モジュールの実装を見つけて"

# ステップ 1：Claude Code がスキャンしてキャッシュ
headroom wrap claude --memory
claude "src/auth/ ディレクトリのコード品質をレビューして"

# ステップ 2：Codex がキャッシュを再利用
headroom wrap codex --memory
codex "src/auth/ のユニットテストを生成して"
# Codex は Claude のキャッシュ済みインデックスを直接使用、再スキャン不要

# ステップ 3：Cursor が引き続き再利用
headroom wrap cursor --memory
cursor "src/auth/ のエラーハンドリングをリファクタリングして"

from headroom import compress
import anthropic

# ログを読み込む
with open("production.log") as f:
    logs = f.read()

messages = [
    {"role": "user", "content": f"このログを分析してエラー原因を見つけて:\n{logs}"}
]

# 圧縮
compressed = compress(messages, model="claude-3-sonnet")

print(f"元: {compressed.original_tokens} トークン")
print(f"圧縮後: {compressed.compressed_tokens} トークン")
print(f"節約: {compressed.savings_percent}%")

# 送信
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=2048,
    messages=compressed.messages
)

print(response.content[0].text)

python -m headroom.evals suite --tier 1

from headroom import CompressionMiddleware

# ASGI アプリにミドルウェアを追加
app.add_middleware(CompressionMiddleware)

# 学習モードを有効化
headroom wrap claude --learn

# Claude Code が誤った答えを出した場合、Headroom は：
# 1. 失敗原因を分析
# 2. 修正プロンプトを生成
# 3. プロジェクトの CLAUDE.md に書き込み
# 4. 次回セッションで自動的に修正を適用

from headroom import PipelineExtension

class MyCustomCompressor(PipelineExtension):
    def on_input_received(self, event):
        # 入力受信時にカスタムロジックを実行
        print(f"Received {len(event.content)} bytes")

    def on_input_compressed(self, event):
        # 圧縮完了後に実行
        print(f"Compressed to {event.compressed_size} bytes")

# 拡張を登録
pipeline.register(MyCustomCompressor())

pip install "headroom-ai[all]"
headroom wrap claude  # または使用している任意の Agent
headroom perf         # 節約効果を確認