Multi Account Rotator

Multi-Account Rotator

v2.11.5 — Multi-account Claude Max rotator with launchd/systemd daemon + AI-brain heuristics, so you never blow a weekly cap during long autonomous runs. Now includes private-first account selection (v2.11.4) and Linux headless browser-auth (v2.11.5).

What it does

If you run Claude Code at scale (long-running orchestrations, autonomous overnight runs, multiple parallel sessions), you can blow your Claude Max weekly quota. The rotator:

1. Stores credentials for multiple Claude Max accounts in macOS keychain.
2. Polls each account's remaining quota every N minutes.
3. Before any single account hits its cap, swaps the active Claude Code-credentials keychain entry to the next available account.
4. Refuses to rotate to an account with overage billing enabled (so you don't accidentally rack up credit-card charges).

Components

Path	Role
scripts/account-rotation/rotate.mjs	Swaps the Claude Code-credentials keychain entry.
scripts/account-rotation/daemon.mjs	launchd-managed; polls usage, rotates ahead of cap.
scripts/account-rotation/ai-brain.mjs	Haiku-powered heuristic — picks next account based on remaining quota + usage trajectory.
scripts/account-rotation/setup-account.mjs	OAuth init for one account.
scripts/account-rotation/force-rotate.sh	Manual override.
templates/com.claude-ops.account-rotation.plist	launchd unit.
skills/ops-rotate/SKILL.md	/ops:rotate — manual rotate.
skills/ops-rotate-setup/SKILL.md	/ops:rotate-setup — multi-account onboarding.

Setup

/ops:rotate-setup        # interactive multi-account onboarding
/ops:setup               # step 3o walks through OAuth init for each account

account_rotation_enabled is opt-in (default false) — you must explicitly turn it on in /plugins settings.

Hard guardrail

The rotator refuses any account that has overage billing enabled, unless you pass --allow-extra-usage. This is intentional — accidentally rotating to an account with overage on means real credit-card charges when usage exceeds the included monthly quota.

Configuration

Key	Type	Default	Purpose
account_rotation_enabled	boolean	false	Master switch (opt-in).
account_rotation_setup_oauth_each	boolean	true	During /ops:setup, walk through OAuth init for every configured account that lacks a keychain token.

Private-first account selection (v2.11.4)

When multiple accounts are eligible, rotate.mjs prefers personal/private accounts over TEAMS/org accounts (those with orgName or orgUuid set in config.json). Org accounts trigger claude.ai's organisation chooser page and may require Google Workspace push-2FA that headless browser auth cannot clear.

To use an org account despite this preference, add "preferEvenIfOrg": true to its config entry.

Linux headless browser-auth (v2.11.5)

The browser-auth fallback now works on aarch64 and x86-64 Linux without a desktop environment:

	macOS	Linux
Browser	Chrome (headed)	Brave (Tier-2; no ARM Chrome builds exist)
Display	native	Xvnc virtual — DISPLAY=:1, 1280×800 minimum
Auth	magic-link or Google OAuth	magic-link only
Inbox reads	default Gmail account	gog --account <email> per-account

Minimum Linux setup:

# 1. Install Brave
sudo apt-get install -y brave-browser   # Debian/Ubuntu

# 2. Start a virtual display (1280x800 — narrower viewports break claude.ai)
Xvnc :1 -geometry 1280x800 -depth 24 &
export DISPLAY=:1

# 3. Register each rotation email with gog
gog auth add you@example.com --services gmail

Full steps: scripts/account-rotation/README.md §Linux setup.

See also

• Configuration — all userConfig toggles.
• Setup Wizard — step 3o (OAuth init) and 6.5d (rotator toggle).
• Notifications — push alerts via Telegram bot, ntfy, Pushover, Discord.
• OS Compatibility — Linux headless browser-auth matrix.