Skip to content

feat: add macOS WidgetKit widget extension#24

Open
stolot0mt0m wants to merge 4 commits intof-is-h:mainfrom
stolot0mt0m:feature/widget-extension
Open

feat: add macOS WidgetKit widget extension#24
stolot0mt0m wants to merge 4 commits intof-is-h:mainfrom
stolot0mt0m:feature/widget-extension

Conversation

@stolot0mt0m
Copy link
Copy Markdown

@stolot0mt0m stolot0mt0m commented Jan 28, 2026 •
edited
Loading

Summary

This PR adds a native macOS WidgetKit widget extension that displays Claude usage data with Apple-style circular progress rings.

Features

  • Small Widget: Shows 5-hour limit with percentage and reset time
  • Medium Widget: Shows up to 3 usage rings (5h, 7d, Sonnet) with percentages and reset times
  • Apple-style Design: Circular progress rings with text labels in center
  • Dark/Light Theme Support: Adaptive background and colors for both themes
  • Color-coded Progress: Matches main app's color scheme
  • Auto-refresh: Widget updates every 15 minutes

Widget Display

Limit Type Center Label Color Scheme
5-Hour 5h Green → Orange → Red
7-Day 7d Light Purple → Deep Purple → Magenta
Sonnet S Light Blue → Blue → Indigo

Technical Details

New Files

  • Usage4ClaudeWidget/ - Widget extension target
    • Usage4ClaudeWidget.swift - Main widget with TimelineProvider and views
    • Usage4ClaudeWidgetBundle.swift - Widget bundle entry point
    • Usage4ClaudeWidget.entitlements - Widget entitlements (App Group)
    • SharedUsageData.swift - Widget-only data model

Data Sharing

  • Uses App Groups (group.xyz.fi5h.Usage4Claude) via UserDefaults(suiteName:) for sandbox-safe data sharing between app and widget
  • Main app writes data on refresh, widget reads on timeline update

Modified Files

  • Usage4Claude/Shared/SharedUsageData.swift - Shared data model with App Group storage
  • Usage4Claude/Usage4Claude.entitlements - Added App Group entitlement
  • Usage4Claude/Helpers/DataRefreshManager.swift - Widget sync on data refresh
  • project.pbxproj - Added Widget extension target (Xcode-style UUIDs)

Signing & Sandbox

  • Main app signing config unchanged (Manual, Usage4Claude-CodeSigning, sandbox enabled)
  • Widget extension uses same signing style
  • Both targets have ENABLE_APP_SANDBOX = YES

Deployment Target

  • Both main app and widget target macOS 14.0 (WidgetKit requires macOS 14.0+)
  • Note: This is a bump from the previous 13.0 — required for WidgetKit APIs

Test Plan

  • Build and run main app
  • Verify widget appears in widget gallery (requires signing)
  • Add Small widget to desktop - shows 5h ring with % and reset time
  • Add Medium widget to desktop - shows 3 rings with % and reset times
  • Verify data syncs from main app to widget via App Group
  • Verify colors match main app's color scheme
  • Test Dark and Light theme appearance
  • Verify widget refreshes automatically

@stolot0mt0m stolot0mt0m force-pushed the feature/widget-extension branch 2 times, most recently from b88c7be to 6bd134b Compare January 28, 2026 12:28
@stolot0mt0m stolot0mt0m force-pushed the feature/widget-extension branch from 6bd134b to 274b95b Compare February 27, 2026 20:35
@stolot0mt0m
Copy link
Copy Markdown
Author

stolot0mt0m commented Feb 27, 2026

Hey @f-is-h! 👋

I've rebased this PR on the latest main so it's conflict-free and ready for review.

I think a native macOS widget would be a great addition to Usage4Claude — here's why:

  • At-a-glance monitoring — Users can see their current usage without opening the app or clicking the menu bar icon. The circular progress rings make it instantly clear where they stand.
  • Proactive awareness — With the widget sitting on the desktop or in Notification Center, users are less likely to hit rate limits unexpectedly. They can plan their Claude usage throughout the day.
  • Reset time visibility — Showing when limits reset helps users decide whether to wait or keep going, especially when they're close to the cap.
  • Native feel — WidgetKit integrates seamlessly with macOS, supporting both light and dark mode. It feels like a natural extension of the app rather than an afterthought.

Would love to hear your thoughts — happy to make adjustments if needed!

@f-is-h
Copy link
Copy Markdown
Owner

f-is-h commented Mar 20, 2026

Hi, thanks for putting this together! The widget concept is great and I'd love to have it in the app.

