Settings — UsageNow Docs

Open Settings from the gear button in the popover, or press ⌘, while the popover is open. Settings has six tabs: General, Providers, Menu Bar, Notifications, Privacy, and About.

Language#

UsageNow speaks thirteen languages: English, German, Spanish, French, Portuguese, Russian, Hebrew, Japanese, Korean, Dutch, Kazakh / Қазақша, Uzbek / Özbekça, and Turkish / Türkçe. The last three were added in 1.0.0. Uzbek copy uses Ö, Ğ, Ş and Ç. By default it follows your Mac's language. To use another for UsageNow only, choose it in Settings › General › Language and then Restart Now — the widget follows too. System goes back to your Mac's language.

The choice is the same one System Settings › General › Language & Region › Applications makes for UsageNow, so changing it in either place shows in both.

Provider and model names keep their original names. What's New is translated and bundled offline; Hebrew also uses right-to-left layout.

General#

Open Setup#

Reopens the optional first-run setup. Updating an existing installation preserves its choices and does not automatically show setup again.

Command line#

Install CLI adds ~/.local/bin/usagenow, a link to the command inside the app. Run usagenow status or usagenow status --json to read the safe snapshot without starting providers. Remove CLI removes only UsageNow's own link. An unrelated existing command is never overwritten; shell profiles are never edited. See Command Line for PATH setup, freshness and exit codes.

Starts UsageNow automatically when you log in to your Mac. macOS manages this setting, so you can also change it in System Settings › General › Login Items.

If macOS needs your approval, Settings shows Allow UsageNow in System Settings to finish setup. with a button that opens Login Items.

Appearance#

Choose Light, Dark, or System. System follows your Mac’s appearance. The default is Light. The setting applies to the popover and Settings.

Show limits as#

Remaining (the default) or Used. Every percentage — in the popover, the menu bar, and the widget — follows this choice. See Left or used.

Show the last 30 days#

The chart of daily activity under each provider in the popover. On by default; turn it off to keep the popover short when you track many providers. See Last 30 days.

Refresh interval#

How often UsageNow refreshes on its own: Manual, 5 minutes (the default), 15 minutes, or 30 minutes. With any setting, UsageNow also checks for new usage when you open the popover. A provider's HTTP 429 cooldown takes priority, including over manual refresh; see rate limits.

Show service incidents#

Off by default. Periodically checks public OpenAI, Claude, Cursor, and GitHub Copilot status pages for enabled providers, with a ten-minute cache. No account or usage data is sent. A service incident is separate from your account's connection state and does not prove that your token has expired. See Service incidents.

Updates#

Check for updates automatically lets UsageNow look for a new version on its own; Check Now asks immediately. UsageNow installs an update only when it is signed with the UsageNow update key, and a check sends nothing about you — no identifier, no system profile, no version history. See Updates.

If you built UsageNow yourself, both controls are off: a build that didn't come from the release process carries no update key and can't update itself.

Claude usage limits — Experimental#

Fetch Claude usage limits shows your current Claude Code subscription limits by asking Anthropic, using your existing Claude Code sign-in. It’s off by default, and it appears only while Claude Code is enabled in the Providers tab.

When limits can’t be fetched, a one-line reason and a Try Again button appear under the setting. Read Claude Code before turning this on.

Providers#

Choose which services UsageNow displays and monitors.

Available — all supported providers. Local tools start on; explicit connections start off. Drag a row, or use Move Up / Move Down, to set the popover and widget order.
Connect — Cursor, GitHub Copilot, Perplexity, ElevenLabs, and Z.ai. Use Check and Save to verify a key, token, or session before storing it. Cursor and Perplexity also offer isolated Sign In. See Connect a provider.
API key — DeepSeek, Kimi, OpenRouter, and Ollama Cloud. Keys are also checked before saving. Turning off an explicit-connection provider deletes the credentials you saved in UsageNow, not the service's own sign-in.
Experimental — Cursor, Copilot, Perplexity, Z.ai, and Ollama Cloud use undocumented usage sources. The optional Claude usage-limits setting is experimental too. JetBrains AI reads internal local quota formats and still needs active-subscription validation.
Accounts — Codex, Claude Code, and explicit connections support Add Account…. Each has its own usage and credential where applicable. Cursor and Copilot are no longer Coming soon in 0.8.0.

The list scrolls when it's taller than the window.

Widgets can now have their own provider and account selection. Right-click a widget and choose Edit Widget; see Personalize each widget.

Accounts#

UsageNow reads the account each tool uses by default. If you use more than one — a personal and a work Codex, say — add the others with Add Account… under the provider. Each account gets its own section in the popover and its own row in the widget, named after the provider and the account: Codex · Work.

