Usage Meter Claude Code mod: Claude Code plan limits above the prompt

Usage Meter is a community mod by Hamza Zafar (hamzafer), from his claude-code-mods collection. It draws one line above the prompt with your Claude Code plan limits (the rate-limit windows) and the session's cost, for example ⏱ 5h █▆▁▁▁ 34% · resets 2h10 · 7d ███▁▁ 61% · $0.42 session.

Each window gets a five-cell bar made of block characters, so partial cells show finer steps than whole blocks would. The bar and the percentage are green below 75%, yellow from 75% and red from 90%. The first window (normally the 5-hour one) always shows when it resets. The others, such as the 7-day window or a spend limit, show their reset time only once they run high. The countdown moves on every minute. A window whose reset time has passed is hidden until Claude Code reports a fresh reading, so you never see a stale 100%.

When a window passes 90%, a toast warns you once per reset period, for example 5h usage limit at 92%, resets in 1h05. On a narrow terminal the line drops the secondary windows first, then the cost, so the main window always fits. Without a subscription (an API key session), there are no plan windows and only the cost is shown.

If you already use our Context Meter, the overlap is the 5-hour and 7-day figures and the cost. Context Meter writes them as text into the status line and adds context-window fill; Usage Meter draws them as bars above the prompt with a live countdown and leaves context out. The author's README needs Claude Code 2.1.287 or later.

The recording starts Claude Code with the mod loaded, sends a short prompt, and shows the line above the prompt after the turn: the 5-hour and 7-day plan windows as small bars with their percentages, the time until the 5-hour window resets, and the session cost. The plan bars appear because the demo account is signed in with a Claude subscription.

Use any of the methods in the install block; they install straight from the author's own marketplace. Nothing needs configuring.

From hooks/register.tsx, the two hooks that take readings:

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 keeps the windows with a finite percentage, stores them in a host-held $.state atom and calls warn, which shows a toast for any window at or above 90% that has not been warned about in its current reset period. A reset time that moved on by more than half an hour counts as a new period. The ui.render hook on AbovePrompt reads the snapshot and a tick atom that the 60-second timer bumps, so the countdown redraws without a new reading. Pure functions build, fit, bar, colorFor and countdown produce the segments, and the author's tests cover them.

There are no options in /config and no slash command. The constants at the top of register.tsx control the details: CELLS (bar width, 5), TICK_MS (countdown refresh, 60 seconds), WARN_AT (toast threshold, 90) and LABELS for the window names (5h, 7d, spend).

We read every file the plugin can execute before running it: hooks/hooks.json, hooks/register.tsx, the type declarations and the tests. There is no package.json, install script or bundled code.

Changes the UI covers the line above the prompt and the 90% toast. The mod reads usage figures that Claude Code already tracks, through $.session.usage and the session.measure event, and keeps them in $.state. It does not run commands, read or write files, use the network, read environment variables or call the model. claude plugin validate reported no errors or warnings, and the author's 11 tests passed on Claude Code 2.1.291.

Checked with Claude Code 2.1.291 on macOS (validate and tests). If the line does not show up:

• claude --version is 2.1.287 or later.
• You are on a Claude subscription. With an API key, only the cost appears, and only after it is above $0.00.
• Claude Code may not have usage figures until the first model response. Send one prompt and the line fills in.
• A survey is open above the input; the line returns after it closes.