Claude Code 利用を約4倍：Headroom MCP 予算最適化（2026-06-04）

実リポで Claude Code を回すインディー開発者なら分かる痛み：grep、テストログ、MCP ツール出力が毎回コンテキストに戻り、Anthropic は入出力トークン課金。Headroom（Apache 2.0、2026年中 GitHub 1万+スター）はモデル前にツール出力・ログ・ファイル・RAG チャンクをローカル圧縮。公開 workload で 60–95% トークン削減、README デモではログの FATAL 検索が 10,144 → 1,260 トークンで同答えと主張。

本稿は headroom wrap claude と MCP サーバー の実請求計算＋セットアップ—Claude 置換の誇大広告ではなく、一度見た stderr メガバイトにフル運賃を払うのをやめる話。

エンジニアリング repo で Claude Code 予算が燃える理由

Claude Code の強み—エンジニアのように repo を読む—がメーターでもある：

• ツール出力インフレ — 大規模モノレポで bash・検索・MCP が1ターン 1万–8万トークン。
• 再送コンテキスト — 圧縮なしで旧ツール塊がスレッドに残り、45分リファクタで費用が複利。
• MCP スプロール — 各サーバーが JSON を追加；うるさいツール3つで入力トークンが倍。

ハーネス選定中なら Codex CLI vs Claude Code ベンチ と 2026 エージェント比較—本稿は Claude Code 済みでマージンを取り戻す方向。

アーキテクチャ — Headroom の位置

Claude Code (or Cursor / Codex via wrap) │ tool calls · logs · file reads ▼ ┌──────────────────────────────────────┐ │ Headroom (local — Python 3.10+) │ │ CacheAligner → ContentRouter → CCR │ │ SmartCrusher (JSON) │ │ CodeCompressor (AST) │ │ Kompress-base (text) │ │ MCP: compress · retrieve · stats │ └──────────────────────────────────────┘ │ compressed context + retrieve tool ▼ Anthropic API (Claude)

• CCR（可逆） — 原文はローカル保存；モデルは headroom_retrieve で逐語取得可。
• MCP モード — headroom_compress、headroom_retrieve、headroom_stats を任意 MCP クライアントへ。
• プロキシモード — headroom proxy --port 8787、OpenAI 互換クライアントはコード変更ゼロ。

公式: headroom-docs.vercel.app · ソース: github.com/chopratejas/headroom。

請求比較マトリクス — 公開 workload vs「素の Claude Code」

Headroom 公開の前後表は計画数字—repo を保証しません。自分の $/MTok を掛けてドル化。

示意月次計算（仮定）

Sonnet 級 ~$3/MTok 入力 と仮定（Anthropic 現行ページ要確認）：

タイトルの 4倍利用 は ドル予算一定 で平均約75%節約 ≈ 同額で約4倍ターン—無制限ではない。

シナリオ A — headroom wrap claude（最短ルート）

向いている人：ターミナルで毎日 Claude Code（Mac/Linux）；MCP.json を触らない。

# Python 3.10+ required pip install "headroom-ai[all]" # One-command wrap (starts compression + optional memory) headroom wrap claude # After a session, inspect savings headroom perf

変わる点： Headroom が API 前にツール出力とコンテキストを横取り。UX はそのまま；裸 claude ではなく wrap で起動。

もし X なら Y： もし レンタル Mac で obra Superpowers 済みなら、なら 同一ホストに Headroom — obra Superpowers セットアップ；Headroom は直交（圧縮 vs 手順）。

シナリオ B — Claude Code + カスタムツール向け MCP

向いている人：MCP を厳選し compress/retrieve を第一級ツールにしたいチーム。

pip install "headroom-ai[mcp]" # Install MCP config for supported clients headroom mcp install

Claude Code MCP 設定（典型—最新ドキュメントで確認）：

{ "mcpServers": { "headroom": { "command": "headroom", "args": ["mcp", "serve"] } } }

得られる MCP ツール：

もし X なら Y： MCP が巨大 JSON を返すなら、Claude が要約する前に Headroom 経由。

シナリオ C — 混合スタック向けプロキシ

headroom proxy --port 8787 # Point OpenAI-compatible clients at http://127.0.0.1:8787

Claude Code と並行で Codex、Aider、スクリプト を回し、圧縮を一層にまとめたいとき。

ステップ・ランブック — 最初の有効な1時間

1. インストール — pip install "headroom-ai[all]"。
2. ベースライン — Headroom なしで1タスク；Anthropic で入力トークンを記録。
3. wrap 有効化 — headroom wrap claude；同じタスクを繰り返す。
4. 比較 — headroom perf；検索/ログ重いタスクで最大。
5. MCP（任意）— headroom mcp install。
6. 期待値 — 探索型は ~47%。
7. CCR ドリル — headroom_retrieve で可逆性確認。
8. スキップ — CI に Python なし；レンタル Mac で proxy。

トラブルシュート

headroom wrap claude が Claude Code を起動しない

症状： command not found: claude。
対処： Claude Code CLI；wrap 前に which claude。

小ファイルで節約がほぼ 0%

大 repo で rg または CI ログで試す。

圧縮後にモデルが詳細を見落とし

headroom_retrieve（CCR）で原文を取得。

MCP headroom が赤

headroom mcp serve の stderr を確認。

推奨パス

FAQ

Related reading

• Codex CLI vs Claude Code ベンチ
• obra Superpowers セットアップ
• 2026 AI エージェント比較