AI Battery Settings Guide

Updated October 2026 · AI Battery 3.1

AI Battery's settings open from the gear icon in the top-right corner of the popover. This guide explains every option for both Claude and Codex accounts.

Accounts

AI Battery supports up to 3 Claude and 3 Codex accounts; each keeps its own rate limits, token stats, and persistent ledger. In an account's detail view the popover header is the account: a chip with the provider's brand mark, the account identity, and a small switcher glyph. Click it to switch between accounts (grouped by provider, plan shown per row) or to add one.

The overview

With two or more accounts the popover opens on an overview instead of whichever account you looked at last — one account sees no change. Each account is a card: the provider mark and identity (the active account carries an active badge), its quota bars with the tokens spent in each window, and a state line with the time to limit and the reset countdown. A small live dot breathes beside an account's name while its provider's CLI has been active in the last five minutes, so the list also says which account you are hitting right now. Credits and API-key accounts show today's tokens on the state line instead.

• Drill in — click a card (or press 1–6) to open that account's full view. The back chevron beside the account chip, or Esc, returns to the overview; Esc from the overview closes the popover. r refreshes every account.
• It remembers where you were — drill into an account, click away, reopen, and you are still in that account; the back chevron brings you back to the overview. A relaunch opens on the overview again.
• Signed-out accounts stay on the list as a sign-in card ("Signed out · click to sign in") rather than disappearing.
• Status dots are exceptions, not readouts: a provider's dot appears only when Anthropic or OpenAI is reporting a degraded or down component.
• Footer — the overview has its own footer with a labelled Settings button, the refresh control with how fresh the cards are, and Quit. Adding accounts happens in Settings.

In Settings, the Accounts rows list every account with its provider mark, a name field, and a remove button (×). Removing an account deletes its stored credentials from macOS Keychain.

Add Claude Account…

• Opens Anthropic's OAuth 2.0 sign-in in your browser (PKCE, the same protocol Claude Code uses).
• Sign in, copy the authorization code, paste it into AI Battery.
• The refresh token is stored in macOS Keychain; the access token is held in memory only.

Add Codex Account…

Pick one of three ways:

• Sign in with ChatGPT — the browser opens OpenAI's sign-in and redirects straight back to AI Battery on 127.0.0.1:1455. Nothing to paste.
• Import Codex CLI login — reuses the login from codex login by reading ~/.codex/auth.json once, only when you click the button.
• OpenAI API key — paste an sk-… key. Its shape is checked locally before any network request; if the key can't be verified while offline it is added with a note and checked on the first refresh. The key is stored in Keychain like a refresh token.

What you see afterwards depends on the plan: ChatGPT subscriptions show a 5-hour and a weekly window (plus any purchased-credit balance), Business and Enterprise spend-control workspaces show a single Credits budget bar, and API keys show OpenAI's per-minute API Limits with your real spend at API rates.

Names and identity

• Name field — an optional alias shown in the header chip and its menu. The placeholder shows the account's own identity so you know which is which.
• Without an alias, the chip shows the Codex sign-in email or the Claude workspace name, and falls back to "Claude 1" / "Codex 2", numbered within each provider.
• Emails are masked in the popover (k•••@domain) unless you turn on Full account email in popover. Settings placeholders are never masked.

Refresh

Controls how often AI Battery asks your provider for fresh rate-limit data.

• Range: 30 seconds to 5 minutes, in 30-second steps
• Default: 2 minutes
• Cost per poll (shown under the slider; with several accounts it reads "×N accounts", because every account is polled): Claude ≈ 3 tokens; Codex with ChatGPT sign-in none — it reads the usage endpoint; Codex API key ≈ 16 output tokens, billed at API rates

AI Battery also polls adaptively: after three unchanged cycles the interval doubles step by step, up to 5 minutes, and snaps back to your setting when a session log changes or the Mac wakes. Polling pauses entirely after 5 minutes of system idle. Between polls the last API reading is kept, so the bars are never empty.

Hide idle

Hides context-health sessions that have been idle longer than the cutoff.

