Widgets

UsageNow includes native macOS widgets, built with WidgetKit, that you can place on your desktop.

Sizes#

Small#

A glance at what matters most: for each enabled provider, the usage window with the least left, plus the next reset. With a single provider, it has room for the window’s name and reset time.

Medium#

A column for each enabled provider, with its usage windows, the percentage left in each, and reset times. With three or more providers, it switches to one compact row per provider so each stays readable. When more providers are enabled than fit, the ones closest to a limit are shown.

Large#

Up to four detailed provider or account rows, with two reported quota windows and reset times per row. Missing data is not invented to fill the extra space.

In every size, percentages follow Settings › General › Show limits as: what's left by default, or what's used — exactly as in the menu bar.

A provider with no limits to show — Gemini CLI, Warp, OpenCode, Qoder, Qwen Code, Cline, or Grok Build — shows today's activity in its own unit instead: tokens, or credits for Kiro, Warp, and Qoder. In the medium widget's rows, such a provider also gets a small chart of its last two weeks, one bar per day with today's bar highlighted. The chart shows the shape of your activity, not amounts, and turns off with Settings › General › Show the last 30 days.

Connected-account credit and character counters are shown in their own units, separately from today's local activity. Missing or unlimited allowances do not get an invented percentage.

An account you added appears as its own row, named after the provider and the account — Codex · Work.

Add the widget#

1. Right-click an empty area of your desktop and choose Edit Widgets.
2. Search for UsageNow.
3. Choose Small, Medium, or Large and drag it onto your desktop.

Open UsageNow at least once first, so the widget has data to show.

Personalize each widget#

Right-click a widget, choose Edit Widget, then select Providers and accounts. Each widget has its own selection: keep work accounts in one widget and personal accounts in another, for example. Leave the selection empty to follow UsageNow's enabled providers automatically.

The choices come only from the app's sanitized snapshot. Renaming an account preserves its selection. Removing an account never silently substitutes another one; an unavailable selection remains unavailable until you change it. Disabled providers are excluded even when selected.

How the widget gets its data#

The widget never reads your provider data itself.

UsageNow app ──► sanitized snapshot (App Group) ──► widget

The main UsageNow app refreshes providers, then writes a small snapshot of the values the widget displays to a shared App Group container on your Mac. The widget renders only that snapshot.

The snapshot holds display values only: each enabled provider’s usage windows and reset times, plan, most recent model, today’s token, request, and credit counts, the name you gave an added account, the shape of the last two weeks as shares of the busiest day, and whether percentages read as left or used. It never contains prompts, code, file paths, or credentials. It stays on your Mac.

Providers and the widget#

With an empty selection, the widget follows your provider settings automatically. A personalized widget filters the same snapshot to its selected sources:

• Providers you turn off in Settings › Providers don’t appear in the widget.
• Providers that aren’t installed don’t appear either.
• When a provider has no usage limits available, the widget shows Usage limits unavailable instead of a number.

Freshness#

The widget shows what UsageNow last saw. Its values change when the UsageNow app refreshes and writes a new snapshot, so keep UsageNow running if you rely on the widget. Launch at Login helps.

• Each provider keeps its own reading time. Updating one cannot make another provider's old data appear fresh; a clock marks stale readings.
• A fresh reading is saved even if its percentage did not change. Failed requests keep the original timestamp.
• Countdown text keeps ticking between timeline reloads. The timeline includes upcoming resets and the point when readings become stale; macOS still controls extension scheduling.
• When a quota window resets, the old percentage becomes unknown until the app gets fresh data. A reset does not prove the new window has 100% left.
• The freshness and countdown fixes from 0.8.0 also apply to personalized widgets in 0.9.0.
• While UsageNow updates, the app and the widget can briefly be different versions. The widget skips anything from a newer app it doesn't recognize — a provider added in that version, for example — and shows the rest.

Widget messages#

See Troubleshooting if the widget looks stale or doesn’t appear.