AI Battery Settings Guide

Updated March 2026

AI Battery's settings are accessible from the gear icon in the top-right corner of the popover. This guide explains every option.

Accounts

AI Battery supports up to 3 Claude accounts with one-click switching. Each account has its own rate limits, token stats, and session history.

Add Account — opens Anthropic's OAuth sign-in (same protocol as Claude Code). Refresh tokens are stored in macOS Keychain.
Display Name — customize the label shown in the account picker (up to 30 characters). Defaults to "Account 1", "Account 2", etc.
Remove Account — removes the account and its stored credentials. Only available when you have more than one account connected.

Switch between accounts using the dropdown next to "AI Battery" in the popover header.

Refresh Interval

Controls how often AI Battery polls Anthropic's API for updated rate limit data.

Range: 10 to 60 seconds (5-second steps)
Default: 60 seconds
Tradeoff: lower intervals give more frequent updates but slightly more usage overhead

Lower intervals give you more up-to-date numbers but use slightly more tokens. For most workflows the overhead is small relative to normal Claude Code usage.

AI Battery also uses adaptive polling: if the data hasn't changed between polls, it automatically reduces frequency. Activity resumes at the base interval when it detects file changes or a system wake.

Display

Tokens

When enabled, shows a per-model breakdown of your token usage below the rate limit section. For each model (e.g. Opus 4.6, Sonnet 4.5), you'll see:

Input tokens (↑) — tokens sent to the model (your messages, file contents, tool results)
Output tokens (↓) — tokens the model generated (responses, code, tool calls)
Cache read tokens — tokens served from Anthropic's prompt cache instead of being reprocessed (cheaper than regular input)
Cache write tokens — tokens written to the prompt cache for future reuse

The total token count appears in the top-right corner of the Tokens section.

Cost Estimate ($)

When enabled, a dollar figure appears next to each model's token count and as a total at the top of the Tokens section. This is the API cost equivalent — what your usage would cost if you were paying Anthropic's per-token API rates instead of your subscription.

What the $ figure means

The dollar amount does not represent what you're actually being charged on a Claude subscription. It is an API-equivalent estimate for comparison.

The cost estimate shows what the same usage would cost at API pay-per-token rates. It's useful for:

Understanding whether your subscription plan is good value compared to API pricing
Seeing which models consume the most budget in API-equivalent terms
Deciding whether to upgrade or downgrade your plan tier

AI Battery uses configurable API-equivalent pricing rates for these estimates. Because higher-end models are more expensive per token, the API-equivalent cost is usually concentrated in the heaviest model usage.

Activity

When enabled, shows a sparkline chart and summary stats for your Claude Code usage. The chart has three time ranges:

12H — messages per hour over the last 12 hours
7D — messages per day over the last 7 days
12M — messages per month over the last 12 months

Below the chart you'll see trend comparisons (vs. yesterday), your daily average, peak day, throttle count, and cumulative stats for today and all time.

Colorblind Mode

Replaces the default color palette (green/orange/red) with a colorblind-safe alternative using blue, cyan, amber, and purple. This affects all color-coded indicators throughout the app — rate limit bars, context health, and the menu bar icon.

Hide Idle Sessions

Automatically collapses context health entries for sessions that haven't had activity within a specified duration.

Options: 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, or Never
Default: Never (all sessions always visible)

Useful if you run many Claude Code sessions throughout the day and only want to see the active ones in your context health list.

The segmented control below the header lets you choose which metric appears in your macOS menu bar:

5-Hour — your current 5-hour burst rate limit utilization
7-Day — your current 7-day sustained rate limit utilization
Context — the context window fullness of your most recent active session
Pace — today's message count as a percentage of your daily average

Auto Mode

The "A" button to the left of the metric picker enables auto mode, which automatically shows whichever metric is most urgent. The selection logic has three priority tiers:

Throttled — if you've hit a rate limit, it shows the throttled window
Near exhaustion — if any rate limit is at 95% or above, it shows that window
Urgency score — otherwise, it scores all four metrics and picks the most actionable one. Ties are broken by priority: Context > 5-Hour > 7-Day > Pace

When auto mode is active, the manual metric picker is disabled and a "Showing [Mode]" label appears below it.

Alerts

Status Alerts

When enabled, AI Battery monitors status.claude.com and sends a macOS notification when Anthropic reports an outage or degraded performance. Tracked services include Claude API, Claude Code, claude.ai, Console, and Claude for Gov.

A "Test" button appears when enabled so you can verify notifications are working.

Rate Limit Alerts

When enabled, sends a macOS notification when your rate limit usage crosses a threshold you set. The threshold slider ranges from 50% to 95% (default: 80%, in 5% steps). Both the 5-hour and 7-day windows are monitored.

This gives you advance warning before you hit the limit — enough time to wrap up your current task or pace your remaining usage.

When enabled, AI Battery starts automatically when you log in to macOS. Uses Apple's native SMAppService framework — no background daemons or launch agents.

Context Health Indicators

These aren't configurable settings — they're fixed thresholds built into the app. Understanding them helps you interpret what AI Battery is showing you.

Green (under 60%) — plenty of room. Claude has full recall and responds accurately.
Orange (60-80%) — getting crowded. Consider running /compact or starting a fresh session.
Red (over 80%) — auto-compaction is imminent. Start a new session for best results.

AI Battery also surfaces smart warnings when it detects patterns that suggest a session needs attention:

High input-to-output ratio — flagged when input exceeds output by more than 20:1 (a sign Claude is reading lots of files but producing little output)
Rapid token consumption — flagged when a session burns through more than 50K tokens in under 60 seconds

For a deeper explanation of context health, see Understanding Claude Code's Context Window.