Cache Clock：Claude Code プロンプトキャッシュの期限を見守る

Cache Clock は、Claude Code のプロンプトキャッシュの状態を表示するコミュニティ Mod です。作者は Hamza Zafar（hamzafer）で、claude-code-mods コレクションの一部です。ステータスラインの下に 1 行を足します。キャッシュが温かい間は緑色で、cache ● 1h ██████████ 59m left · hit 48% · misses 0 のように表示されます。キャッシュの有効期間（5m または 1h）、残りを示す 10 マスのバー、残り時間、ヒット率、ミス回数です。

残りが有効期間の 20% を切ると行は黄色になります。キャッシュが切れると赤になり、cache ○ cold · next message re-caches 82k tokens と表示され、Claude Code が直前のミスの原因を報告していればそれも付きます。メッセージを送る前に、キャッシュから返されるのか、プレフィックス全体を作り直すコストがかかるのかがわかります。

数値は Mod が計算しているわけではありません。Claude Code は 2.1.251 以降、ステータスラインのコマンドに prompt_cache オブジェクトを渡しており、Mod はそれを整形するだけです。プラグインはステータスラインを登録できないため、Mod は /cache-clock コマンドを追加します。setup は statusLine を Mod のスクリプトに向け、remove は元に戻します。すでにステータスラインがある場合はそのまま残り、キャッシュの行がその下に付きます。

録画では、小さなデモプロジェクトで Mod を読み込んだ Claude Code を起動します。ステータスラインはあらかじめ Mod のスクリプトに向けてあり、録画者自身の ~/.claude を書き換えないよう、/cache-clock setup の手順は意図的に省いています。Claude に README.md を読んでプロジェクトを 1 文で説明するよう頼みます。ターンの実行中、プロンプトの下には、バーが満タンの緑色の cache ● 1h が 59m left と hit 0% · misses 0 とともに表示されます。ターンが終わると、同じ行が hit 48% · misses 0 に更新されます。

インストールブロックにある方法のどれかを使ってください。いずれも作者自身のマーケットプレイスから直接インストールされます。そのあとセッションで /cache-clock setup を実行します。行は Claude の次の返答のあとに現れ、/cache-clock だけを実行すると有効かどうかがわかります。

hooks/register.ts がコマンドを登録し、セットアップを行います。同梱の statusline/cache-clock.mjs は、Claude Code がステータスラインを更新するたびに実行するスクリプトです。stdin から JSON を読み、元のコマンドが保存されていればそれを実行し、キャッシュの行を出力します。純粋なフォーマッターは statusline/render.mjs にあります。

export function render(input, nowSeconds) {
  const cache = input?.prompt_cache
  if (!cache || typeof cache !== 'object') return ''
  if (cache.caching_observed === false) return ''

  const left = typeof cache.expires_at === 'number' ? cache.expires_at - nowSeconds : null
  const isWarm = cache.warm !== false && left !== null && left > 0
  return isWarm ? warmLine(cache, left) : coldLine(cache)
}

expires_at を過ぎた時点で、入力が作成時に warm だったとしてもコールドとして扱います。setup は 2 つのスクリプトをプラグインのフォルダではなく <config dir>/cache-clock/ に書き出します。プラグインのフォルダはバージョンごとに変わるためです。次のセッション開始時に、ステータスラインがこの Mod のものであれば、refreshScripts が新しい版でコピーを上書きします。setup は refreshInterval を 30 秒にします（すでにそれより短ければそのまま）。返答の合間もカウントダウンが進みます。

オプションはありません。切り替えは /cache-clock setup と /cache-clock remove だけです。見た目を変えるには render.mjs を編集します。BAR_CELLS でバーの幅、WARN_SHARE で黄色に変わる境目（既定は 20%）、ファイル冒頭で色のエスケープコードを変えられます。編集するのは <config dir>/cache-clock/ のコピーです。セットアップ済みの間は、次のセッション開始時に Mod が同梱版で上書きします。

実行前に、プラグインが実行するすべてのファイルを読みました。.claude-plugin/plugin.json、hooks/hooks.json、hooks/register.ts、2 つのステータスラインスクリプト、テストです。package.json、インストールスクリプト、バンドル済みや minify 済みのコード、バイナリはありません。リポジトリには MIT の LICENSE があります。

• 設定の変更は要求したときだけ。 インストール時やセッション開始時には、自身のスクリプトの更新以外は何も書き込みません。/cache-clock setup は Claude の設定フォルダ（または CLAUDE_CONFIG_DIR）の settings.json に書き込みます。ステータスラインがプロジェクト設定由来の場合は <project>/.claude/settings.local.json に書きます。さらに <config dir>/cache-clock/ にスクリプトと setup-<hash>.json のバックアップを書きます。/cache-clock remove は以前の statusLine を復元します（セットアップ後にあなたが変更していた場合を除く）。管理設定（policy）や --settings のステータスラインには手を出さず、不正な設定 JSON もそのままにします。
• 更新のたびにコマンドを実行します。 セットアップ後、Claude Code は node "<config dir>/cache-clock/cache-clock.mjs" を実行します。このスクリプトは、以前のステータスラインのコマンドを、同じ入力でシェル経由（spawnSync(..., { shell: true })、タイムアウト 5 秒）で実行します。setup 自体は Node の有無を確認するため node --version を実行します。
• ネットワーク、テレメトリ、モデル呼び出し、デーモンはありません。 HOME と CLAUDE_CONFIG_DIR は設定フォルダを見つけるためだけに読みます。トークンや認証情報は読みません。
• プロンプトインジェクションも、ブロックするフックもありません。 登録するのは session.start と自身のコマンドだけで、プロンプトやツール結果には何も追加しません。
• 必要なもの： PATH 上の Node と Claude Code 2.1.251 以降。

claude plugin validate はエラーも警告も報告せず、作者の 25 件のテストは Claude Code 2.1.296 ですべて通りました。

macOS 上の Claude Code 2.1.296 で確認しました（validate、テスト、デモ）。行が表示されない場合：

• /cache-clock を実行します。「cache-clock is on」と出るはずです。
• まず 1 通メッセージを送ってください。prompt_cache が届くまで、またプロバイダーがキャッシュなしと報告している間、行は空です。
• claude --version が 2.1.251 以降で、同じターミナルで node --version が動くことを確認します。
• ステータスラインが管理設定や --settings で指定されていないこと。setup はそれらを変更しません。
• すでに起動しているセッションで setup した場合は、次の返答か 30 秒ごとの更新を待ちます。