• Options: 30m, 1h, 2h, 4h, 8h, or ∞ (never)
• Default: ∞

Display

Colorblind

Replaces the green / orange / red palette with blue, cyan, amber, and purple everywhere a colour carries meaning — rate-limit bars, context health, and the menu bar star.

All accounts in menu bar

With two or more accounts, the menu bar lists every account's percentage (for example 42% | 23%). Each slot shows that account's headline number — the fuller window, the Credits budget, or for an OpenAI API-key account the busier of its per-minute request and token limits — the same figure its overview card leads with, whatever metric tab is selected, so the bar and the overview can never disagree. The star colour and any countdown follow the worst account, and when both providers are connected each group is prefixed with its brand mark. A transient fetch failure keeps an account's previous reading rather than blanking its slot.

With the toggle off and several accounts, the bar shows the worst account's headline alone. Only a genuinely single-account menu bar follows the metric tabs.

Full account email in popover

Shows Codex sign-in emails unmasked in the header chip and account menu. Off by default — safer when screen-sharing. Claude workspace names are never masked.

Menu bar metric

The tabs below the header choose which metric sits at the top of an account's detail view and, with a single account, drives the menu bar star (with several accounts the bar follows the overview — see All accounts in menu bar):

• 5 Hour — the 5-hour window
• 7 Day — the 7-day window (labelled Weekly on Codex). On a Business/Enterprise or API-key Codex account this collapses into a single Credits or API Limits tab.
• Context — context fullness of your most critical active session

Auto mode

The A button to the left of the tabs lets AI Battery pick the most urgent metric for you. It escalates in four tiers:

1. Throttled — a window the provider is actively limiting always wins.
2. Rate limit at 80% or more — shows the higher of the two windows.
3. Context at 60% or more in any active session — shows Context.
4. Otherwise the binding (highest-consumed) rate-limit window.

To stop the menu bar flickering near a threshold, a held mode is released only after its metric drops 10 points below the threshold (rate limits at 70%, context at 50%). Clicking any tab turns auto mode off.

Alerts

Status

Sends a macOS notification when a provider reports an incident. With accounts on both providers, both status feeds are watched; otherwise the active account's provider. For Claude accounts AI Battery watches status.claude.com (claude.ai, Console, Claude API, Claude Code, Claude for Gov); for Codex accounts it watches status.openai.com filtered to Codex API, Codex CLI, Codex in ChatGPT Desktop, Codex Web, and the Codex VS Code extension. A Test button fires sample notifications using the active provider's component names.

Rate Limit

Notifies when usage crosses a threshold you set: 50% to 95% in 5% steps, default 80%. Both windows are monitored (or the Credits budget on a spend-control plan), the alert fires once per crossing and re-arms when usage drops back below. Alerts are per account, so switching accounts never silences or re-fires another account's alert.

Launch at Login

Starts AI Battery when you log in to macOS, using Apple's native SMAppService — no background daemons or launch agents.

About and updates

The last section shows the app version with two links: Check for Updates (turns into a yellow Install vX.Y.Z once a release is waiting) and Release notes. AI Battery checks for updates once a day; when one is available a small arrow breathes beside the Settings gear in both the account view and the overview — click it to install, right-click for release notes or to check again. There's no banner and no badge to dismiss; the arrow disappears once the update is installed. Updates are user-initiated only — nothing downloads in the background.

Context health indicators

These are fixed thresholds, not settings. Percentages are relative to the model's full context window — 1,000,000 tokens for current Claude models, about 258,000 for GPT-5-family models via Codex.

• Green (under 60%) — plenty of room.
• Orange (60–80%) — getting crowded. Consider /compact or a fresh session.
• Red (over 80%) — start a new session for best results.

AI Battery also flags patterns that suggest a session needs attention:

• Long conversation — 15 or more turns of accumulated history.
• High input-to-output ratio — input exceeds output by more than 20:1 (lots of file reads, little produced).
• Rapid token consumption — more than 50K tokens in under 60 seconds.
• Zero-output session — several turns with no output tokens, often an error loop.

For a deeper explanation, see Understanding the Context Window.