Headroom チュートリアル：Claude Code、Codex、AI Agent のコンテキストを節約する

chopratejas/headroom は、AI エージェントのコンテキスト圧縮のためのツールです。これによって解決される問題は非常に現実的です。エージェントがコマンドを実行し、ログを読み取り、コードを検索し、RAG フラグメントを詰め込んでいる間、すぐにコンテキストウィンドウがいっぱいになり、コストと遅延が同時に増加します。

Headroom の背後にある考え方は、コンテンツが LLM に入る前に、ツール出力、ログ、ファイル、RAG クリップ、およびセッション履歴を圧縮することです。 README に記載されている目標は非常に単純です。回答の品質を維持しながら 60-95% トークンを削減するというものです。

それはどのような問題を解決しますか?

現在、多くのエージェントツールには十分にスマートではないモデルはありませんが、コンテキストがあまりにも汚いです。

grep、rg、ログクエリは一度に数百または数千の行を返します。
RAG 検索フラグメントは繰り返され、冗長で、フォーマットされています。
JSON、スタックトレース、および SQL 結果には、多数の低値フィールドがあります。
複数回のデバッグの後、古い出力がコンテキストを占有します。
Claude Code、Codex、Cursor、Aider などのツールはそれぞれコンテキストを維持するため、メモリの共有が困難になります。

ヘッドルームは「モデルに入る前のクリーナー」です。 LLM や RAG に代わるものではありませんが、LLM の前に圧縮、ルーティング、キャッシュ、および追跡可能な取得の層が追加されます。

コアコンピテンシー

README によると、Headroom にはいくつかの主な使用形式があります。

ライブラリ: Python または TypeScript で compress(messages) を直接呼び出します。
プロキシ: OpenAI 互換プロキシとして headroom proxy --port 8787 を使用します。
エージェントラップ: headroom wrap claude|codex|cursor|aider|copilot を使用して既存のエージェントをラップします。
MCP サーバー: MCP クライアントが使用する headroom_compress、headroom_retrieve、headroom_stats を提供します。
クロスエージェントメモリ: Claude、Codex、Gemini およびその他のツールがローカルメモリを共有し、重複を自動的に削除します。
headroom learn: 失敗したセッションから経験を掘り起こし、CLAUDE.md または AGENTS.md と書き込みます。
可逆圧縮: 元のテキストは削除されず、必要に応じて検索ツールを通じて取得できます。

これらの形式は非常に重要です。コードに埋め込むことしかできない SDK ではなく、プロキシとしてのみ使用することもできません。最も軽いラップモードから始めて、それを独自のアプリケーションに統合するかどうかを決定できます。

どのように圧縮するのでしょうか?

Headroom の構造にはいくつかのキーワードがあります。

ContentRouter: コンテンツタイプを識別し、対応するコンプレッサーを選択します。
SmartCrusher: JSON などの構造化コンテンツの処理を好みます。
CodeCompressor: コードと AST の処理を優先します。
Kompress-base: テキスト圧縮に使用されます。
CacheAligner: プロンプトプレフィックスをより安定させ、プロバイダーの KV キャッシュヒット率を向上させます。
CCR: 元のテキストを保存し、必要に応じて取得を通じて取得します。

人間の言葉で言えば、すべてのコンテンツを大まかに 1 つの段落に要約するのではなく、最初にコンテンツタイプを決定し、次にさまざまな圧縮戦略を選択します。コード、JSON、プレーンテキスト、ログ、RAG フラグメントは、同じ方法で圧縮しないでください。

クイックインストール

README に記載されているインストール方法は非常に簡単です。

1
2


pip install "headroom-ai[all]"
npm install headroom-ai

Python 側には Python 3.10+ が必要です。インストール後、まず次のコマンドを試してください。

1
2
3


headroom wrap claude
headroom proxy --port 8787
headroom perf

MCP クライアントを使用している場合は、次のようにできます。

1

headroom mcp install

効果を確認したいだけの場合、最も簡単な方法は、最初に headroom perf を実行して、一般的なワークロードで節約できるトークンの数を確認することです。利用可能であることを確認したら、Claude Code、Codex、Cursor、または独自の OpenAI 互換クライアントに接続します。

