megaproxy/claude-usage-widget
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions
claude-usage-widget/README.md
megaproxy 9be856d37c Polish for shipping: robust auto-detect, empty state, real icons, end-user README 
- cli_usage::default_command now enumerates WSL distros and probes each for
  claude before falling back; no more hardcoded -d Ubuntu.
- New autodetect_claude_command Tauri command + IPC binding so the UI knows
  whether claude is reachable.
- App.svelte: clear 'Claude Code not found' empty state with install link.
- Real icons: scripts/make-icon.py generates a 1024x1024 source.png; runtime
  produces 32/128/256 PNGs and a multi-resolution .ico. README in icons/
  explains how to regen.
- README rewritten for friends: install / requirements / troubleshooting on
  top; build-from-source moved to bottom.
2026-05-09 14:25:24 +01:00

4.3 KiB
Raw Blame History

Claude Usage Widget

A small always-on-top Windows desktop widget that shows your live Claude subscription usage — the same percentages Claude Code's /usage command displays, refreshed every 5 minutes.

┌─────── Claude Usage ────────────╳ ─┐
│                                     │
│         ╭───────╮                   │
│        ╱   72%   ╲                  │
│       │  session  │                 │
│        ╲ resets  ╱                  │
│         ╰ 2:50am ╯                  │
│                                     │
│   Models (current block)            │
│   ▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱                  │
│   ● Opus 42M   ● Haiku 3M           │
│                                     │
│   Weekly limits     resets May 9    │
│   All models    ▆░░░░░     8%       │
│   Sonnet        ▃░░░░░     5%       │
└─────────────────────────────────────┘

Install

  1. Download the latest Claude.Usage.Widget_<version>_x64-setup.exe from the Forgejo releases page.
  2. Run the installer. Windows SmartScreen will warn "unrecognized publisher" (it's not code-signed). Click More info → Run anyway.
  3. The widget pops up in the upper-left corner. Drag it where you want.

Requirements

  • Windows 10/11 with WebView2 Runtime (preinstalled on Windows 11; downloadable on Windows 10).
  • Claude Code installed and signed in.
    • Native Windows install (claude.exe on PATH) → works automatically.
    • Or installed inside WSL → also works automatically; the widget probes each distro to find one with claude.

Using it

  • The big ring shows your current 5-hour session percentage with a reset countdown.
  • The bars below show the rolling weekly limits (all models + Sonnet only).
  • Per-model breakdown (Opus / Sonnet / Haiku) shows how much of your local current 5-hour block came from each — derived from your local Claude Code transcripts. (Anthropic's /usage doesn't break this out, so we compute it ourselves.)
  • ↻ button (title bar) — force-refresh /usage right now.
  • ⚙ — Settings (custom claude command, refresh interval, autostart, distro override).
  • × — quit.
  • The window is resizable — drag any edge.

Troubleshooting

"Claude Code not found" — the widget couldn't find a claude to run. Make sure claude --version works in either PowerShell or a WSL shell. If it works in a non-default WSL distro, open Settings and set claude command to e.g. wsl.exe -d Debian bash -lc claude.

Ring shows "no /usage data" — the spawn worked but Anthropic's output didn't match the parser. Open Settings → Test /usage now → expand the raw output disclosure and file an issue with what's there.

SmartScreen blocks the installer — expected; the binary isn't code-signed. "More info → Run anyway".

Autostart toggle doesn't survive reboot — that's the dev build limitation. The released installer registers a stable path so autostart works correctly there.

Privacy

Everything stays on your machine. The widget:

  • Reads your local Claude Code config (~/.claude/projects/) for the per-model breakdown.
  • Spawns claude /usage to read live percentages — that command Anthropic serves from their backend over your existing Claude Code session, exactly the same as when you type /usage interactively. The widget never sees your OAuth token.
  • Stores its own settings at %APPDATA%\claude-widget\config.json.
  • Makes no other network calls.

Building from source

You need a Windows host with:

winget install Rustlang.Rustup OpenJS.NodeJS.LTS Microsoft.VisualStudio.2022.BuildTools
rustup default stable-x86_64-pc-windows-msvc
corepack enable
corepack prepare pnpm@latest --activate

Then in this repo:

pnpm install
pnpm tauri dev    # iterate
pnpm tauri build  # produces NSIS installer in src-tauri\target\release\bundle\nsis\

Project layout, architecture decisions, and known follow-ups live in memory.md.