Token Weather：Claude Code コンテキストウィンドウ予報

Token Weather は Hamza Zafar（hamzafer）によるコミュニティ製の Mod で、彼の claude-code-mods コレクションの一つです。入力欄の上の 1 行に、Claude Code のコンテキストウィンドウ予報を表示します。ウィンドウの埋まり具合を天気の言葉とアイコンで示し、使用率、ウィンドウサイズに対するトークン数、直近のターンのスパークライン、そしてプロンプトキャッシュがあとどれだけ温かいままかのカウントダウンが並びます。

予報は ☀ Clear（25% 未満）から ☁ Cloudy、☂ Showers、☇ Storm を経て、90% 以上の ↯ Compact soon まで変わります。隣の last turns は最大 12 件の値を ▁▂▃▄▅▆▇█ で描き、その中の最大値に合わせて縮尺されます。続けて、直近のターンでの増減が ▲ +39.4k last turn のように出ます。行に十分な幅があれば、❄ cache 4:12 がキャッシュの期限切れまでを数え、最後の 1 分は黄色になり、期限後は ❄ cache cold と表示されます。

Token Weather は、当サイトの Context Bar、Context Meter、Cache Clock と一部重なります。Context Bar はウィンドウをカテゴリ別に分け、Context Meter はステータスラインに使用率とプラン使用量を出し、Cache Clock はステータスラインの下にキャッシュの詳細を出します。Token Weather は 1 行の判定と推移を示します。作者のマーケットプレイスでのバージョンは 0.2.2 です。

録画では、小さなデモプロジェクトでこの Mod を読み込んだ Claude Code を起動します。プロンプトを送る前、入力欄の上の行は ☀ Clear 0% of context 0 / 1M です。続いて、README.md を読んでこのプロジェクトを 1 文で説明するよう Claude に頼みます。最初のリクエストの実行中に ❄ cache 5:00 のカウントダウンが現れます。ターンが終わると、行は ☀ Clear 4% of context 39.4k / 1M、スパークライン、▲ +39.4k last turn、❄ cache 60:00 になります。応答が 1 時間のキャッシュを書き込んだためです。

インストールブロックにある方法のどれでも使えます。いずれも作者自身のマーケットプレイスから直接インストールされます。この行は次のセッション開始時に表示されます。プラグインのオプションは、プロンプトキャッシュの有効期間の 1 つだけです。

読み取り値は、ホストが保持する $.state のアトムに保存されるため、ホットリロードをまたいで残ります。読み取りはセッション開始時とメインエージェントの各ターンの後に、$.session.usage のコンテキスト情報から行われます。キャッシュの時計は、ターン内のツールループのリクエストも含め、メインスレッドのモデルリクエストが終わるたびにやり直されます。次は hooks/register.tsx の turn.step ハンドラです。

on('turn.step', async function* ($, e, next) {
  const result = yield* next(e)
  if (!e.agentId && result.stopReason !== null) {
    const now = await $.clock.now()
    await update($, lastRequestAt, () => now)
    restart($, now, now, await ttlMsFor($, override))
  }
  return result
})

auto モードでは、各ターンの後にセッション記録（<config dir>/projects/<project>/<session id>.jsonl）の最後の 1 MB を読み、直近のメインスレッドの応答の cache_creation に 1 時間または 5 分のトークンがあるかを調べます。結果はプラグインのストアに保存され、次のセッションでも使われます。カウントダウンの表示が変わるタイミングでタイマーが行を再描画します。残り 10 分を超える間は 30 秒ごと、それ以下は 15 秒ごと、最後の 2 分は毎秒です。

オプションはプラグイン設定の cacheTtl だけで、auto（既定）、5m、1h から選びます。固定値にすると自動検出より優先されます。予報の区分、12 件の履歴、60 秒の警告は register.tsx の先頭にある定数です。任意の並び順ファイル <config dir>/claude-code-mods/bands.json も読み込み、同じ作者の複数のバー系 Mod が入力欄の上に並ぶときの順序を決めます。

実行前に、プラグインが実行できるすべてのファイルを読みました。.claude-plugin/plugin.json、hooks/hooks.json、hooks/register.tsx、hooks/bands.ts、型定義、3 つのテストファイルです。package.json、インストールスクリプト、バイナリ、バンドルされたコードはなく、描画する文字列は数値から組み立てられ、モデルのプロンプトには何も注入しません。リポジトリには MIT の LICENSE があります。

動作のすべては次のとおりです。

• **ネットワーク：**なし。
• **プロセス：**1 つだけ、tail -c 1048576 <セッション記録のパス> で、記録が 1 MB を超える場合に限ります。それ以外はファイルを直接読みます。
• **読むファイル：**自分のセッション記録（キャッシュ有効期間の検出用）、Claude の設定ディレクトリにある任意の bands.json、$.settings.read による Claude Code の設定（Cache Clock のステータスラインが設定されているかの確認用）。場所の特定に環境変数 HOME と CLAUDE_CONFIG_DIR を読みます。
• **書き込むファイル：**直接の書き込みはなし。検出したキャッシュ有効期間（5m または 1h）を、プラグイン専用のストア $.store に保存します。
• **バックグラウンド処理：**Claude Code 内の再描画タイマーのみで、セッション終了時に止まります。デーモンはありません。
• **ゲート：**なし。ツール呼び出しやプロンプトをブロックしたり書き換えたりしません。

claude plugin validate はプラグイン自体にエラーも警告も出しませんでした（ディレクトリ用のチェッカーはアイコンがないと指摘）。作者の 24 件のテストは Claude Code 2.1.307 ですべて通りました。

Claude Code 2.1.307 の macOS で確認しました（validate、テスト、録画）。行が表示されない場合は次を確認してください。

• インストール後に新しいセッションを始めたこと。Mod はセッション開始時に読み込まれます。
• 入力欄の上にアンケートが開いていないこと。アンケート中はこの行が退き、閉じると戻ります。
• ウィンドウが 60 桁以上あること。それより狭いと、予報の言葉、使用率、トークン数だけが表示されます。
• カウントダウンがずれるときは、cacheTtl を auto ではなく 5m か 1h にしてください。プロジェクトのパスが非常に長い場合や、セッション中にプロジェクトを移動した場合はセッション記録が見つからず、最後に検出した値が残ります。
• /clear や再開の後は、次のリクエストまでカウントダウンが隠れます。