convez.ai
PluginProdutividadeIntermediário
INNO-HI

Claude Usage Widget

INNO-HI/ClaudeUsageWidget

Monitore seu uso de Claude Code em tempo real na barra de menu

Ver no GitHub
BomPluginScore · de 0 a 100

Widget em tempo real para monitorar uso de Claude Code na barra de menu do macOS. Exibe burn-rate com ETA, sparkline de 7 dias, alertas customizáveis e exportação de dados em CSV/JSON. Suporta múltiplas contas e 4 idiomas.

Instalação

$npx convez-ai INNO-HI/ClaudeUsageWidget

1 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

Estrelas
7
Forks
3
Acompanhando
0
Saúde
75%
Último commit
há 4 meses
Versão
v1.6.7-macos
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acompanhar consumo de sessão e limites semanais do Claude Code em tempo real
  • Prever quando atingirá limite de uso com ETA automática
  • Analisar tendências de uso com sparkline histórico de 7 dias
  • Exportar histórico de uso para planilhas ou notebooks

Veredito

Ferramenta especializada e bem-executada para quem trabalha intensamente com Claude Code. Implementação sólida em Swift com testes, suporte multilíngue, alertas inteligentes e zero custo de tokens. Recomendado para usuários macOS que precisam de visibilidade real-time sobre quotas.

README

A tradução para o português deste README ainda está na fila.


Features

  • Real-time Monitoring — 5-hour session usage & 7-day weekly limits with a spring-animated session ring
  • Burn-rate ETA — Predicts when you'll hit the session limit at current pace
  • 7-day Sparkline — Usage trend strip in the Weekly Limits card (history persisted locally)
  • Custom Alert Thresholds — Two sliders replace the fixed 80% / 90%; the menu-bar icon pulses at the lower one
  • Rich Menu-Bar Tooltip — Hover the icon for current %, ETA, weekly usage, and last sync without opening the popover
  • CSV / JSON Export — Send your 7-day history to a spreadsheet or notebook (Settings → Data)
  • Multi-account — Point the widget at a non-default ~/.claude/.credentials.json to monitor a second account
  • Menu Bar Format — Off / % / Time / Both (segmented picker)
  • 3-step Onboarding — Intro → claude login copy button → notifications opt-in
  • Friendly Error Banner — Classified errors (credentials / rate-limit / network / server) with Retry & Open Terminal actions
  • Auto-Update via Sparkle — One-click "Check for Updates" inside the app (macOS, EdDSA-signed)
  • Launch at Login — Optional auto-start when you log in to macOS
  • Universal Binary — Native on Apple Silicon and Intel Macs (macOS 13+)
  • Rate-Limit Safe — ±10% jitter between syncs and 2×→16× exponential backoff on 429
  • Light & Dark Theme — Off-white surface in light mode, dark surface in dark mode
  • 에이투지체 (A2Z) Typography — Clean Korean-optimised font system across the popover
  • 4 Languages — English · 한국어 · 日本語 · 中文 (switch instantly inside Settings)
  • Accessibility — VoiceOver labels, ⌘R refresh, ⌘Q quit, ⌘, settings, system Reduce Motion honoured
  • Zero Token Cost — Uses OAuth usage API only, no Claude messages sent
  • Auto Sync — Configurable intervals: 1m / 5m / 10m / 30m / 1h / manual
  • Tested — 22-test pure-logic suite (swift test) for ETA, sparkline, thresholds, formatting
  • CI/CD — GitHub Actions for tests + auto build/sign/notarize/release/appcast on v*-macos tags
  • Claude Code Buddy — Official terminal pet integration (18 species, 5 rarity tiers, ASCII art)
  • Cross Platform — Native Swift on macOS, Node.js web widget on Windows & Linux

Screenshots


Claude Code Buddy

The widget integrates the official Claude Code Buddy terminal pet system.

  /buddy        → Hatch your buddy
  /buddy pet    → Pet your buddy (mood +1)
  /buddy off    → Put buddy to sleep

18 species — Each buddy is deterministically generated from your account ID. You can't choose or reroll.

  Cat         Dragon        Duck          Ghost         Owl
 /\_/\       /\_/\_          __          .___.        {o,o}
( · · )     (  · · )       >(··)__     | · · |      /)___)
 > ^ <       \ ~~ /         (  __)>    |  o  |       " "
             /|  |\          ||         \^^^/

5 rarity tiers — Common (60%) · Uncommon (25%) · Rare (10%) · Epic (4%) · Legendary (1%)

5 stats — DEBUGGING · PATIENCE · CHAOS · WISDOM · SNARK

1% Shiny variant with sparkle effects