と通常の要約の違いは何ですか?

通常の要約の最大の問題は、それらが元に戻せないことです。ログは「データベース接続に失敗しました」として要約され、元のエラーコード、タイムスタンプ、コールスタック、コンテキストは表示されません。エージェントが後で詳細が必要になった場合は、再度確認するだけです。

Headroom の重要なポイントの 1 つは可逆的です。元のコンテンツはローカルに保存され、圧縮されてモデルに渡されます。モデルが元のテキストを必要とする場合、headroom_retrieve を通じて取得されます。この設計は、デバッグ、コード検索、実稼働ログ分析により適しています。これらのシナリオでは詳細に戻る必要があることが多いためです。

もちろん、これはローカルストレージとプライバシーの境界を管理する必要があることも意味します。 README ではローカルファーストを強調していますが、圧縮コンテンツをクラウドモデルに送信する限り、独自のデータセキュリティ要件に従って処理する必要があります。

どのシナリオが適していますか?

Headroom は次のシナリオに最適だと思います。

Claude Code、Codex、および Cursor は、ツールの出力が長すぎるため、速度が低下することがよくあります。
エージェントを使用して大規模なウェアハウス、検索結果、ファイルの断片を分析すると、コンテキストが簡単に爆発します。
トラブルシューティングを行う場合、SRE はログ、トレース、構成、およびコマンド出力をモデルに表示する必要があります。
RAG アプリケーションを実行すると、検索結果が非常に冗長になります。
複数のエージェントツール間でローカルメモリを共有したい。
MCP ツールを既存の AI ワークフローに統合したい。

時々数回のチャットを要求するだけの場合、またはプロンプトが非常に短い場合は、必ずしも必要ありません。 Headroom の値は主に「エージェントが実際に作業を行っている」ときに現れます。

使用する際の注意点は何ですか?

コンテキスト圧縮は魔法ではありません。トークンを節約できますが、新たな問題が発生する可能性もあります。

圧縮戦略が不適切な場合、モデルは主要な詳細を取得できない可能性があります。
コードとログのシナリオでは、取得が信頼できるかどうかをテストする必要があります。
プロキシモードを受け入れる場合、リクエストがどのローカルリンクとクラウドリンクを通過するかを確認します。
チームで使用する場合、ローカルキャッシュ、セッション記録、機密データ保持ポリシーを定義する必要があります。
トークンの節約だけでなく、タスクの完了率や誤判断率にも注目してください。

私の提案は、デモを見るだけではなく、実際のタスクでテストすることです。たとえば、一連の履歴バグ、CI ログ、RAG クエリ、およびコード検索タスクを取得し、「モデルに直接フィードする」場合と「ヘッドルームを通過する」場合のコスト、速度、応答品質をそれぞれ比較します。

＃＃まとめ

ヘッドルームは典型的な「コンテキストエンジニアリング」ツールです。これはエージェントを再作成しようとするのではなく、エージェントと LLM の間に立って、元のテキストを取得する機能を保持しながら、モデルに入るコンテンツをクリーニングして短縮します。

これは、Claude Code、Codex、Cursor、Aider、Copilot CLI、または MCP ツールをすでに使用しているユーザーに適しています。「モデルのコンテキストがログやツールの出力によって圧倒されることが多い」という問題点がある場合は、ヘッドルームを試してみる価値があります。モデルの機能が不十分であるだけの問題の場合、コンテキストを圧縮するだけでは必ずしも解決するとは限りません。

Claude Code 本体のトークンとキャッシュ最適化

Prompt Cacheは文字列そのものをキャッシュしない

Prompt Cacheは、プロンプト文字列をそのまま保存するだけの仕組みではない。Transformerモデルでは、前方のコンテキストを注意層で計算したKey/Value状態、つまりKV cacheが重要になる。

これは2つのことを意味する。

前方のコンテキストが安定していれば、後続リクエストで一部の計算結果を再利用できる。
モデル、ツール定義、システムプロンプト、前方メッセージが変わると、以前のキャッシュを再利用できないことがある。

