Claude Usage Widget
gnoeynij/Claude-Usage-Widget
Monitor de uso Claude Code desktop com Tauri 2 + SolidJS + Rust
Ver no GitHubWidget de desktop em tempo real que monitora o uso da API Anthropic (Claude Code) direto na barra de tarefas do Windows/macOS. Exibe sessão atual, limites semanais, custos por modelo e histórico de bloqueios em 3 modos visuais (Mini/Normal/Detalhado) com design Liquid Glass nativo do SO.
Instalação
npx convez-ai gnoeynij/Claude-Usage-Widget1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Monitorar consumo de API em tempo real sem abrir navegador
- Rastrear custos por modelo e projetar gastos mensais
- Receber alertas ao atingir 85% ou 95% dos limites de uso
Veredito

Ferramenta desktop sólida para desenvolvedores que usam Claude Code diariamente. Stack moderno (Tauri 2 + Rust + SolidJS) garante performance e design nativo; excelente para quem precisa de visibilidade contínua de uso e custos sem overhead de browser.
README
A tradução para o português deste README ainda está na fila.
English | 한국어
Claude Usage Widget
A desktop widget for Claude Code that shows your Anthropic API usage — current session, weekly limits, recent blocks, and per-model cost — at a glance, without opening a browser or terminal. Rebuilt from scratch with Tauri 2 + SolidJS + Rust for Windows and macOS.
This project is a personal project based on INNO-HI/ClaudeUsageWidget, published with the original author @khwee2000's permission. Original copyright belongs to INNO-HI. See LICENSE for terms and the Releases page for the full change log.
A lightweight desktop tool that sits in a corner of your screen and tracks your Claude Code usage in real time. Aimed at developers who use Claude Code daily and want a passive, always-visible usage monitor instead of polling a dashboard.
✨ Features
Three-mode widget
- Mini (240×112) — Donut + 2-row capsule. Minimum footprint
- Normal (320×360) — Donut hero + weekly capsules. Default
- Detail (592×619, minSize 520×520) — dashboard: Active session (live countdown), Periods (+ month-end cost projection), Recent 5h blocks, Models (+ mix %), Stats (lifetime cost · messages · cache hit)
Switch via footer SegmentedControl or tray menu. Each mode has its own default size + minSize, and any size you drag-adjust is remembered per mode.
Liquid Glass + OS-native vibrancy
System backdrop composited with OS-level vibrancy — Win11 Mica/Acrylic on Windows, NSVisualEffectView (HudWindow material) on macOS. The background-opacity slider fades only the background — text, donuts, and gauges stay fully opaque.
Tray status indicator
- Anthropic mark with a status dot — green when the last sync succeeded, red when it failed (token expired, network down, rate limited, …)
- The dot flips immediately on every sync, so you can tell at a glance whether the widget is healthy without expanding it
Auto-update
Silent check 3 seconds after boot + manual button in Settings. When an update is available, you get a dot badge on the gear icon and a "Restart now" button after the background download finishes. Signed manifests via tauri-plugin-updater.
OAuth token auto-recovery
Reads Claude Code's OAuth token from the platform-native store — ~/.claude/.credentials.json on Windows, the macOS Keychain (Claude Code-credentials service) on macOS. On expiry, the in-app banner tells you to run claude once and the widget self-heals on the next sync.
Usage notifications
- An alert fires when you cross 85% or 95% of the 5-hour session or 7-day weekly limit
- In-app Liquid Glass toast while the widget is on screen — matches the widget's look, needs no OS permission; falls back to an OS notification when the widget is hidden to the tray
- One alert per threshold per block — no repeats on every sync; OS permission requested lazily on the first tray-hidden crossing
Lifetime cost & cross-device combining
- Lifetime · this device — a non-decreasing running total that survives Claude Code log cleanup (the on-disk figure can drop as old JSONL sessions are pruned; lifetime keeps every cost it has counted)
- Lifetime · all devices — point each PC's Combined across devices setting at the same cloud-synced folder (OneDrive / iCloud / Dropbox / Google Drive) and the widget sums every device's lifetime into one figure. No server — each device writes only its own file and the cloud handles propagation
Real-time countdowns
The session reset and the active 5-hour block tick down live, second by second, between syncs. (All cost figures are local estimates: ~/.claude/projects JSONL × the official pricing table.)
Bilingual (English / Korean)
Every string switches instantly, including time labels and AM/PM.
🚀 Installation & Usage
Windows
- Download — Grab the latest
Claude Widget_X.Y.Z_x64-setup.exefrom the Releases tab. - Install — Double-click the installer. WebView2 Runtime installs automatically on Windows 10 (Windows 11 ships with it).
- First launch — SmartScreen bypass — This is an unsigned-installer personal open-source build, so Windows SmartScreen may warn you on first launch. It is not malware — click
More info → Run anywayto proceed. - Run — The widget needs an existing Claude Code login on the same PC (
~/.claude/.credentials.json).
macOS
- Download — Grab the latest
Claude Widget_X.Y.Z_aarch64.dmgfrom the Releases tab (Apple Silicon). - Install — Open the .dmg, drag
Claude Widget.appinto/Applications. - First launch — Gatekeeper bypass — The .dmg is ad-hoc signed (not paid Apple Developer ID), so macOS refuses the first launch with "Apple could not verify…". Two options:
- Right-click → Open in Finder, then click Open in the dialog. macOS remembers the choice — subsequent launches are normal.
- Or run once in Terminal:
xattr -d com.apple.quarantine "/Applications/Claude Widget.app"
- Run — The widget reads your OAuth token from the macOS Keychain — wherever the
claudeCLI stored it. No extra setup if you've used Claude Code at least once on this Mac.
Controls (Windows & macOS)
- Mode — Footer SegmentedControl (Mini / Normal / Detail) or tray right-click menu
- Move — Drag the header bar (or any non-interactive surface in Mini)
- Resize — Drag window corners/edges; each mode remembers your size
- Hide —
×in the footer sends the widget to the tray; left-click the tray icon to bring it back - Quit — Right-click the tray icon →
Quit - Settings —
⚙button in the header - Auto-sync — Settings → Auto sync (
Off / 5m / 10m / 30m / 1h, default5m).
⚠️ The widget reuses the OAuth token that Claude Code stores locally (
~/.claude/.credentials.jsonon Windows/Linux, the login Keychain on macOS) to call Anthropic's OAuth usage endpoint. Anthropic's Consumer Terms (updated 2026-02-19) state that OAuth tokens from Claude Free/Pro/Max accounts are not authorized for use outside Claude Code and claude.ai — so this read-only reuse is an unofficial, best-effort approach that carries some account/ToS risk and may stop working if Anthropic changes the endpoint or enforces the policy. Use at your own discretion.
🛠️ Build from Source
v2.0+ uses Tauri 2 + Rust + SolidJS + Vite + UnoCSS + Motion One. The legacy PyQt6 source is preserved on the
v1.5.1tag; the instructions below build the currentmainbranch.
Requires Node ≥ 20 and the Rust toolchain (rustup). Platform extras:
- Windows — Microsoft C++ Build Tools ("Desktop development with C++" workload). WebView2 Runtime ships with Windows 11; on Windows 10 the installer bootstrapper fetches it automatically.
- macOS — Xcode Command Line Tools (
xcode-select --install). First-time DMG bundling needs Terminal to have Finder Automation permission (System Settings → Privacy & Security → Automation → Terminal → Finder). Seedocs/macos-setup.mdfor the full setup walk-through.
# 1. Clone
git clone https://github.com/gnoeynij/Claude-Usage-Widget.git
cd Claude-Usage-Widget
# 2. Install dependencies
npm install
# 3. Run in dev mode
npm run tauri dev
# 4. Production build
npm run tauri build
# 5. Output (Windows)
# src-tauri/target/release/bundle/nsis/Claude Widget_<ver>_x64-setup.exe (recommended)
# src-tauri/target/release/claude-widget.exe (portable)
#
# 5. Output (macOS)
# src-tauri/target/release/bundle/dmg/Claude Widget_<ver>_aarch64.dmg (recommended)
# src-tauri/target/release/bundle/macos/Claude Widget.app (raw bundle)
Tauri's bundler picks the right output per host OS — running
npm run tauri buildon Windows produces the NSIS installer, and on macOS produces the .app + .dmg.
📝 Change Log
v2.0.x (Tauri 2 + SolidJS line)
- v2.4.0 — Limit projection (ghost arc/dot shows expected usage at reset; ⚠ badge + tray alert when on pace to hit the limit) + Detail mode redesign (daily cost bar chart as hero, device-toggle history, totals card, unused models shown as $0) + interactive widget guide (real widget render + usage slider, 4-tab callout annotations).
- v2.3.1 — Daily cost history that survives JSONL cleanup (per-day model-mix breakdown in Detail) + lifetime cost now accrues in every mode, not just Detail + fast-mode (
speed: fast) pricing and Claude Mythos 5. Fixes: notification toasts no longer push widget content down (Portal overlay), no more duplicate 85%/95% toast on a 100% sync, and "always on top" now sticks across restarts. - v2.3.0 — Single-instance lock (re-launching focuses the existing window instead of spawning a duplicate) + Claude Fable 5 pricing ($10/$50, released 2026-06-09) + a notification fix (a 100%-on-sync crossing no longer fires both the 85% and 95% toast at once — only the highest level alerts).
- v2.2.0 — Lifetime cost that doesn't reset (per-device + combined across all your devices via a shared cloud folder) + live second-by-second session/block countdowns + in-app Liquid Glass notification toasts + Detail insights (month-end cost projection, model mix %). Also fixes a sync-breaking bug on the new
extra_usageAPI field, plus internal cleanup (dead code, unused HTTP plugin / CSS tokens) and aresolve()pricing cache. - v2.1.7 — Opus 4.8 cost fix (it was billed at the legacy $15/$75 tier — a 3× overcount — now the correct $5/$25) + subscription plan chip (e.g. "Max 20×") in the Settings panel header.
- v2.1.6 — macOS background opacity now applies immediately on slider change / launch (previously a mode switch was needed for it to take effect).
- v2.1.5 — cost-accuracy pass: Opus pricing corrected to the official table (~3× → actual), separate 5m/1h cache pricing, web-search surcharge, deprecated-model fallback, version shown in the update check.
- v2.1.4 — Tray icon shows immediate sync status (green dot = OK, red dot = failure), tray glyph rendered at the right system size, macOS widget corners rounded to 24px. Internal: halo-gauge design retired (-430 net lines).
- v2.1.3 — macOS background opacity matches Windows; boot + hover frosted-opaque regression fixed.
- v2.1.2 — Background opacity slider now works on macOS (
macos-private-apiopt-in unlocks the wrytransparentfeature path). - v2.1.1 — opacity slider visual consistency hotfix:
.glass-panel::before/::after+.glass-card::beforenow fade with--bg-alpha-mult(previously the outline + inner glow stayed painted at 100% opacity);--scrim-bglight/dark token split fixes the dark-gray Settings wash on light mode. - v2.1.0 — OS usage notifications (5h session 85% / 95% thresholds, lazy permission request) + Detail-mode mtime-based caching (heavy users no longer re-walk the full ~/.claude/projects on every sync) + log rotation cap (~5 MB) +
scripts/bump-version.mjsfor one-shot 6-file version bumps. - v2.0.3 — settings persist gap fix (lang / dark / opacity / sync / always-on-top / mode now survive restarts) + PyQt6 migration realignment + tray menu i18n (ko/en) + error banner expanded to 4 states (TOKEN_EXPIRED / NO_CREDENTIALS / RATE_LIMITED / NETWORK).
- v2.0.2 — first macOS release (vibrancy, Keychain credentials, drag region, DMG) + black-corner fix + unified Windows/macOS auto-updater + Detail-mode UX (hourly cost, per-model tokens, drag overlay).
- v2.0.1 — first public v2.0.x release (v2.0.0 was an internal cut); signing key rotation.
- v2.0.0 — internal cut. Full PyQt6 → Tauri 2 + SolidJS rewrite. Liquid Glass + Win11 Mica/Acrylic, 3-mode widget (Mini/Normal/Detail), auto-updater, tray, OAuth recovery, en/ko i18n.
Full notes also on the Releases page.
v1.5.1 (PyQt6 line, legacy)
- Token expiry handling — pre-check
expiresAtto skip doomed GETs, and on a 401 retry once with freshly-read credentials (catches the race where Claude Code rotates the token mid-sync)
For earlier history (v1.0.0 – v1.5.0), see the v1.5.1 tag README.
📄 License
Released under the MIT License.
- Original work © 2026 INNO-HI
- Modifications and additional features © 2026 choi jinyeong
Published with the original author's prior permission. The MIT license preserves attribution while allowing free use, modification, and redistribution.
Fonts: SUIT by Sun (SIL Open Font License). Pixel mark src/assets/claude-header.png is an Anthropic asset used for brand identity.