Installation

macOS (Native App)

Requires macOS 13.0+ · Apple Silicon & Intel (Universal Binary)

Download the latest signed & notarized DMG from Releases, drag the app to /Applications, and launch.

✅ Signed with Developer ID Application: INNO-HI Inc. and notarized by Apple. Future updates ship via in-app Settings → Check for Updates (Sparkle).

Or build from source (requires an Apple Developer account for full signing):

git clone https://github.com/INNO-HI/ClaudeUsageWidget.git
cd ClaudeUsageWidget/macos
bash build.sh
open "build/Claude Usage Widget.app"

The macOS Swift source lives under macos/. Sparkle 2.x is vendored at macos/vendor/Sparkle.framework.

Windows / Linux (Cross-platform)

Requires Node.js 18+

git clone https://github.com/INNO-HI/ClaudeUsageWidget.git
cd ClaudeUsageWidget
node src/server.js

Opens automatically at http://127.0.0.1:19522.


Prerequisites

  1. Install Claude Code
  2. Run claude login in your terminal
  3. Launch the widget

Credentials are read from ~/.claude/.credentials.json (or macOS Keychain).


How It Works

┌─────────────┐     OAuth Token     ┌──────────────────────┐
│  Widget App  │ ──────────────────► │  Anthropic Usage API │
│  (local)     │ ◄────────────────── │  /api/oauth/usage    │
└─────────────┘    Usage Data (%)    └──────────────────────┘
       │
       ▼
   ~/.claude-usage-widget-history.json   (7-day rolling, exportable)

• Reads OAuth credentials from ~/.claude/.credentials.json (or any user-picked JSON for multi-account use) • Calls GET https://api.anthropic.com/api/oauth/usage • Auto-refreshes expired tokens; ±10% jitter + 2×→16× exponential backoff on 429 • Stores each successful sync as a 7-day rolling history file used by the Sparkline and Burn-rate ETA • No messages sent to Claude → zero token cost


Configuration

All settings live behind the gear icon in the popover.

SettingOptionsDefault
LanguageEnglish · 한국어 · 日本語 · 中文English
Credentials file~/.claude/.credentials.json (default) or any user-picked JSONdefault
Auto-syncmanual / 1m / 5m / 10m / 30m / 1h5m
Launch at Loginon / offoff
Menu Bar TextOff / % / Time / Both%
Compact modeon / offoff
Keep on Topon / offoff
Show Buddyon / offon
Usage Alertson / offoff
Alert thresholds (1st / 2nd)50–95% / 60–99% sliders80% / 90%
Data exportCSV · JSON · Clear history—
Check for Updatesone-click (Sparkle)—
Buddy commands/buddy · /buddy pet · /buddy feed · /buddy offoff

Troubleshooting

"Claude Widget is damaged and can't be opened. You should move it to the Trash."