Anthropic公式ドキュメントも、失効階層を tools -> system -> messages と整理している。ツール定義の変更は全体のキャッシュに影響し、system層の変更はsystemとmessagesに影響し、messages層の変更は主にメッセージキャッシュに影響する。

Claude Codeではさらに CLAUDE.md、Skills、MCP、プラグイン、subagentなどが関わるため、実際の利用ではキャッシュ失効点を踏みやすい。

キャッシュを壊す要因1：途中でモデルを切り替える

モデル切り替えは最も影響が大きい操作の一つだ。

Prompt Cacheはモデルごとに分離される。Opus、Sonnet、Haikuは構造や重みが異なるため、同じテキストから計算したKV cacheも共有できない。Opusで長いコンテキストを作ったあとSonnetへ切り替えても、SonnetはOpusのキャッシュを再利用できない。

そのため、節約のつもりで途中から安いモデルへ切り替えると、かえってそれまでのキャッシュが無駄になることがある。本来cache read価格で読めたコンテキストが、再度書き込みと計算の対象になる。

安定したやり方は次の通り。

メイン会話ではモデルを固定する。
安いモデルで処理したい支線タスクはsubagentに分離する。
支線エージェントに検索、探索、整理を任せ、要約だけをメイン会話へ戻す。

こうするとメインの長いコンテキストを動かさず、キャッシュ命中率を保ちやすい。

キャッシュを壊す要因2：途中でMCPを追加する、プラグインを再読み込みする

MCPはClaude Codeへツールを提供する。新しいMCPサーバーを追加するとツール一覧が変わる。ツール定義はコンテキスト鎖の最も左側にある。

Prompt Cacheの視点では、ツール一覧が変わると、その後ろのsystemとmessagesも再計算が必要になりやすい。MCPが多い場合、ツール定義そのものが多くのTokenを占めるため、失効コストは大きくなる。

ただし重要な細部がある。Claude Codeは通常、セッション起動時にMCP設定を読む。途中で設定を変えても現在のsessionにすぐ影響するとは限らない。本当に注意すべきなのは、再起動、resume、プラグイン再読み込み、ツール一覧の再構築が起きる場面だ。

おすすめは：

長いタスクの前に必要なMCPをまとめて用意する。
作業中に不足に気づいてインストールし、再読み込みする流れを避ける。
大きなMCPツールセットは必要時だけ使う、またはデフォルト有効数を減らす。
ほとんど使わないMCPを常時有効にしない。

ツール定義が安定していてこそ、Prompt Cacheは安定して命中する。

キャッシュを壊す要因3：途中でCLAUDE.mdを編集する

CLAUDE.mdはClaude Codeのプロジェクト記憶ファイルだ。ビルドコマンド、テストコマンド、設計上の約束、コードスタイル、プロジェクト固有の注意点を書くのに向いている。

便利だが、これもコンテキストに入る。Claudeのヘルプでは、CLAUDE.mdはセッション開始時に読まれ、ユーザーメッセージとしてClaudeへ渡されると説明されている。またAnthropicのPrompt Cacheも使われる。最初のリクエストでは通常の入力価格を払い、以後キャッシュが有効なら低いcache readコストで処理される。

問題は、CLAUDE.mdが内容で識別されることだ。ファイル内容を変えると、旧キャッシュとは一致しない。

そのため、長いタスクの途中で頻繁にCLAUDE.mdを編集しないほうがよい。より良い使い方は：

タスク開始前にCLAUDE.mdが十分か確認する。
安定したルールはファイルへ、臨時指示は現在の会話へ置く。
一度だけの要望のために長期記憶ファイルを編集しない。
どうしても変更するなら、次の段階を新しいsessionや新しいフェーズとして扱う。

CLAUDE.mdは安定したプロジェクト説明であり、毎回変えるメモ帳ではない。

キャッシュを壊す要因4：途中でSkillsをインストールまたは更新する

Skillsもコンテキストの一部だ。新しいSkillを入れる、Skillを更新する、Skill一覧が変わると、セッションへ注入されるコンテキストも変わる。

こうした変化は、reload、resume、新しいsessionで反映されることが多い。messagesが再構築されると、古いキャッシュは命中しにくくなる。

MCPと同じく、次のように扱うとよい。

