Troubleshooting

Start with a manual refresh: open the popover and press ⌘R. Many problems clear up once UsageNow asks providers for fresh data.

Codex is not detected#

UsageNow hides Codex when it can’t find it. Check that:

• Codex is enabled in Settings › Providers.
• Codex is installed. UsageNow looks for Codex data in ~/.codex, and for the codex executable inside the Codex app or ChatGPT app, in /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, Bun, nvm, and the Codex extension for VS Code and the editors built on it.
• If you use CODEX_HOME, UsageNow can see it. Apps opened from Finder or at login don’t inherit variables set in your shell profile.

If codex is installed somewhere else — for example through a Node version manager — UsageNow can still read local activity from ~/.codex, but it can’t run the app-server, so limits may be stale. Installing Codex in one of the locations above fixes this. See Codex.

Claude Code is not detected#

Check that:

• Claude Code is enabled in Settings › Providers.
• Claude Code is installed and you’ve used it at least once on this Mac, so ~/.claude exists.
• If you use CLAUDE_CONFIG_DIR, UsageNow can see it. Apps opened from Finder or at login don’t inherit variables set in your shell profile.

If the section says Sign in to Claude Code to view usage, sign in to Claude Code and use it once, then refresh.

Claude usage limits unavailable#

This is expected by default. Claude Code does not currently expose subscription limits through a supported local API, so UsageNow shows Usage limits unavailable unless you turn on the experimental source in Settings › General › Fetch Claude usage limits. See Claude Code.

If the setting is on, the message under it tells you what’s wrong. The sections below cover each one.

Keychain access denied#

Allow UsageNow to access your Claude Code sign-in in Keychain. means the sign-in couldn’t be read. UsageNow reads it with /usr/bin/security, the tool Claude Code saves it with, so normally no prompt appears. If one does — your keychain may have been set up differently — and it was dismissed or denied:

1. Open Settings › General.
2. Choose Try Again under Fetch Claude usage limits.
3. If macOS asks whether security may use “Claude Code-credentials”, choose Allow.

After a failure like this, UsageNow doesn’t try again on its own, so macOS won’t keep prompting you. It tries again only when you choose Try Again or refresh manually.

Claude token is stale#

Refresh Claude Code from Terminal to view usage limits. means the Claude Code sign-in in your keychain has expired or was rejected. UsageNow never renews it.

Launch claude in Terminal to refresh your Claude Code session. You don’t need to choose Try Again: UsageNow notices the renewed sign-in on its next refresh. Until then, the last limits it read stay on screen, marked stale.

claude

If you mostly use the Claude desktop app, this happens more often: the desktop app keeps its own sign-in and doesn’t renew the one Claude Code stores in your keychain.

Claude usage limits are temporarily unavailable#

Anthropic’s usage endpoint didn’t answer, or answered in a way UsageNow doesn’t understand. Wait a few minutes and refresh. If it persists across app updates, the undocumented endpoint may have changed — open an issue. Local activity keeps working in the meantime.

Antigravity limits aren't shown#

UsageNow first asks the Antigravity IDE. In 0.9.0, it can fall back to the official CLI's read-only usage report if the IDE cannot answer. Use a signed-in CLI 1.x, version 1.1.11 or later; 1.2.2 was verified. Unsupported versions and unrecognized replies are not treated as current quota. Open the IDE or check the CLI's own sign-in, then refresh. Last known readings keep their original age. See Antigravity.

JetBrains AI limits aren't shown#

This integration is experimental and still needs validation with an active AI Assistant subscription. Open your IDE's AI Assistant usage view so the IDE can update its own quota cache, then refresh UsageNow. Installing the IDE alone is not enough. Unknown, expired, or unsupported quota data stays unavailable; UsageNow never signs in or fetches JetBrains quota itself. See JetBrains AI.

Gemini CLI shows no limits#

This is expected. Gemini CLI records no usage limits on your Mac, so UsageNow shows Usage limits unavailable with today's tokens, requests, and models below. See Gemini CLI.

OpenCode, Qoder, Qwen Code, Cline, or Grok Build is not detected#

• Check that the provider is enabled in Settings › Providers.
• OpenCode is found by its database in ~/.local/share/opencode, its CLI, or its app. Use it once so it creates the database. See OpenCode.
• Qoder is found by ~/.qoder, the Qoder app, or qodercli. Credits appear once its agent has answered something. See Qoder.
• Qwen Code is found by ~/.qwen or the qwen CLI, and Grok Build by ~/.grok or the grok CLI. Activity appears once they've recorded a session. See Qwen Code and Grok Build.
• Cline is found by its saved tasks in VS Code, Cursor, Windsurf, Kiro, VSCodium, or Trae, by ~/.cline/data, or by the cline CLI. Run one task so it saves something. Forks such as Roo Code and Kilo Code aren't read. See Cline.