This is macOS Gatekeeper rejecting a quarantined file whose Developer ID signature didn't survive the download (a known issue with some browsers and older builds — see #1). The current release is signed (Developer ID) and notarized, but if you still hit the message:

  1. Move the app to /Applications first (don't open from the DMG).

  2. Strip the quarantine attribute:

    xattr -dr com.apple.quarantine "/Applications/Claude Usage Widget.app"
    
  3. Re-launch — you may be asked once for permission, then it stays approved.

If that still fails, the download was likely corrupted — re-download from Releases and verify the DMG size matches the release listing.

Widget shows -- or Token expired

Your Claude Code OAuth token has expired. Run in Terminal:

claude login

Then click Refresh in the widget settings.

Launch at Login isn't sticking

macOS may have queued a permission prompt under System Settings → General → Login Items. Enable the entry there, or toggle the option off/on inside the widget.

No notifications appearing

First time you enable Usage Alerts, macOS asks for notification permission. If you missed it: System Settings → Notifications → Claude Usage Widget → Allow Notifications.

"Check for Updates" says nothing happens

You're already on the latest version. Sparkle silently confirms when you're up to date.


Change Log

See CHANGELOG.md for the full version history.

v1.5.2 (latest)

  • Fixed eyes were invisible on the menu-bar icon — NSColor.clear doesn't actually carve through, so the body stayed solid. Now uses windingRule=.evenOdd to produce real transparent cutouts. Eye box doubled for visibility at 18×18

v1.5.1

  • Fixed the "Claude active" face that never lit up — v1.5.0 watched ~/.claude-status.json mtime which only updates if you've configured a status-line script. Now uses pgrep -x claude every 10 s, which directly reflects whether the CLI binary is alive
  • Added Settings → "Animated menu-bar face" toggle to disable the syncing blink if it's distracting

v1.5.0

  • Added 3-expression menu-bar face — idle dots (●●), blinking slits (−−) while syncing, wide alert eyes (◉◉) while Claude Code is actively running
  • Claude activity detected via ~/.claude-status.json mtime (writes within last 30 s = active)
  • All eye animation honours the system Reduce Motion setting

v1.4.3

  • Fixed thread-race on the credential cache (URLSession bg ↔ main thread mutation)
  • Added 5-minute denial cooldown so Keychain "Always Allow" applied after the first prompt is picked up without restarting
  • Defended isCachedTokenExpired against NaN / Infinity in corrupted credential files
  • Trim whitespace from credentialPathOverride before using it as a file path
  • Added 13 regression tests (total 35) covering ms/sec detection, NaN, Infinity, and the exact user-reported expiresAt value

v1.4.2

  • Fixed expiresAt unit mismatch that re-prompted the Keychain on every sync when Claude Code stored the value in milliseconds — the cache check now auto-detects ms vs seconds
  • Added unified-logging diagnostics under subsystem com.innohi.claudeusagewidget / category creds so users can verify themselves when the Keychain is actually queried

v1.4.1

  • Fixed repeated macOS Keychain access prompts — credentials are now cached in memory between syncs; the Keychain is only queried again when the token actually expires, the server returns 401/403, or the user explicitly hits Refresh

v1.4.0

  • Added CSV / JSON export of usage history (Settings → Data) + Clear history
  • Added Multi-account credential path — point the widget at a non-default credentials file
  • Added Rich menu-bar tooltip — hover the icon for current %, ETA, weekly %, last sync
  • Added GitHub Actions CI for tests + release automation (auto build/sign/notarize/DMG/appcast on tag push)
  • Added Mac App Store submission scaffolding — entitlements + dual-build guide
  • Added 22-test unit suite (swift test) for pure logic (ETA, sparkline, thresholds, formatting)
  • Added Homebrew Cask submission guide

v1.3.0

  • Added Custom alert thresholds — two sliders replace fixed 80/90%
  • Added 3-step onboarding with claude login copy button + notifications opt-in
  • Added Friendly error banner (credentials / rate-limit / network / server) with Retry & Open Terminal
  • Added Japanese (日本語) and Simplified Chinese (中文) localisation — picker now EN / KO / JA / ZH
  • Pulse + ring glow now follow the user's lower notification threshold
  • Internal refactor: Theme.swift, BuddyViews.swift, OnboardingView.swift split out

v1.2.0

  • Added Burn-rate ETA — predicts when the session limit will be hit
  • Added 7-day Sparkline trend in the Weekly Limits card
  • Added Menu Bar Text format — Off / % / Time / Both
  • Added Warning pulse — menu bar icon breathes at ≥80%, session ring gets a soft glow halo
  • Added Skeleton loading + spring-animated session ring
  • Refreshed Onboarding with animated ring hero and gradient CTA
  • New 에이투지체 (A2Z) typography across the popover, wider 400 px layout, larger ring & progress bars
  • Switched popover background from glassmorphism blur to solid off-white / dark surface
  • Added accessibility labels, ⌘Q quit shortcut, system Reduce Motion support
  • Fixed deprecated NSWorkspace.launchApplication and stale footer version label

v1.1.0

  • Added Sparkle auto-update (signed via EdDSA)
  • Added Launch at Login option
  • Added Mini / Full mode toggle (hide menu-bar %)
  • Added Usage Alerts (80% / 90% session thresholds)
  • Added Universal Binary (Intel + Apple Silicon)
  • Added API rate-limit safety — ±10% jitter and 2×→16× exponential backoff on 429
  • Build pipeline now produces signed & notarized DMG

v1.0.0

  • Initial public release with menu-bar widget, glassmorphism UI, OAuth-based usage monitoring

Tech Stack

PlatformStack
macOS (native)Swift 5.9, SwiftUI, AppKit, ServiceManagement, UserNotifications, Security (Keychain), Sparkle 2.x
Pure logic librarySwift Package (macos/Package.swift) — testable on any platform
Cross-platformNode.js, HTML/CSS/JS
CIGitHub Actions: swift test on every push/PR, build/sign/notarize/release on v*-macos tags

Development

# Run the test suite (22 tests covering ETA, sparkline, thresholds, formatting)
cd macos
swift test

# Build a local unsigned .app for development
SKIP_SIGN=1 ./build.sh
open "build/Claude Usage Widget.app"

# Full signed + notarized release build (needs Developer ID identity + notary profile)
./build.sh

See:


License

MIT


Ver o original no GitHub

Bom para

Relacionados