タスク開始前に必要なSkillsを決める。
同じ種類のタスクではSkillセットを固定する。
長いタスクの途中でSkillsを追加しない。
新しいSkillを入れたら、新しい段階の始まりとして扱う。

コンテンツ作成、レビュー、デプロイ、翻訳など反復する作業では、よく使うSkillsを固定するとコンテキスト構造が安定する。

キャッシュを壊す要因5：TTLを超えてアイドルになる

Prompt Cacheは永久に保存されない。一般的なデフォルト有効期間は数分程度で、Claude Code関連の説明でも約5分のキャッシュウィンドウが言及されることがある。TTLを過ぎると、同じリクエストでもサーバー側でキャッシュが消えている可能性がある。

長いタスクで「さっきまで安かったのに、少し離席したらTokenが増えた」と感じる原因はこれだ。

Claude Codeの出力を読む、ファイルを確認する、テストを走らせる、次の手を考える。こうした作業だけで5分はすぐ過ぎる。

環境が対応しているなら、長いタスクの前に1時間のPrompt Cache TTLを有効化できる。

1

export ENABLE_PROMPT_CACHING_1H=1

Windows PowerShellでは：

1

$env:ENABLE_PROMPT_CACHING_1H="1"

1時間キャッシュの書き込みコストは、通常5分キャッシュより高くなる。短いタスクには向かないこともあるが、大規模コードベース、長い会話、複雑な多段階開発では、頻繁にキャッシュが切れるより安くなる場合がある。

Tokenを節約しやすいClaude Code長タスクの組み方

安定した流れはこうだ。

タスク開始前にモデルを決め、頻繁に切り替えない。
必要なMCPを有効にし、不要なMCPは切る。
CLAUDE.mdは短く、安定した、長期的に有効なルールに絞る。
今回必要なSkillsを事前に準備する。
複雑なタスクでは1時間TTLを検討する。
大きなタスクは段階に分けるが、各段階の内部ではコンテキスト構造を安定させる。
支線探索はsubagentや別sessionで行い、メイン会話を汚さない。

目的はすべてのキャッシュミスをなくすことではない。見落としやすく、コストの高い失効を避けることだ。

簡単な判断基準

次の一文で判断できる。

この操作はモデル、ツール定義、システムコンテキスト、またはセッション冒頭の固定メッセージを変えるか？

答えがはいなら、Prompt Cacheに影響する可能性が高い。コンテキスト鎖の左側に近いほど影響は大きい。

よくある操作はこう整理できる。

モデル切り替え：高リスク。モデルごとにキャッシュが分離される。
MCP追加またはプラグイン再読み込み：高リスク。ツール一覧が変わる。
CLAUDE.md編集：中高リスク。プロジェクト記憶が変わる。
Skillsインストール：中高リスク。注入コンテキストが変わる。
通常の会話継続：低リスク。主にmessagesを追加するだけ。
TTL超過のアイドル：高リスク。サーバー側キャッシュが期限切れになる。

まとめ

Claude CodeのPrompt Cache最適化で大事なのは、パラメータを暗記することではなく、sessionの前方コンテキストを安定させることだ。

モデルを気軽に切り替えない。MCPやSkillsを作業途中で増やさない。CLAUDE.mdを臨時メモとして頻繁に編集しない。複雑なタスクではTTL延長を検討する。これらを守るだけで、長いタスクのTokenコストと応答速度はかなり予測しやすくなる。

実用的な一言にすると、始める前に整え、始めた後はあまり動かさない。

よくある質問

このプロジェクトは何ですか？

この記事で紹介している AI ツール系プロジェクトで、何ができるか、どう使うか、どんな場合に試す価値があるかを整理しています。

誰に向いていますか？

README を読むだけでなく、実際のワークフローに接続したい開発者や AI ツール利用者に向いています。

使う前に何を確認すべきですか？

インストール方法、対応ツール、データと権限の境界、プロジェクトの更新頻度を確認してください。

本番利用に向いていますか？

まず小さなワークフローで検証し、挙動を確認してから機密性の高い作業や本番タスクに使うべきです。

参考ソース

chopratejas/ヘッドルーム - GitHub