Name — your own label, such as Work or Client. UsageNow never reads an account's name or email from the tool, and a problem report numbers accounts instead of naming them.
Codex and Claude Code — choose the folder the tool uses for that account: the one CODEX_HOME or CLAUDE_CONFIG_DIR points to when you run it. UsageNow reads it exactly as it reads ~/.codex or ~/.claude. For an added Claude Code account, limits appear when Claude Code records reaching one; the experimental limits source reads only the default account's sign-in.
Explicit connections — add the account's key, GitHub token, or Cursor/Perplexity web session, then choose Check and Add Account. It is kept only in this Mac's Keychain, sent only to the provider, and deleted when you remove the account or turn the provider off.

Each account's … menu has Rename…, Replace Key… for an API account, and Remove. Remove forgets the account and, for an API account, deletes its key. It never touches the tool's own folder. A folder that was moved or deleted is marked Folder not found under the account's name.

Turning a provider off stops UsageNow from refreshing it or reading anything for it. See Providers.

Display chooses what appears next to the symbol in the menu bar:

Icon only — the default
Most critical usage
One per enabled provider with limits, such as Codex usage, Antigravity usage, or Kiro usage

You can also choose a supported added account, such as Codex · Work. Removing the selected account falls back to that provider's first account.

When no usage limit is available, the menu bar shows the icon alone. See Menu bar display for how each option is calculated.

Keyboard shortcut#

Opens UsageNow from any app. Click Record Shortcut, then press the keys: a letter or other key with at least one of ⌃, ⌥, or ⌘, or a function key on its own. Press Esc to cancel recording, and use the button beside the shortcut to remove it. There's no default.

Pressing the shortcut shows the same content as the popover, in a window under the menu bar item. Press it again, press Esc, or click elsewhere to close it.

The shortcut needs no Accessibility or Input Monitoring permission: macOS tells UsageNow only that its own shortcut was pressed. If another app already holds the combination, Settings says so and asks for a different one.

Notifications#

Since 1.0.0, choose warning and critical remaining percentages for each enabled provider, and turn notices about a warned limit's reset on or off independently. Initial thresholds are 20% and 5%. Quiet hours follow this Mac’s time zone and can cross midnight. Warnings and resets in quiet hours are skipped, never saved up for the morning. Stale readings and windows whose reset has passed do not trigger low-limit warnings. Existing notification consent is preserved when upgrading.

Notify me about limits#

Off by default. When on, UsageNow sends a notification:

when a limit crosses your warning and critical thresholds (20% and 5% left initially) — once each, not on every refresh
when a limit it warned you about has reset, if reset notices are enabled for that provider

A limit first seen below both thresholds gets one notification, not two. A limit you were never warned about resets silently. The wording follows Show limits as: “18% of the 5-hour limit left” or “82% of the 5-hour limit used”.

The first time you turn it on, macOS asks whether UsageNow may show notifications. If notifications are off for UsageNow in System Settings, the tab says so and offers Open Notification Settings….

Limits are checked when UsageNow refreshes, so a warning can arrive up to one refresh interval late. The reset notification is scheduled with macOS when the warning goes out, so it arrives on time even if UsageNow isn't running then. Notifications are local to this Mac; nothing is sent anywhere.

Privacy#

Optional, and off by default. When on, UsageNow may share basic app usage and device information to help improve the app. It never includes prompts, tokens, project names, files, credentials, or coding activity. See Telemetry for exactly what could be sent.

About#

Shows the UsageNow version and build number, links to usagenow.com and @UsageNow on X, What's New…, Open Source Licenses…, and Report a Problem….

What's New#

Every version's changes, newest first, with the one you have marked Installed. The list ships inside the app, so it opens without a connection and always matches your version. The changes follow the changelog on GitHub and appear in your chosen app language, with an English fallback when a translation is missing.

Report a Problem#

Builds a report of what UsageNow sees and shows all of it before anything leaves your Mac:

the UsageNow and macOS versions, and your Mac's architecture
each screen's size, and whether it has a camera housing in the menu bar
menu bar organizers that are running, such as Bartender or Ice, by name only
your UsageNow settings
for each enabled provider and added account: its status, limits, today's totals, how many of the last 30 days had activity, and the last refresh error — accounts are numbered, not named

It never includes names, emails, file paths, API keys, tokens, or prompts. Error messages are cleaned before they're included: your home folder becomes ~, and email addresses and anything shaped like a key are masked. Times are relative, such as "5m ago".

From there, choose Copy, Email…, or Open GitHub Issue…. Email and GitHub open with the report filled in; UsageNow sends nothing itself.