An added account doesn't appear#

• Check the folder: it should be the one the tool uses for that account — where CODEX_HOME or CLAUDE_CONFIG_DIR points when you run it — not your projects folder.
• No sign-in or sessions in this account's folder means the folder holds nothing to read: often it's the wrong folder, or the tool hasn't used it yet. Use the tool with that folder once, then refresh. Settings › Providers marks a folder that no longer exists with Folder not found; remove the account and add it again with the right folder.
• For an API account, check that its key was saved: Settings › Providers shows API key saved under the account's name.

Usage data is stale#

A provider header shows Updated … ago when its data is more than 10 minutes old.

• Refresh manually with ⌘R.
• Check Settings › General › Refresh interval. With Manual, UsageNow refreshes only when you open the popover or press Refresh.
• For Codex, stale limits usually mean the app-server couldn’t be reached, so UsageNow is using the last limits recorded in Codex’s session files. Make sure Codex is signed in and can reach the internet. With ChatGPT 26.9 or later and UsageNow 0.5.0 or earlier, Codex limits stopped updating because ChatGPT moved its bundled codex; UsageNow 0.6.0 finds it again.
• For Claude Code, stale limits come with Refresh Claude Code from Terminal to view usage limits. Launch claude in Terminal; see Claude token is stale.
• A line such as Couldn’t refresh Codex means the last refresh failed. Choose Retry.

Widget shows old data#

The widget shows the last snapshot the UsageNow app wrote.

• Make sure UsageNow is running. The widget can’t refresh providers itself. Turn on Launch at Login to keep it running.
• Open the popover to trigger a refresh.
• Old values keep their original reading time, with a stale indicator per provider. After a quota reset, the old percentage becomes unknown until a new reading arrives.
• Upgrade to 0.8.0 for the fixes to provider freshness, unchanged-value timestamps, ticking countdowns, and development/release widget separation.
• Right after an update, if the widget shows Open UsageNow to load usage data., open UsageNow once. Widgets from 0.6.0 on read data from a newer app too; earlier ones couldn't.

A new connection will not save#

Check and Save makes a read-only usage request before writing to Keychain. Check the specific error: credential format, expired or rejected sign-in, missing permission, network failure, unsupported response, or Keychain failure. Canceling preserves the old connection.

• Cursor and Perplexity use a web session, not an API key. Some SSO providers block embedded windows; use the manual named session-cookie fallback only in the connection sheet.
• Copilot uses an experimental endpoint. A token accepted by GitHub's billing API is not guaranteed to work here; do not add broad permissions blindly.
• ElevenLabs requires user_read. Z.ai supports the global Coding Plan endpoint, not China-platform keys.
• HTTP 429 pauses that connection according to Retry-After, or five minutes by default. Manual Retry cannot bypass the pause; other accounts continue updating.
• Windsurf is different: no connection credential is needed. Open Windsurf to refresh its own cached plan.

See Connect a provider. Never include a key, token, cookie, or sign-in screenshot in a bug report.

Widget does not appear#

• If you built UsageNow yourself without a signing team, the widget shows only Open UsageNow to load usage data. See Enable the widget in a local build.
• Open UsageNow at least once, then look for UsageNow in Edit Widgets.
• If the widget shows No providers enabled, turn on a provider in Settings › Providers.

Launch at Login does not work#

• If Settings shows Allow UsageNow in System Settings to finish setup., choose Open Login Items… and allow UsageNow.
• Check System Settings › General › Login Items to confirm UsageNow is listed and allowed.
• If turning the setting on shows an error, the message under the switch comes from macOS.

No providers enabled#

The popover shows No providers enabled when every provider is turned off. Choose Open Provider Settings and turn on the tools you use.

If it shows No providers detected, your enabled providers aren’t installed on this Mac. See the detection sections above.

Still stuck?#

Choose Settings › About › Report a Problem. It collects the details that help — versions, screens, settings, and what each provider shows — without names, file paths, keys, or prompts, shows you all of it, and opens a prefilled GitHub issue or email. Add what you saw and, if you can, a screenshot. See Settings.

If you'd rather write it yourself, open an issue with your UsageNow version and build number (in Settings › About), your macOS version, and what you see. Please don’t include prompts, tokens, account details, or files from ~/.codex or ~/.claude.