Usage Meter：Claude Code の使用量制限メーターをプロンプトの上に

Usage Meter は Claude Code の使用量制限メーターとして働くコミュニティ Mod で、Hamza Zafar（hamzafer）の claude-code-mods コレクションに含まれています。Claude Code のプロンプトの上に 1 行を描き、プランのレート制限ウィンドウとセッションのコストを表示します。たとえば ⏱ 5h █▆▁▁▁ 34% · resets 2h10 · 7d ███▁▁ 61% · $0.42 session のようになります。

各ウィンドウにはブロック文字でできた 5 セルのバーが付き、部分的なセルによって、ブロック単位よりも細かい段階を表現できます。バーとパーセンテージは 75% 未満で緑、75% 以上で黄色、90% 以上で赤になります。最初のウィンドウ（通常は 5 時間ウィンドウ）は常にリセット時刻を表示します。7 日間ウィンドウや利用額の上限などその他のウィンドウは、使用率が高くなったときだけリセット時刻を表示します。カウントダウンは 1 分ごとに進みます。リセット時刻を過ぎたウィンドウは、Claude Code が新しい数値を報告するまで非表示になるので、古い 100% が表示されたままになることはありません。

ウィンドウが 90% を超えると、リセット期間ごとに一度だけトーストで警告します。たとえば 5h usage limit at 92%, resets in 1h05 です。ターミナルの幅が狭い場合は、まず副次的なウィンドウ、次にコストを省くので、メインのウィンドウは常に収まります。サブスクリプションがない場合（API キーのセッション）は、プランウィンドウがないためコストだけが表示されます。

私たちの コンテキストメーター をすでに使っている場合、重なるのは 5 時間・7 日間の数値とコストです。コンテキストメーターはそれらをテキストとしてステータスラインに書き込み、コンテキストウィンドウの使用量も加えます。Usage Meter はそれらをプロンプトの上にバーとして描き、リアルタイムのカウントダウンを付け、コンテキストは表示しません。作者の README によると、Claude Code 2.1.287 以降が必要です。

録画では、この Mod を読み込んだ Claude Code を起動して短いプロンプトを送り、ターンの後にプロンプトの上に表示される行を見せます。5 時間・7 日間のプランウィンドウが小さなバーとパーセンテージで表示され、5 時間ウィンドウのリセットまでの時間、セッションのコストも並びます。プランのバーが表示されるのは、デモ用のアカウントが Claude のサブスクリプションでサインインしているためです。

インストールブロックのいずれかの方法を使ってください。どれも作者自身のマーケットプレイスから直接インストールします。設定は不要です。

hooks/register.tsx から、数値を取得する 2 つのフックを示します。

on('session.start', async ($, e, next) => {
  const result = await next(e)
  // Moves the reset countdown on while a window has a reset time.
  timer?.cancel()
  timer = $.clock.every(TICK_MS, () => { /* bumps the tick atom */ })
  const usage = await $.session.usage().catch(() => null)
  if (usage) await take($, usage.rateLimits, usage.cost?.usd).catch(() => {})
  return result
})

on('session.measure', async ($, e, next) => {
  const result = await next(e)
  await take($, e.rateLimits, e.cost?.usd).catch(() => {})
  return result
})

take はパーセンテージが有限値のウィンドウだけを残し、ホスト側が保持する $.state アトムに保存してから warn を呼び出します。warn は、90% 以上で、現在のリセット期間にまだ警告していないウィンドウについてトーストを表示します。リセット時刻が 30 分以上先に進んだ場合は、新しい期間とみなされます。AbovePrompt の ui.render フックは、スナップショットと、60 秒タイマーが更新する tick アトムを読み取るので、新しい数値がなくてもカウントダウンが再描画されます。純粋関数 build、fit、bar、colorFor、countdown が各セグメントを生成し、作者のテストがそれらをカバーしています。

/config の設定項目もスラッシュコマンドもありません。細かな挙動は register.tsx 先頭の定数で制御します。CELLS（バーの幅、5）、TICK_MS（カウントダウンの更新間隔、60 秒）、WARN_AT（トーストのしきい値、90）、そしてウィンドウ名の LABELS（5h、7d、spend）です。

私たちは実行前に、プラグインが実行しうるすべてのファイル（hooks/hooks.json、hooks/register.tsx、型宣言、テスト）を読みました。package.json、インストールスクリプト、バンドルされたコードはありません。

UI の変更 は、プロンプトの上の行と 90% のトーストに対応します。Mod は Claude Code がすでに追跡している使用量の数値を $.session.usage と session.measure イベントを通じて読み取り、$.state に保持します。コマンドの実行、ファイルの読み書き、ネットワークの使用、環境変数の読み取り、モデルの呼び出しは行いません。claude plugin validate はエラーも警告も報告せず、作者の 11 件のテストは Claude Code 2.1.291 ですべて成功しました。

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

• claude --version が 2.1.287 以降であること。
• Claude のサブスクリプションを使っていること。API キーの場合はコストだけが、しかも $0.00 を超えてから表示されます。
• 最初のモデルの応答があるまで、Claude Code が使用量の数値を持っていない場合があります。プロンプトを一度送れば行が埋まります。
• 入力欄の上にアンケートが開いていないこと。閉じると行は戻ってきます。