A few things that need to be addressed before merging:

  1. The pbxproj IDs (WIDGET001, WIDGETTARGET, etc.) are hand-written rather than Xcode-generated UUIDs. This will likely cause build issues. Could you add the widget target through Xcode directly so it generates proper IDs?

  2. Please don't change the main app's signing config (CODE_SIGN_STYLE, CODE_SIGN_IDENTITY) or sandbox settings (ENABLE_APP_SANDBOX). Those should stay as they are.

  3. For data sharing between the app and widget, App Groups would be the proper approach instead of writing to ~/.Usage4Claude/. File-based sharing works without sandbox, but turning off sandbox is a step backwards for security.

  4. The widget's MACOSX_DEPLOYMENT_TARGET is 14.0 while the main app targets 13.0. These should be consistent.

Let me know if you have any questions!

@stolot0mt0m stolot0mt0m force-pushed the feature/widget-extension branch from 274b95b to 115ac29 Compare March 20, 2026 16:51
@stolot0mt0m
Copy link
Copy Markdown
Author

stolot0mt0m commented Mar 20, 2026

Hi @f-is-h, thanks for the detailed review! I've addressed all your feedback:

1. pbxproj IDs — Replaced all hand-written IDs (WIDGET001, WIDGETTARGET, etc.) with proper 24-character hex UUIDs.

2. Main app signing config — Restored CODE_SIGN_STYLE = Manual, CODE_SIGN_IDENTITY = "Usage4Claude-CodeSigning", and ENABLE_APP_SANDBOX = YES. Only added CODE_SIGN_ENTITLEMENTS for the App Group entitlement, everything else is untouched.

3. App Groups for data sharing — Switched from file-based storage (~/.Usage4Claude/) to UserDefaults(suiteName: "group.xyz.fi5h.Usage4Claude"). Sandbox stays enabled for both targets. Added the com.apple.security.application-groups entitlement to both the main app and widget.

4. Deployment target — One thing to flag: WidgetKit on macOS requires a minimum deployment target of macOS 14.0 (Sonoma). Setting it to 13.0 would cause build errors since WidgetKit APIs aren't available on macOS 13. I've set both targets to 14.0 to keep them consistent. If you'd prefer to keep the main app at 13.0, we could conditionally compile the widget sync code, but the widget extension target itself would still need 14.0+. Let me know how you'd like to handle this!

Also rebased on the latest main to pick up the recent fixes.

stolot0mt0m and others added 3 commits April 13, 2026 01:21
@stolot0mt0m
feat: add macOS WidgetKit widget extension
58dfa90 
Add a native macOS widget that displays Claude usage data with Apple-style
circular progress rings.

Features:
- Small and Medium widget sizes
- Usage rings for 5h, 7d, Opus, and Sonnet limits
- Color-coded progress (green → orange → red based on utilization)
- Automatic data sync via App Groups
- 15-minute refresh interval

New files:
- Usage4ClaudeWidget/ - Widget extension target
- Usage4Claude/Shared/SharedUsageData.swift - Shared data model

Modified files:
- DataRefreshManager.swift - Sync data to widget on refresh
- project.pbxproj - Widget extension target configuration
- Usage4Claude.entitlements - App Groups capability

Requirements:
- App Group: group.xyz.fi5h.Usage4Claude
- macOS 14.0+ for widget extension
@stolot0mt0m
feat(widget): improve widget design and add theme support
0d6eac8 
Widget improvements:
- Small widget: Show only 5h limit with percentage and reset time
- Medium widget: Show up to 3 rings (5h, 7d, Sonnet) with reset times
- Add text labels in ring center (5h, 7d, S, $)
- Add Dark/Light theme support with adaptive background
- Match ring colors with main app's color scheme
- Remove unused Opus limit case
- Add file-based data sharing via ~/.Usage4Claude/SharedUsageData.json
@stolot0mt0m
fix: address review feedback for widget extension
f943cce 
- Replace hand-written pbxproj IDs with proper 24-char hex UUIDs
- Restore main app signing config (Manual, Usage4Claude-CodeSigning, sandbox enabled)
- Switch from file-based storage (~/.Usage4Claude/) to App Group UserDefaults
- Add App Group entitlements to both main app and widget extension
- Align MACOSX_DEPLOYMENT_TARGET to 14.0 for both targets (required by WidgetKit)
- Match widget signing config to main app style
@stolot0mt0m stolot0mt0m force-pushed the feature/widget-extension branch from 115ac29 to f943cce Compare April 12, 2026 22:22
@stolot0mt0m
Copy link
Copy Markdown
Author

stolot0mt0m commented Apr 12, 2026

Hi @f-is-h, just rebased on the latest main — conflicts are resolved and the PR is mergeable again. Did you get a chance to take another look? No rush, just wanted to check in. Thanks!

@stolot0mt0m
Merge upstream/main into feature/widget-extension
bfc5e38 
Resolves conflict in project.pbxproj:
- Keep MACOSX_DEPLOYMENT_TARGET = 14.0 (required for WidgetKit)
- Adopt MARKETING_VERSION = 2.6.1 from upstream
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@stolot0mt0m @f-is-h