Auto Switch

Auto-switch

OpenSwap can watch usage and change the default Claude Code login before you hit a rate limit. The CLI (openswap auto) and the macOS extra share the same engine, state file, and autoswitch.* settings. Codex CLI has its own rotation, gated by autoswitch.codexEnabled (default on). ChatGPT suggestions only propose a restart you confirm, and only after Enable ChatGPT switching is on. ChatGPT.

Turn it on

openswap auto                          # foreground, polls every 60s
openswap auto --threshold 80
openswap auto --model Fable            # also honor that model's weekly limit
openswap auto --once                   # one check, for cron
openswap auto --dry-run
openswap auto --strategy consume-first

From the extra: Settings → Automation → Auto-switch Claude accounts.

The extra at login with auto-switch on is the usual “leave it running” setup on macOS. You do not also need an openswap auto terminal.

Strategies

Set with openswap auto --strategy …, openswap config set autoswitch.strategy …, or Settings → Automation → Choose the next account by.

Strategy	When it moves	Who it picks
best (default)	Active account’s 5-hour or 7-day window (whichever is closer to the limit) reaches 90%	Most remaining quota
consume-first	Proactive, even below the threshold	Soonest weekly (7d) reset, with room to spare
soonest-5h	Proactive, even below the threshold	Soonest 5-hour session reset, with room to spare

consume-first is use-it-or-lose-it on the week. Weekly windows do not recycle as fast as the 5-hour session, so that strategy ranks by the 7-day reset, not the 5-hour countdown you might see in the popover. If you actually want the account whose session resets soonest (Ads Online in 4 hours), pick soonest-5h.

The popover shows a one-line hold reason when a consume strategy is on: why it is staying on the current account, or which account it would pick.

The popover’s “2 hours” on a 7d / Fable row is that weekly clock. The 5h row is the session window.

Threshold, cooldown, and switching gap

Defaults:

Setting	Default	Meaning
autoswitch.threshold	90	Switch when the closer 5-hour or 7-day window reaches this percent
autoswitch.cooldownSeconds	300	Minimum seconds between proactive switches
autoswitch.hysteresisPct	10	Target must beat the active account by this many percent
autoswitch.intervalSeconds	60	CLI poll interval
autoswitch.codexEnabled	true	Rotate Codex CLI accounts alongside Claude

A candidate must itself sit below the threshold (never land somewhere that would fire again next tick). Two accounts hovering at the line will not ping-pong.

A manual pick from the extra (clicking a Claude card, Rotate, or Best) starts that same cooldown. consume-first will not undo your pick for five minutes. An account at 100% still fails over immediately.

ChatGPT suggestions and live Codex CLI rotation cannot both be on. Turn off Suggest ChatGPT account switches to auto-rotate Codex CLI.

Per-model weekly limits

By default only the account-wide 5h / 7d windows drive switching. If you burn a model’s weekly limit first (for example Fable):

openswap auto --model Fable
openswap config set autoswitch.model Fable
openswap config set autoswitch.model Fable,Opus
openswap config set autoswitch.model all

Names are Anthropic display_names, case-insensitive. They appear as extra rows in openswap list and in the popover.

API credit as the last resort

An API key linked to a subscription (openswap add-token … --for N) is used only when every subscription is at its limit (or none is in rotation). A proactive or consume-first move never lands on a key. While Claude Code runs on the key, auto-switch watches for a subscription to drop back below the threshold and moves you back to it; the popover says Holding on API credit meanwhile.

A key marked API key revoked or invalid, API key out of credit or API key at its spend limit is never a target. If auto-switch put you on it and it stops working, it moves you off at once, like an account at its limit; when nowhere has room it holds and says why.

Claude Code on a key spends credit bought in the Claude Console, not the API credit included with Max and Team. OpenSwap does not cap that spend; set a spend limit on the key’s Console workspace.

Safety

• Switches take the same credential locks Claude Code uses, so a swap never collides with a token refresh.
• Failed usage fetches keep the last-known numbers and back off. An expired token on an idle machine makes the engine hold, not fail over (Claude Code refreshes on your next message).
• A dead refresh token quarantines that slot until you log in and openswap add --slot N, or import a known-good backup.
• API-key accounts are a last resort only: linked with --for, or unlinked with autoswitch.includeApiKeyAccounts on.
• Disabled accounts (openswap disable) are out of rotation.
• ChatGPT desktop restarts are never unattended. ChatGPT.

Cron / --once

Exit codes: 0 switched, 1 error, 2 nothing to do, 3 blocked (no viable target).

*/5 * * * * openswap auto --once --json >> ~/.openswap-auto.log 2>&1

--json on openswap auto is an event stream (one object per line): poll, switch, no-switch, account-quarantined, all-exhausted, error. Ignore unknown kinds.

Shared files

File	Role
settings.json	autoswitch.* policy (CLI and extra). openswap config
autoswitch_state.json	cooldown, last switch, quarantines; delete to reset
menubar_settings.json	extra-only: Claude/ChatGPT/Codex toggles, title, kickoff

See Configuration.