Security

UsageNow reads data written by tools that have access to your code and accounts, so it’s designed around a few strict boundaries. Issues that break any of them are security bugs.

Local-first design#

Usage data stays on your Mac. Nothing UsageNow reads from other tools — ~/.codex, ~/.claude, ~/.gemini, ~/.kiro, ~/.qoder, ~/.qwen, ~/.cline, ~/.grok, Cline's editor tasks, or the Warp and OpenCode databases — is sent to UsageNow servers, and UsageNow works without an account.

Credentials boundary#

• Codex — UsageNow never reads Codex credentials. The official Codex app-server authenticates itself. UsageNow checks only whether Codex’s credentials file exists.

• Claude Code — the experimental usage limits feature is off by default. Only after you turn it on does UsageNow read the existing access token from the keychain. The token stays in memory, is sent only to api.anthropic.com, and is never logged or written anywhere.

• Kiro and Warp — UsageNow reads no credential for either. Kiro's limits come from its own log and Warp's activity from its local database, opened read-only.

• Qwen Code, Cline, and Grok Build — UsageNow reads no credential for any of them: not Qwen Code's oauth_creds.json, not Cline's secrets.json or the editor's secret storage, and not Grok Build's sign-in. Only the numbers described in Privacy are decoded.

• OpenCode and Qoder — UsageNow reads no credential for either. OpenCode's database is opened read-only, and SQLite hands over only each answer's time, model, and token counts. Qoder's transcripts are read for each answer's time, identifier, and credits; its sign-in files are never opened.

• Windsurf — only the cached plan is selected from its read-only database, never credential entries.

• JetBrains AI — bounded local quota XML and log reads only. No credentials, Keychain access, sign-in, or JetBrains network client. Unknown local formats remain unavailable; active-subscription validation is pending.

• Antigravity — the IDE's loopback server or the official CLI's fixed read-only usage report. The CLI authenticates itself; UsageNow never extracts credentials, impersonates client headers, or starts an agent turn.

• Keys, tokens, and sessions you add — for explicit connections, including the API key providers. A key is stored only in the Keychain on this Mac, sent over HTTPS only to that provider's host, used only for read requests, and deleted when you turn the provider off. A key for an added account is kept the same way, and is also deleted when you remove that account. Redirects aren't followed, and an answer from any other host is refused, so the key can't be passed on. See API Key Providers.

UsageNow never refreshes, modifies, or stores your Claude Code credentials.

Cursor, Copilot, Perplexity, Z.ai, and Ollama Cloud use undocumented usage endpoints, so those providers are labeled Experimental. An answer UsageNow doesn't recognize shows the limits as unavailable rather than a guessed number.

Connection checks happen before Keychain changes. Redirects are refused, and the usage transport has no shared cookie jar. Cursor and Perplexity browser sign-in uses a nonpersistent store without importing other browser profiles or injecting credential-reading scripts. Only permitted session cookies are selected. HTTP 429 cooldowns are shared by manual refresh and connection verification; no credential is stored in the cooldown cache.

Public service incidents are optional and separate from provider authentication. Requests contain no account or usage data; redirects, cookies, and credentials are disabled. Quota pace observations stay in a bounded local cache and never enter telemetry.

Widget isolation#

The widget extension renders a sanitized snapshot written by the main app. It doesn’t read provider files, open the keychain, launch processes, or make network requests — the provider and credential code isn’t compiled into the widget at all. See Widgets.

Provider parsing rules#

• Session files are read for timestamps, identifiers, model names, token counts, and rate limits only.
• Lines that hold conversation content are skipped without being decoded.
• Prompts, responses, tool inputs, and code are never stored or logged.
• Responses UsageNow doesn’t recognize are skipped rather than guessed at. When data can’t be understood, UsageNow shows nothing instead of a wrong value.
• Turning a provider off stops all file and credential access for it.

Logging#

UsageNow writes diagnostic messages to the macOS unified log (OSLog) under the subsystem com.usagenow.UsageNow. Logs never include tokens, credentials, prompts, conversation content, source code, or file paths from ~/.codex or ~/.claude. Values written into log messages are private by default, and only non-identifying values such as status codes are marked public.

No credential modification#

UsageNow doesn’t change files, settings, or keychain items that belong to Codex or Claude Code. When a Claude Code sign-in expires, UsageNow asks you to refresh it with Claude Code rather than renewing it itself.

Update signing#

UsageNow installs an update only when it is signed with the private half of an EdDSA key whose public half is inside the app. That private key exists in one place — the maintainer's keychain — and is in no build, no script, and no part of the public repository, so nothing published there can produce an update UsageNow will accept. Apple's own check applies as well: every release is signed with a Developer ID certificate and notarized.

A build that carries no public key, which is any build not made by the release process, doesn't start the updater at all.

Notifications and the keyboard shortcut#

Notifications about limits are off by default and local: UsageNow hands macOS a title and a line of text — a provider's name, a percentage, a reset time — and nothing is sent anywhere. macOS shows them wherever your notification settings allow, including the Lock Screen.

The keyboard shortcut uses the system's hot key API, which needs no Accessibility or Input Monitoring permission. macOS tells UsageNow only that its own shortcut was pressed; UsageNow never sees anything else you type. See Settings.

Report a Problem#

Settings › About › Report a Problem shows its whole report before anything leaves your Mac and sends nothing itself: it opens a prefilled GitHub issue or email. Account names, emails, file paths, keys, tokens, and prompts are never in it, and error messages are cleaned of paths, emails, and key-shaped strings before they're included.

Reporting a vulnerability#

Please don’t open a public issue for security problems. Report them privately through GitHub’s private vulnerability reporting on the UsageNow repository.

Include a description of the issue and its impact, steps to reproduce, and the UsageNow and macOS versions you tested.

The full policy, including supported versions, is in SECURITY.md.