Claude-thermos: Claude Code におけるプロンプトキャッシュの期限切れ防止

Claude-thermos はプロンプトキャッシュのウォーム状態を維持することで API コストを削減します

claude-thermos は、Claude Code セッションにおける「キャッシュ税」を排除するために設計されたユーティリティです。メインエージェントがサブエージェントによって5分以上ブロックされたときに、プロンプトキャッシュがサイレントに失効するのを防ぎます。この失効は、ユーザーの総 API 料金の約20%を占める可能性があります。

問題点: サブエージェント実行中のキャッシュ失効

Claude Code のプロンプトキャッシュには、5分間の Time-to-Live (TTL) があります。キャッシュされた履歴は入力価格の 0.1x で提供されますが、キャッシュミスが発生すると、会話履歴のフル再エンコードが 1.25x の書き込みレートで行われます。これは、個別の崩壊（collapses）が 200K から 500K トークンを再書き込みする可能性がある長いセッションでは、非常に高価になります。

キャッシュ失効の主なトリガーは、ユーザーの非アクティブさではなく、サブエージェントの動作です。サブエージェントは異なるシステムプロンプトとツールセットを使用するため、異なるキャッシュプレフィックスを作成します。サブエージェントが実行されている間、メインエージェントのキャッシュプレフィックスは手つかずのままです。サブエージェントのタスクが5分以上かかると、メインエージェントのキャッシュが失効します。サブエージェントがメインエージェントに制御を戻したとき、メインエージェントは履歴全体を再エンコードする必要があり、多大なコストが発生します。

claude-thermos がキャッシュを維持する方法

claude-thermos は、ANTHROPIC_BASE_URL をループバックポートに向けることで、ローカルリバースプロキシとして動作します。以下の4つのステップでキャッシュを管理します：

1. Observation (観測): プロキシは /v1/messages トラフィックを監視し、リクエストをセッションと「リネージ」（モデル、ツールセット、システムテキストによって定義）にグループ化します。ツールを持つ最初のリネージをメインエージェントとして特定します。
2. Detection (検知): メインのリネージがアイドル状態である一方で、サブエージェントがアクティブに実行されている「危険なウィンドウ」を特定します。
3. Warming (ウォームアップ): 5分間の TTL が切れる前に、プロキシは Anthropic API に直接「ウォームリクエスト」を送信します。このリクエストは、同一のキャッシュ可能なプレフィックスを使用しますが、max_tokens: 1 に設定し、ストリーミングを無効にします。
4. Refresh (リフレッシュ): 単一のトークンは破棄されます。目的はプリフィル（prefill）であり、これにより、高価な再書き込み（1.25x）を避け、安価な読み取りレート（0.1x）でフルキャッシュプレフィックスをリフレッシュします。

インストールと使用方法

claude-thermos には Python 3.11+ と、システムの PATH にインストールされた claude CLI が必要です。uvx を使用して実行できます：

• 標準実行: uvx claude-thermos (claude コマンドの代わりに使用)
• 引数付き: uvx claude-thermos -p "fix the bug" (引数は Claude CLI に直接渡されます)

設定のチューニング

ユーザーは以下のオプションフラグを調整して、ウォームアップの動作をチューニングできます：

フラグ	デフォルト	意味
--idle	270	ウォームアップが開始される前にメインエージェントがアイドル状態でなければならない秒数
--interval	270	ウォームアップサイクルの間の秒数
--max-cycles	4	1回のアイドルエピソードあたりの最大ウォームアップ回数 (auto で無制限)
--subagent-window	540	サブエージェントが「まだアクティブ」とみなされる秒数

コマンドを変更せずに特定の実行でウォームアップを無効にするには、環境変数 CLAUDE_WARMER_DISABLE=1 を設定してください。

節約額の追跡

すべてのセッションは ~/.claude-thermos/logs/<session_id>/ に events.jsonl ストリームと summary.json ロールアップを含むログを生成します。summary.json ファイルには以下のメトリクスが含まれます：

• warms_fired: 送信された合計ウォームリクエスト数。
• cache_read_total: ウォームアップ中に読み取られたトークン数。
• rewrite_avoided_tokens: キャッシュが失効していた場合に再書き込みされていたはずのトークン数。
• net_savings: 回避された再書き込みのコスト (1.25x) とウォームアップのコスト (0.1x) の差（ベース入力トークン単位で測定）。

実際のドル建ての節約額を計算するには、net_savings の値にモデルの入力トークンあたりの価格を掛けます。

コミュニティの議論と対論

このツールに関するコミュニティのフィードバックでは、キャッシュ TTL と「ウォームアップ」リクエストの倫理についての議論が浮き彫りになっています。

キャッシュ TTL の相違

複数のユーザーが、Pro および Max プランではキャッシュの失効が5分ではなく1時間である可能性があることを指摘しています。

"Pro/Max プランのコールを直接調査しましたが、今日現在、それらは1時間のキャッシュ失効を持っています... API レートを支払っている場合は、5分か1時間かを自分で選択できます。"

もし特定のティアでキャッシュ TTL が実際に1時間である場合、claude-thermos が使用している5分間のウォームアップ間隔は、それらの特定のユーザーにとっては不要、あるいは無駄である可能性があります。

リソース使用量と倫理

一部のユーザーは、自動化されたウォームアップリクエストが「共有地の悲劇」を招き、機能的な出力を提供することなく Anthropic のインフラへの負荷を増大させる可能性があるという懸念を表明しています。

"これは他の全員のコストを高くするだけではないですか？... 私は常に行列の先頭にいることを要求するつもりはありません。"

逆に、他のユーザーは、このツールは、サブエージェントが必要なエージェント的ワークフローを使用しているユーザーにペナルティを与えるような、欠陥のあるキャッシュメカニズムにプロバイダーが対処することを強いるものであると主張しています。