Desktop Widget

Desktop widget (macOS)

A widget for Notification Center and the Desktop. Small: up to two accounts with the most remaining, not locked to whoever is active. Medium: up to three accounts. Large: up to six. Extra large: up to ten.

The widget ships inside OpenSwap.app. The menu bar extra writes ~/Library/Application Support/OpenSwap/widget-snapshot.json and asks the host to reload. Tap an account on the widget to switch (the extra must be running). That is a CLI switch, not a ChatGPT desktop restart. A signed-out Claude card is repaired the same way as in the extra, not switched onto a dead backup. Disabled accounts are not tappable. Combined remaining counts Claude cards only.

Right-click the widget and choose Edit Widget:

• Layout: all accounts, combined remaining, or one account
• Windows: 5-hour, 7-day, or both
• Account: used when layout is one account

Combined remaining is remaining 5-hour or 7-day slots across healthy accounts (20% used plus 80% used is one slot left out of two, not 50%). It does not average personal with Ads Online, and it does not blend 5h with 7d. Tap the combined number to switch to the account with the most remaining. If the extra has not updated in 10 minutes, the widget shows when it last updated.

Add it

The app registers its widget each time it starts, so there is nothing to install. Keep the menu bar extra running so the numbers stay live. Then add it:

1. Notification Center: click the date in the menu bar → Edit Widgets
2. Desktop: right-click the desktop → Edit Widgets
3. Search for OpenSwap

macOS does not let apps place a widget for you.

openswap widget --status     # is it registered?
openswap widget --install    # register it again by hand
openswap widget --uninstall  # unregister it

Remove a placed widget from the Desktop / Notification Center the same way you added it. Uninstalling OpenSwap removes the widget too.

Source install

A source install builds the widget with Xcode instead: openswap widget --install needs this git checkout, Xcode (command-line tools are not enough) and an Apple Development signing identity (Xcode → Settings → Accounts). It copies a separate host app to ~/Applications/OpenSwap.app and starts it at login. After the first install, leave DEVELOPMENT_TEAM unset so rebuilds keep the same team. How the installer picks a team is in the developer widget notes.

Moving to the cask retires that host app (it goes to the Trash). Widgets placed with it may go blank; add them again.

Dark Mode

The widget uses dynamic colors and follows Light / Dark, including Desktop widgets sitting on a light or dark wallpaper.

Empty or stale numbers

• Open OpenSwap so the extra is running (Settings › General › This Mac › Open at login keeps it up)
• Confirm the snapshot exists: ~/Library/Application Support/OpenSwap/widget-snapshot.json
• openswap widget --status should show it registered
• Register it again: openswap widget --install