FAQ

VibeQuota helps developers see when Claude or Codex usage is getting close to practical limits. It shows your usage windows, reset timing, account status, and related usage context wherever that data is available — right from your Mac menu bar or your phone.

VibeQuota V1 supports Claude and Codex. More providers may come later.

No. VibeQuota shows the latest known usage and reset information from the provider. When it shows status language like Heavy or Limit Risk, treat it as a conservative warning — not an exact prediction.

No. VibeQuota is an independent app. It is not official, endorsed, sponsored, or operated by Anthropic, OpenAI, or any other provider.

For iPhone use, yes. The Mac app collects your usage data and syncs it; the iPhone app displays that synced data. You can use the Mac app entirely on its own — but the iPhone app needs Mac-synced data to show real usage.

It runs in your menu bar and collects usage data for Claude and Codex. It shows current usage in the menu, updates your desktop widgets, and can sync snapshots to iCloud for the iPhone app.

Open VibeQuota from the menu bar, then go to Settings → Providers. From there you can select Claude or Codex, enable or disable it, refresh it, and manage connection options.

Use the Refresh action in the menu bar menu, or the refresh button in Settings → Providers for a specific provider.

Yes. Go to Settings → General → Refresh cadence. You can choose manual refresh or automatic intervals such as 1, 2, 3, 5, 15, or 30 minutes. If you pick manual, the automatic timer is turned off and you refresh whenever you like.

Yes — use Settings → General → Start at Login.

Yes. On Mac use Settings → Advanced → Hide personal information; on iPhone use Settings → Usage Settings → Hide personal information. This obscures email addresses in the app UI.

Yes. On Mac use Settings → Display → Show usage as used; on iPhone use Settings → Usage Settings → Show remaining usage.

Session is usually the provider's shorter active usage window. Weekly is a longer window when the provider exposes one. The exact definitions come from the provider's own data.

Reset is the time a usage window is expected to reset, as reported or derived from the provider. If the provider doesn't expose a reset time, VibeQuota may show a pending or unavailable state.

They're simple status labels based on usage percentage:

• OK — usage is low.
• Moderate — usage is around the middle of the window.
• Heavy — usage is high.
• Limit Risk — usage is near the limit.
• Unavailable — no usable data for that provider.

Where available, yes — it can show estimated local cost, credits, or dashboard extras when a supported source provides them. Availability depends on the provider, account state, and your enabled options. Costs are estimates or provider-reported summaries; your provider's own billing page is always the final authority.

The Mac app supports a first-party Claude OAuth sign-in flow. Depending on your build and environment, it may also support Claude web sign-in or a local Claude CLI fallback. Connect under Settings → Providers → Claude.

Common reasons:

• Claude is disabled in settings.
• Claude sign-in hasn't been completed.
• The saved Claude session expired.
• The selected source can't read usage.
• The provider didn't return a weekly/session window.
• Network or provider service issues blocked the refresh.

Some Claude accounts or sources don't return every usage window. VibeQuota will still show whatever windows it can read.

No. VibeQuota is designed not to collect, sync, or analyze prompts or code. Provider integrations only use the limited data needed to determine usage state.

Yes, when an Anthropic Admin API key is configured. This can show organization-level spend, message, or token summaries. Only configure an Admin API key if you understand and intend to use that feature.

Codex support can use Codex OAuth credentials and the Codex CLI RPC. Optional Codex web usage can add dashboard extras like credits, code review usage, usage breakdown, and credits history when enabled. Connect under Settings → Providers → Codex.

Some Codex paths need permission to read local Codex data, such as files under the Codex configuration directory. This is limited to known Codex locations and is meant to be visible to you.

An optional setting that uses your chatgpt.com / Codex web session to display extra dashboard details. It's opt-in because hidden web refreshes can use network and battery. Battery Saver reduces routine background refreshes for these extras — manual refresh still works whenever you want it.

Yes. The Mac app has account controls for Codex, and the iPhone app groups multiple accounts for the same provider.

Check that:

• Codex is enabled in Settings → Providers.
• The selected Codex usage source is available.
• Codex credentials are valid.
• Any requested folder access has been granted.
• The local Codex CLI works, if you're using a CLI-backed path.
• Optional web usage is enabled only if you want web dashboard extras.

The Mac app writes usage snapshots to your private iCloud database, and the iPhone app reads those snapshots. The flow is:

