Add WidgetKit support for macOS Notification Center and Desktop

[eddmann]

Feature Request: WidgetKit Widget Support

Summary

Add a macOS WidgetKit widget to allow users to view Claude.ai usage metrics directly from their Desktop or Notification Center, without needing to access the menu bar icon.

Motivation

Currently, ClaudeMeter only displays usage information via the menu bar icon and popover. A widget would provide:

• Always-visible monitoring: Users can glance at their usage without clicking the menu bar icon
• Flexible placement: Widgets can be placed on the Desktop (macOS Sonoma+) or in Notification Center
• Better user experience: Aligns with modern macOS design patterns and user expectations
• Quick reference: Especially useful for users who frequently check their Claude usage

Proposed Implementation

Technical Approach

1. Add Widget Extension Target to ClaudeMeter.xcodeproj

   • Create new WidgetKit extension using SwiftUI
   • Minimum deployment target: macOS 14.0 (Sonoma) - matches current app requirement
   • Share code with main app using frameworks/shared targets

2. Widget Sizes

   • Small (systemSmall): Show primary usage metric (e.g., 5-hour session %)
   • Medium (systemMedium): Show 2-3 key metrics (session + weekly + Opus)
   • Large (systemLarge): Detailed breakdown of all usage categories

3. Data Sharing Strategy

   • Use App Groups to share data between main app and widget extension
   • Main app writes usage data to shared UserDefaults/container
   • Widget Timeline Provider reads from shared storage
   • Consider using shared CacheRepository with file-backed cache

4. Widget Timeline

   • Refresh policy: Every 60-120 seconds (align with app's refresh interval setting)
   • Use timeline reload policy to respect user's configured refresh interval
   • Show "last updated" timestamp
   • Handle stale data gracefully (>10s old indicator like main icon)

5. Widget UI Elements

   • Color-coded gauge visualization (reuse MenuBarIconRenderer logic)
   • Usage percentages with labels
   • Visual indicators for warning/critical thresholds
   • Tap action to open main app/popover

Architecture Considerations

• Shared Models: Move core models (UsageData, UsageStatus, AppSettings) to shared framework
• Shared Services: Potentially share UsageService logic between app and widget
• Dependency Injection: Extend DIContainer to support widget context
• Icon Rendering: Adapt MenuBarIconRenderer for widget sizes

User Settings

Add widget-specific preferences to Settings:

• Enable/disable widget refresh
• Widget refresh interval (60-600s, default to app's setting)
• Option to show/hide specific metrics
• Privacy mode (blur numbers when locked?)

Design Considerations

• Match existing app's color scheme (green/yellow/red status colors)
• Use SF Symbols for consistency
• Support Light/Dark mode
• Respect system transparency/vibrancy settings

Technical Challenges

1. Session Key Security: Widgets run in separate process - need secure access to Keychain
2. Network Access: Widgets have limited background execution - must rely on app for data fetching
3. App Group Setup: Requires proper entitlements and provisioning profile updates
4. Timeline Management: Balance freshness vs. system resource usage

Alternative Considerations

• macOS Catalyst: Verify widget support for AppKit-based apps (current app is pure AppKit/SwiftUI hybrid)
• Live Activities: Not applicable for macOS, but worth noting for potential future iOS companion app

Success Criteria

• Widget appears in macOS Notification Center widget picker
• Widget can be added to Desktop (Sonoma+) or Notification Center
• Widget displays accurate, up-to-date usage data
• Widget respects user's refresh interval preferences
• Widget visual design matches app's existing style
• Tapping widget opens main app/shows popover
• Widget handles errors gracefully (no session key, network errors, etc.)
• Widget performance is acceptable (no excessive battery/CPU usage)

References

• Apple WidgetKit Documentation
• Building Widgets Using WidgetKit and SwiftUI
• App Groups for Data Sharing

Related Files

• ClaudeMeter/Views/MenuBar/MenuBarIconRenderer.swift - Gauge rendering logic to reuse
• ClaudeMeter/ViewModels/MenuBarViewModel.swift - Data fetching pattern to share
• ClaudeMeter/Models/UsageData.swift - Core data models
• ClaudeMeter/DependencyInjection/DIContainer.swift - DI setup to extend

---

Priority: Medium
Effort: Medium-High (3-5 days for full implementation)
Category: Enhancement

🤖 Generated with Claude Code