Claude Code Meter

A macOS desktop widget that shows your Claude Code usage limits in real time. Built for Ubersicht.

Displays both the 5-hour rolling window and 7-day rolling window with progress bars, percentage, exact reset time, and countdown timer.

• macOS 12+
• Ubersicht (free, open source)
• An active Claude Pro or Max subscription with Claude Code authenticated

1. Install Ubersicht if you don't have it:

   brew install --cask ubersicht

   If you're installing Übersicht for the first time, run it once to create the widgets folder where this widget will be installed.

2. Download claude-code-meter.jsx into your Ubersicht widgets folder:

   curl -o "$HOME/Library/Application Support/Übersicht/widgets/claude-code-meter.jsx" \
     https://raw.githubusercontent.com/gxjansen/claude-code-meter/main/claude-code-meter.jsx

3. Launch Ubersicht (or it will pick up the file automatically if already running).

The widget reads your OAuth token from the macOS Keychain (stored there by Claude Code during claude auth). No manual token configuration needed.

The widget supports two display modes:

• Remaining -- shows how much capacity is LEFT (bucket draining).

  

• Used -- shows how much capacity is CONSUMED (counter filling).

  

Bar color reflects pace (usage rate vs time elapsed in the window), not absolute fill: green when you're tracking under the sustainable rate, amber when on/above pace, red when burning through too fast. Below 10% remaining the bar is always red regardless of pace.

Click the mode badge in the top-right corner of the widget header to toggle between modes. The label next to each percentage (left / used) always clarifies what the number means.

Open claude-code-meter.jsx in a text editor to change defaults at the top of the file:

Change the className export to reposition the widget:

export const className = {
  bottom: "20px",  // distance from bottom
  right: "20px",   // distance from right
  width: "280px",
};

The widget pulls usage data from Anthropic's servers via their OAuth usage API (https://api.anthropic.com/api/oauth/usage). It does not track local sessions or count tokens client-side -- it reads the same server-side utilization percentages that Anthropic calculates across all your Claude Code activity. The OAuth token stored in your macOS Keychain by claude auth is used to authenticate the request.

The API returns utilization percentages and reset timestamps for both the 5-hour and 7-day rolling windows.

No data leaves your machine beyond the API call to Anthropic's servers (the same call Claude Code itself makes).

The widget detects specific error conditions and shows targeted messages:

• Token expired -- OAuth token has expired (typically after a reboot or long idle period). Click the re-authenticate button to launch claude auth login.
• Authentication failed -- API rejected the token (401/403). Click to re-authenticate.
• No credentials found -- Claude Code keychain entry is missing. Run claude auth login in your terminal.
• Rate limited -- Too many API requests. The widget shows cached data (with an amber "cached" indicator) during backoff, then retries automatically.
• Network error -- Cannot reach the Anthropic API. Check your internet connection.

For auth-related errors, the widget shows a clickable re-authenticate button that runs claude auth login to open a browser-based login flow. Once you complete the login, the widget will automatically pick up the new token on its next refresh.

MIT