• Claude/Codex usage is collected by the Mac app.
• The Mac app writes local widget data and CloudKit sync data.
• The iPhone app fetches the latest private CloudKit data.
• iPhone widgets read the iPhone app's local widget cache.

Yes, for cross-device sync. Your Mac and iPhone should use the same iCloud account, and iCloud Drive / CloudKit access must be available.

No. VibeQuota is built around local device storage and your private iCloud database — there's no VibeQuota server in the middle.

Things like provider name, usage percentage, reset time, last updated time, sync status, provider availability, error status, source device name, account display identity (to tell accounts apart), and cost/token summaries where collected.

It does not sync prompts, code, raw logs, API keys, access tokens, cookies, credentials, environment variables, repository names, or file paths.

The iPhone app fetches data on launch, when returning to the foreground, on pull-to-refresh, from CloudKit silent pushes, and periodically while open (roughly every two minutes). Background timing is ultimately controlled by iOS and iCloud.

Pull down on the Usage list, or open Settings → About & Sync and tap the refresh button in Sync Status.

Usually the iPhone hasn't found Mac data in iCloud yet. Check that:

• The Mac app is installed and has run at least once.
• Claude or Codex is enabled on Mac.
• iCloud Sync is enabled on Mac (Settings → Mobile).
• Mac and iPhone use the same iCloud account.
• The Mac has successfully refreshed provider data.
• The iPhone has network access.

Incompatible Data means the iPhone found synced data it couldn't decode — update VibeQuota on both Mac and iPhone so they share the same format. Sync Error means the CloudKit fetch couldn't complete, usually due to network issues, iCloud account/storage problems, or a temporary CloudKit service error.

Yes. The iPhone app can read snapshots from multiple Macs and merge them into one view. See which Macs are syncing under Settings → About & Sync in the Devices section. If one Mac is on an older version, the iPhone may flag it as outdated (or using legacy key-value sync) — update that Mac for the most complete data.

The latest provider usage synced from your Mac. It has two tabs: Usage and Settings.

No. It's a display client — it doesn't log in to Claude or Codex directly and doesn't collect provider usage itself. That's why onboarding notes the Mac app is required: the Mac is the collector, and it must push data to iCloud before real usage appears.

Demo mode lets you preview the iPhone UI with sample data before your Mac has synced real data. Tap Exit Demo to leave it.

It shows provider cards for synced Claude and Codex data — provider name, account identity when available, usage windows, reset timing, status messages, a cost teaser, and account grouping. Tap a card to see the detailed rate-limit windows, provider-specific details, and utilization history if synced.

It means the iPhone has grouped multiple accounts for that provider. Tap the provider to switch between accounts in the detail view.

If data from different Mac versions looks like the same account but can't be linked automatically, the iPhone may ask whether the records are the same. Confirm only when you recognize them as the same login. You can undo a merge later from the provider card's context menu.

Setup Guide, About & Sync, Release Notes, Usage Settings, Troubleshooting, and a link to vibequota.com. Usage Settings cover remaining vs used quota, the quota warning marker, changelog link visibility, and hiding personal information.

Yes — it can send quota transition alerts and related sync notifications. You can deny permission and still view synced usage when you open the app. Timing and delivery are controlled by iOS, APNs, and iCloud.

macOS: VibeQuota Switcher, Usage, History, and Metric — these read the local snapshot written by the Mac app.

iPhone: Home screen small / medium / large, plus lock screen circular, rectangular, and inline. They show Claude and Codex usage from the latest synced snapshot, including session and weekly usage where available.

No. Widgets show the latest snapshot available to WidgetKit, and the operating system decides when widgets reload. VibeQuota asks widgets to reload after a successful refresh, but it can't guarantee real-time updates.

Preview — the widget is using placeholder data because it hasn't loaded a real snapshot yet. Open the app, let it sync, then wait for the widget to refresh.

Open app to sync — the widget has no current local data. Open VibeQuota on that device so it can fetch iCloud data and write the widget cache.

No widget data — the cache exists but has no usable provider data. Check that Claude or Codex is enabled on the Mac, the Mac has refreshed, and the iPhone has synced.

The snapshot is older than the freshness window — open the app or refresh sync to get newer data. Freshness is separate from how high your usage is:

