Show HN: Claude-thermos – あなたのClaudeセッションを暖かく保ちます
Show HN: Claude-thermos – keeps your Claude session warm for you (github.com)
要約
Claude-thermosは、AnthropicのClaude Codeセッションにおけるプロンプトキャッシュの無駄な再エンコードを防ぐためのツールです。Claude Codeでは、5分間アイドル状態が続くとキャッシュが失われ、長いセッションやサブエージェントの利用時に高額な再エンコード料金が発生します。Claude-thermosはこのキャッシュをバックグラウンドで定期的に「ウォームアップ」することで、キャッシュの有効期限切れを防ぎ、コストを約20%削減します。
全文翻訳
claude-thermos
Claude Codeのキャッシュ再構築に料金を払うのをやめましょう。 メインエージェントが5分以上サブエージェントを待機すると、プロンプトキャッシュはサイレントに失効し、次のターンで会話全体が書き込みレートで再エンコードされてしまいます。長いセッションで多くのサブエージェントを使用する場合、これは請求額の約20%に相当します。claude-thermosはキャッシュを保温し、この税金を払う必要がなくなります。
使用方法
Claude Codeを通常通り実行しますが、uvxを使用してclaude-thermos経由で実行します。
uvx claude-thermos # 代わりに: claude
uvx claude-thermos -p "fix the bug" # 任意のclaude引数はそのまま渡されます
Python 3.11以降とPATH上のclaude CLIが必要です。
これで完了です。保温はバックグラウンドで自動的に実行されます。コマンドを変更せずに実行を無効にするには、CLAUDE_THERMOS_DISABLE=1を設定してください。
チューニング(すべてオプション):
| フラグ | デフォルト | 意味 |
|---|---|---|
--idle | 270 | メインエージェントがアイドル状態になってから保温が開始されるまでの秒数 |
--interval | 270 | 保温サイクル間の秒数 |
--max-cycles | 4 | アイドルエピソードあたりの最大保温回数(無制限の場合はauto) |
--subagent-window | 540 | サブエージェントが「アクティブ」と見なされる秒数 |
実行するclaudeの選択
デフォルトでは、claude-thermosはPATH上のclaudeを起動します。--binまたはCLAUDE_THERMOS_BIN環境変数を使用して、別のバイナリを指定してください。単純な名前はPATHで検索されます(そのため、--bin claude-nightlyは機能します)。フルパスはそのまま使用されます。これは、バンドルされたビルドやアカウントごとに異なるCLAUDE_CONFIG_DIRをエクスポートするラッパーに便利です。
claude-thermos --bin /path/to/bin/claude -p "fix the bug"
# または
export CLAUDE_THERMOS_BIN=/path/to/bin/claude
claude-thermos -p "fix the bug"
フラグは、パススルーされるclaude引数の前に来る必要があります。
デーモンモード(IDEおよび複数のターミナル用の共有プロキシ)
デフォルトのコマンドは、起動したclaudeプロセスのみを保温します。自身でclaudeを起動するクライアント(独自のバンドルされたバイナリをスポーンするVSCode/Claude Code拡張機能など)は、それを通過しません。他のターミナルも同様です。
claude-thermos serveは、固定ループバックポートで保温プロキシをスタンドアロンデーモンとして実行します。任意のクライアントをそれに接続すれば、すべてが1つのウォームを共有します。
claude-thermos serve --port 8787 # デーモンを実行(Ctrl-C / SIGTERMで停止)
# その後、任意のクライアントに対して:
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
claude -p "fix the bug" # ターミナル — デーモンによって保温されます
VSCode拡張機能の場合、そのプロセスがその環境変数を継承していることを確認してください(macOSでは、アプリを起動する前にlaunchctl setenv ANTHROPIC_BASE_URL http://127.0.0.1:8787を実行するか、エディタを起動するシェルでエクスポートします)。拡張機能はANTHROPIC_BASE_URLを尊重するため、そのトラフィックはデーモンを通過し、サブエージェント実行中にメインエージェントは保温されたままになります。
デーモンはランチャーと同様にトラフィックを監視し、多くのセッションを同時に追跡しているため、単一のデーモンがすべてのクライアントにサービスを提供します。--session-ttl(デフォルト3600s)より長くアイドル状態のセッションをエビクトするため、無期限に実行できます。
Tuning: serveは、デフォルトコマンドと同じ--idle/--interval/--max-cycles/--subagent-windowフラグに加えて、以下を受け入れます。
| フラグ | デフォルト | 意味 |
|---|---|---|
--port | 8787 | デーモンがリッスンするループバックポート |
--upstream | https://api.anthropic.com | プロキシがリバースプロキシする実際のAPI |
--session-ttl | 3600 | セッションがエビクトされるまでアイドル状態を許容する秒数 |
注意:
--upstreamは実際のAPIである必要があり、デーモン自身のループバックアドレスであってはなりません。そうしないと、プロキシが自身にフォワードしてしまいます。serveはループバックアップストリームを拒否するため、ANTHROPIC_BASE_URLをグローバルにエクスポートした場合でも、デーモンを明示的な--upstream https://api.anthropic.comで起動してください。
キャッシュが失効し続ける理由
Claude Codeのプロンプトキャッシュは5分間のTTLを使用します。各ターン、キャッシュがアクティブである限り、会話履歴全体がフルプライスで再送信されるのではなく、0.1倍の価格でキャッシュから読み込まれます。
キャッシュは、同じプレフィックス間でリクエスト間に5分以上経過すると失効します。そのギャップの主な原因は、ユーザーが考えていることではありません。それは、メインエージェントが5分以上実行されるサブエージェントでブロックされていることです。サブエージェントは異なるシステムプロンプトとツールセットを持つため、そのリクエストは異なるキャッシュプレフィックスを持ち、メインエージェントのキャッシュをリフレッシュすることはありません。サブエージェントが作業している間、メインエージェントのキャッシュされた履歴は未変更のまま経過し、5分を過ぎると消滅します。サブエージェントが戻ると、メインエージェントはバイト単位で同一の、追記のみの履歴で再開し、キャッシュが見つからないため、1.25倍の書き込みレートでの完全な再エンコードを強制されます。
その時点で履歴は大きくなっているため、再エンコードは高価です。個々の折り畳みで200Kから500Kトークンが書き直されます。約185のローカルセッションで測定したところ、これらの再構築は総請求額の約22%を占め、以前はキャッシュされていたコンテンツを再エンコードするために費やされたお金でした。
仕組み
claude-thermosは、Claude Codeを小さなローカルリバースプロキシの後ろに起動します(ANTHROPIC_BASE_URLをループバックポートにポイントします。すべてのトラフィックは引き続き実際のAnthropic APIに送信されます)。
- 監視。 プロキシは
/v1/messagesトラフィックを監視し、セッションとリネージにグループ化します。リネージとは、モデル+ツールセット+システムテキストによってキー付けされたキャッシュプレフィックスのことです。最初のツールを含むリネージがメインエージェントであり、残りはサブエージェントです。 - 危険なウィンドウを検出。 メインリネージがアイドル状態になり、かつサブエージェントがアクティブに実行されている場合、メインプレフィックスは失効のリスクにさらされます。
- 保温。 5分間のTTL未満の間隔で、メインエージェントの最後のリクエストをウォームリクエストとしてリプレイします。これは、キャッシュ可能なプレフィックスは同一ですが、
max_tokens: 1でストリーミングはありません。単一トークンは破棄されます。目的は、完全なキャッシュ済みプレフィックスを読み取り、リフレッシュするプリフィルです。ウォームリクエストはプロキシを経由せず、APIに直接送信されるため、実際のトラフィックを妨害することはありません。 - 結果。 サブエージェントが終了すると、メインエージェントのキャッシュは保温されたままです。高価な書き換えではなく、安価な読み取り料金で済みます。
各ウォームはキャッシュ読み取り(0.1倍)のコストがかかります。それを防いだ書き換えは、はるかに大きなプレフィックスで書き込み(1.25倍)のコストがかかったはずなので、この取引は非常に有利です。
イベントログと節約額
各セッションは以下に書き込まれます。
~/.claude-thermos/logs/<session_id>/
├── events.jsonl # 追記専用構造化イベントストリーム
└── summary.json # セッション終了時に書き込まれる集計合計
events.jsonlは、各リクエスト/レスポンスのトークン使用量と、すべての保温決定(warm_fired、warm_result、cap_reached、resume_detectedなど)を記録します。summary.jsonは、通常読み取る集計です。
| フィールド | 意味 |
|---|---|
warms_fired | 送信されたウォームリクエスト数 |
cache_read_total | それらのウォームによって読み戻されたトークン数 |
episodes | 正常な再開(実際に回避された書き換え)で終了した、サブエージェントありのアイドルエピソード数 |
rewrite_avoided_tokens | エピソード全体で集計された、書き直されたであろうトークン数 |
warm_cost | 保温にかかったコスト: 0.1 × cache_read_total |
rewrite_avoided_cost | 保存されたコスト: 1.25 × rewrite_avoided_tokens |
net_savings | rewrite_avoided_cost − warm_cost |
すべての3つのコスト計算は、基本入力トークン単位(トークン数はすでにキャッシュ乗数で重み付けされています)です。net_savingsをドルに変換するには、モデルの入力トークンあたりの価格を掛けてください。
節約されたドル ≈ net_savings × (入力トークン価格)
例えば、入力価格が1Mトークンあたり3ドルの場合、net_savingsが1_200_000であれば、そのセッションで節約された金額は約1_200_000 × $3 / 1_000_000 = $3.60です。