A living document tracking every improvement to the Claude Usage Widget — from weekend prototype to polished macOS tool.

March 22, 2026 — Weekend Build: v1.0

What: Built the entire widget from scratch. Electron app, tray icon, auth flow, session tracking, dark/light mode, expand/collapse dashboard.

Why: I use Claude 8+ hours a day and kept getting blindsided by usage limits mid-conversation. No native way to monitor it. So I built one.

Decisions:

• Electron over Swift — faster to ship, cross-platform later if needed
• Vanilla JS + CSS over React — widget is simple, no need for framework overhead
• API key stored via electron.safeStorage — encrypted at rest, no plaintext
• usage_config.json as data source with fs.watch — simple, debuggable, extensible

March 27, 2026 — Push Notifications

What: Added 5 notification triggers — session 80%, 90%, 100% and weekly 80%, 95%. Wrote copy with personality instead of corporate tone.

Why: The whole point is to not get blindsided. A progress bar you have to look at isn't enough. The widget needs to come to you.

Decisions:

• macOS native Notification API via Electron
• Fire once per threshold, auto-reset on new session detection
• Mute toggle in tray menu for focus blocks
• Copy: "You're cooked. Session limit hit. Go touch grass." — because nobody reads boring notifications