• Fresh — updated within ~5 minutes.
• Stale — about 5 to 30 minutes old.
• Expired — older than ~30 minutes.
• Unavailable — no usable snapshot exists.

Alerts related to usage window changes — for example usage reaching a warning threshold, a session becoming depleted, or usage being restored.

Yes. On Mac, use Settings → General for local session quota and warning notifications. For iPhone push forwarding, use Settings → Mobile → iOS Push Notifications. You can also manage permission in iOS Settings.

Visual threshold markers on the usage bars that show when a window is approaching a configured warning level. The Mac app exposes warning threshold settings in General and provider settings; availability can vary by build and provider.

Yes — a 7-day app-managed trial. The trial clock is stored locally in your Mac Keychain.

VibeQuota unlocks with a one-time lifetime purchase. The Subscription tab (Settings → Subscription) shows your access state, trial status, unlock controls, and restore purchase.

If no lifetime unlock is active, provider collection pauses and synced/widget surfaces are cleared or locked rather than showing stale active data. If purchase status can't be checked (e.g. you're briefly offline), the app handles it carefully so you aren't immediately locked out during a temporary problem.

Yes — use Settings → Subscription → Restore.

No. The purchase integration uses RevenueCat for purchase and entitlement state only. Provider credentials, usage values, account emails, prompts, code, and logs are not sent to RevenueCat.

VibeQuota is designed not to collect, transmit, or analyze:

• Prompts and code
• Repository names and file paths
• Raw logs
• API keys, access tokens, and credentials
• Environment variables
• Browser cookies and session tokens
• Usernames from local paths

Some optional provider paths may use browser cookies or manual cookie headers to read usage data. These paths are meant to be visible to you, limited to provider-specific origins, and never sent to analytics or crash reporting. Manual cookie headers are secrets — only paste them into VibeQuota if you understand the flow, and never share them publicly, commit them, or put them in screenshots.

The compatibility config file is ~/.codexbar/config.json. It may contain provider settings, manual cookies, API keys, source selection, ordering, and token accounts — keep it private. The path still says "codexbar" because some internal paths are inherited from the upstream codebase and can't be renamed casually without breaking existing user data or migrations.

If analytics is ever enabled, only privacy-safe product events are allowed — never prompts, code, file paths, provider responses, tokens, credentials, or raw usage details. Crash/error reporting is planned with privacy scrubbing and must not attach raw provider logs, prompts, code, file paths, tokens, cookies, or credentials.

• Open VibeQuota from Applications.
• Check whether macOS hid menu bar extras due to limited space.
• Restart the app.
• Check Settings → General → Start at Login if you expected it to launch automatically.

Open Settings → Providers and confirm the provider is enabled. VibeQuota V1 only shows Claude and Codex.

Use Refresh from the menu bar or Settings → Providers. If the provider still fails, check its sign-in/source settings and any displayed error message.

• Refresh the Mac app.
• Confirm Settings → Mobile → iCloud Sync is enabled on Mac.
• Open the iPhone app and pull to refresh.
• Check Settings → About & Sync for status and device list.
• Update both apps if versions differ significantly.

No Providers Enabled means a Mac snapshot was found but no provider data is enabled — enable Claude or Codex on Mac and refresh. No Mac data found means no usable snapshot is in iCloud yet — confirm the Mac has iCloud Sync enabled, has refreshed successfully, and uses the same iCloud account.

iPhone: open the app, pull to refresh, then wait for WidgetKit to reload. If needed, remove and re-add the widget; check Settings → Troubleshooting → Raw Sync Data for cache diagnostics. macOS: open the Mac app and refresh — desktop widgets read the Mac app's local snapshot, so they need the Mac app to write a fresh one.

Mock data is synthetic test data that should only appear when debug tooling is enabled — turn it off in the Mac app's Mobile/debug settings and let things sync again. Duplicate or stale accounts can appear from multiple Macs, older versions, or identity changes; the iPhone has merge/unmerge and cleanup tools, but updating all Macs and refreshing usually resolves it.

A description of what you see, plus these non-secret details:

• Mac app version and iPhone app version.
• Whether Settings → Mobile → iCloud Sync is enabled.
• iPhone Settings → About & Sync status.
• Number of devices listed and the provider names affected.
• Screenshots with emails or personal data hidden.

Never send cookies, tokens, API keys, raw logs, prompts, code, repository names, file paths, or credentials.

Right here at vibequota.com.