Claude Usage Widget

What it shows

Everything updates on its own every 30 seconds.

Requirements

• macOS 12 Monterey or later.
• Übersicht, a free app that runs desktop widgets.
• Node.js 18 or later.
• Claude Code signed in with a Claude Pro or Max subscription. API accounts have no plan limits to show.

Install

About five minutes. The commands use Homebrew; regular installers work too.

1. Install Übersicht

   With Homebrew:

   brew install --cask ubersicht

   Or download it from tracesof.net/uebersicht and move it to Applications. Open Übersicht: its icon appears in the menu bar. In its Preferences, turn on launching at login so the widget is always there.

2. Install Node.js

   The widget’s data collector runs on Node.js. With Homebrew:

   brew install node

   Or use the installer from nodejs.org. Node from Homebrew, the official installer, Volta, nvm and fnm is found automatically.

3. Add the widget

   Download the archive above and unzip it. Click the Übersicht icon in the menu bar, choose Open Widgets Folder and move the claude-usage.widget folder there. Keep the folder name as it is.

   The widget appears in the bottom left corner within half a minute. It starts in Russian: open claude-usage.widget/config.json and set "lang": "en".

4. Connect the Claude Code status line

   Plan usage is sent only to the Claude Code status line, so the widget takes it from there. Add this to ~/.claude/settings.json:

   {
     "statusLine": {
       "type": "command",
       "command": "node \"$HOME/Library/Application Support/Übersicht/widgets/claude-usage.widget/lib/statusline.cjs\""
     }
   }

   Restart Claude Code and send any message. The status line shows a short summary like ◆ Opus 5.5 5h 47% 7d 30%. Already have your own status line? Keep it: append --then "your-command" to the command, and the hook passes the same input to it and prints its output instead.

5. Allow Keychain access, if asked

   Per-model limits come from Anthropic using the token Claude Code keeps in your Keychain. Usually macOS does not ask anything. If it shows a dialog for security, allow it, or turn this off with "oauth": { "enabled": false } in the config.

Updating: download the new archive and replace the claude-usage.widget folder. Copy your config.json aside first and put it back afterwards.

Settings

Edit config.json inside the widget folder. The widget picks changes up on its next refresh, and invalid values fall back to defaults.

Where the data comes from

The status line is the only official source of plan usage, but it updates only while Claude Code runs. Limits are shared with claude.ai, so the widget falls back to Anthropic when the status line goes quiet.

Privacy. The only network request goes to api.anthropic.com. The token is read from the Keychain on demand and is never saved, logged or refreshed. The cache in ~/.cache/claude-usage-widget holds only percentages, reset times and log summaries, and is safe to delete. The endpoint is unofficial: if it changes, only per-model limits and the fallback stop working.

If something is off