Connect your accounts.
Know what you’re reading.

Requirements and release information

AIUsageWatch is a free native menu bar app for macOS 14 or later. Public release is in preparation. A verified download link will be added to this website when it is available. Your provider accounts and their own plan charges are separate.

Move the released app to Applications before enabling Open at login. The app lives in the menu bar and does not need a Dock icon. Opening the running app from Finder brings Preferences to the front.

Connect your providers

1. Codex: install and sign in to the Codex CLI. Point the account at its configuration directory, usually ~/.codex. The app uses the saved login for that directory through the local CLI app-server.
2. Claude: the default ~/.claude account uses your Safari session at claude.ai. In Preferences, grant access to Safari’s Cookies.binarycookies file. For a separate Claude configuration directory, sign in with Claude Code using that CLAUDE_CONFIG_DIR; the app reads its .credentials.json.
3. Cursor: sign in at cursor.com in Safari and grant access to the Safari cookie file in Preferences. Cursor does not use an account directory for its reading.
4. Grok: select the Grok directory containing logs/unified.jsonl. Run Grok to update the billing reading in that log.

The app reads the available allowance information for each source. Claude and Codex CLI sources need their relevant saved login. The website preview never accesses your accounts.

Personal and work accounts together

Open Preferences… from the menu, or press ⌘,. Each account has a label, provider, directory, colour and letter. Use + to add a directory; the app guesses the provider from its contents. Check the provider before using the new account.

For another Codex login, select its separate CODEX_HOME. For another Claude login, use a separate CLAUDE_CONFIG_DIR with its own saved credentials. The default Claude Safari session can be ambiguous when it contains multiple organisations; use a separate configuration directory in that case. Cursor’s reader uses the available Safari session, so adding a duplicate Cursor row does not create an independent login.

More accounts add columns, with at most three rows in each column. Custom letters and colours help identify accounts. General settings include refresh timing, percentage markers, letters and a warning for supported Codex banked reset expiry information.

Understand the bars

The filled part means remaining allowance. At 0% remaining there is no filled bar. Colour identifies an account. The menu shows percentages, available reset times, relevant window details and reading status.

Claude includes weekly and available five-hour details; Codex selects the main weekly limit. Cursor uses its own included-usage figure, whose payload does not name a usage period. Grok uses a weekly credit figure from the CLI log. Percentages from different providers are not equivalent numbers of tokens, prompts or dollars.

Catch Codex banked resets before they expire

When Codex reports available banked resets and their expiry dates, AIUsageWatch can show a warning dot beside the account before the next banked reset expires. Open the menu for the available count and expiry information. An unused banked reset can be lost at expiry; this is separate from the normal time when your weekly allowance resets.

Enable Warn before reset in Preferences and choose 1–14 days ahead. The default is two days, with a red warning dot; you can change the colour. The dot stays visible when account letters are off. The warning depends on the app running, warnings being enabled and expiry data being available and current. It does not automatically use a banked reset or send a system notification.

Codex’s automatic starter request

When a live Codex weekly reading is 100% remaining, AIUsageWatch sends one small codex exec request using that directory’s saved CLI login. Its purpose is to start a weekly window that may otherwise stay idle. It uses Codex’s default available model and consumes a small amount of that account’s allowance.

A red dot marks the account while the request is running or if it fails. The menu explains the status and provides a manual retry. The app remembers the attempt in memory for that weekly window. Repeated polls do not send more requests for that remembered attempt; relaunching clears the memory and may result in another request if the live reading is still 100%.

Historical transcript fallback does not send starter requests. Claude’s automatic starter is not enabled in the current build. This is separate from reading usage, and the current preferences do not provide a Codex starter toggle.

A number is old, missing or unexpected

• Saved reading: the last good reading is cached on your Mac and restored on launch. The menu says how old it is when a refresh fails.
• Rate limit or connection failure: retries back off for 15 minutes after a rate limit and 2 minutes after other errors. Refresh now bypasses that backoff.
• Safari connection: check the correct provider is signed in, review the cookie-file grant and confirm that the session is unambiguous.
• Grok: run the CLI to record a new usage reading. An expired window or older log is shown as historical rather than a live balance.
• Codex: confirm the CLI is available and that the configured directory has the intended login. Transcript fallback may show older information if the app-server is unavailable.

Provider endpoints and payloads can change. A reading does not guarantee that a provider will accept the next request. Check the provider’s own account page when a balance or reset looks wrong.

Local settings and provider connections

Preferences and cached readings live in ~/Library/Application Support/AiUsageWatch/. The app does not directly read the Keychain. Provider CLIs manage their own login behaviour. Live readers contact the relevant provider using the existing session or credentials. Read the privacy policy for the distinction between local app storage, provider connections and support messages.

Report a problem

Contact AIUsageWatch support with the app version, macOS version, provider, reading status and steps that reproduce the issue. If you use the diagnostic --dump mode, review its output before sending it. Remove tokens, cookie values, private account paths and any other sensitive information. Do not upload credential files.