| name | ops-rotate-setup |
| description | Interactive OAuth init wizard for the multi-account Claude rotator. Walks through every account in the rotation config and, for any account missing a valid keychain token, delegates to the proven `rotate.mjs` magic-link flow (browser-driver cascade + Gmail polling), which writes the verified OAuth token to `Claude-Rotation-<key>` (key = account label or email, keychain account `$USER`). Re-runnable any time. Standalone alias of the same step inside `/ops:setup`. |
| argument-hint | [--all|--account <email>|--add|--crs] |
| allowed-tools | ["Bash","Read","AskUserQuestion"] |
| effort | medium |
| maxTurns | 25 |
Purpose
Initialize OAuth tokens for the multi-account Claude rotator system (the
account-rotation daemon). For each configured account that does not already
have a valid keychain token, delegate to rotate.mjs --setup --only=<email> --auto --skip-valid, which drives the browser-driver cascade (CDP-attach to a
real Chrome → spawn Chrome with a real profile → bundled Chromium), polls Gmail
for the magic link via gog, verifies the token, and writes it to the OS
keychain under the schema the daemon/rotator consume: service
Claude-Rotation-<key> (key = account label or email), keychain account
$USER (override with $CLAUDE_ROTATOR_KEYCHAIN_ACCOUNT), value
{ "claudeAiOauth": { "accessToken": ... } }.
Why delegate: a freshly launched Playwright Chromium is blocked by
claude.ai's Cloudflare Turnstile (the magic link is never sent), and a
hand-rolled web-cookie capture writes a credential shape no consumer reads.
rotate.mjs solves both correctly, so setup-account.mjs is a thin wrapper
around it.
Use this skill when:
- You ran
/ops:setup and skipped the account-rotation step
- You added a new Claude account and need to wire it in
- A keychain entry was rotated/expired and needs re-init
- You want to re-run only the OAuth portion without touching other ops config
Rules (mandatory)
- Rule 0: Never write real emails to any committed file. Account email and
display name come from runtime user input only.
- Rule 1: Max 4 options per
AskUserQuestion. Paginate at 4 with
[More...] bridges when listing accounts.
- Rule 4: Background by default. The OAuth flow (rotate.mjs browser cascade
- Gmail polling) is long-running; always launch it with
run_in_background: true and tail the log.
- Never auto-enable
account_rotation_enabled after init. The user flips that
switch from /plugins settings.
Step 1 — Load config
USER_CFG="$HOME/.claude/plugins/data/ops-ops-marketplace/account-rotation-config.json"
REPO_CFG="${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/config.json"
CFG="$([[ -f "$USER_CFG" ]] && echo "$USER_CFG" || echo "$REPO_CFG")"
jq '.accounts // []' "$CFG"
If accounts is empty AND no --add argument was passed, jump to Step 2 —
Bootstrap. Otherwise jump to Step 3 — Token check.
Step 2 — Bootstrap (no accounts configured)
AskUserQuestion:
No Claude accounts are configured for the rotator yet. Add some now?
[Add now] — collect email/display/plan, then run OAuth
[Use existing keychain] — skip — assume keychain already has tokens
[Skip] — exit, do nothing
[Help] — explain how the rotator works and exit
[Help]: print one-paragraph explainer (rotator purpose, where keychain entries live, how /plugins toggles account_rotation_enabled) and exit.[Use existing keychain]: print "Looking for Claude-Rotation-* entries..." and run CRED="${CLAUDE_PLUGIN_ROOT}/lib/credential-store.sh"; ACCT="${CLAUDE_ROTATOR_KEYCHAIN_ACCOUNT:-$USER}"; bash "$CRED" backends 2>/dev/null && jq -r '.accounts[] | (.label // .email)' "$CFG" 2>/dev/null | while read -r key; do bash "$CRED" get "Claude-Rotation-$key" "$ACCT" >/dev/null 2>&1 && echo "✓ $key" || echo "✗ $key"; done || echo "(no backends available — re-run with [Add now])". Exit.[Skip]: exit.[Add now]: enter the add loop below.
Add loop
For each new account:
- Prompt for email (free text). Validate
*@*.* shape, reject empties.
- Prompt for display name (free text, defaults to email local-part).
AskUserQuestion for plan:
Plan tier for this account?
[Max] — Claude Max ($100/$200 tier)
[Pro] — Claude Pro
[Team] — Team plan seat
[Other] — type a label
- Append to in-memory accounts list. Then ask:
Account added. Next?
[Add another]
[Done — start OAuth]
[Cancel]
Once [Done], write the new accounts into $USER_CFG (create dirs as needed):
mkdir -p "$(dirname "$USER_CFG")"
jq --argjson new "$NEW_ACCOUNTS_JSON" \
'.accounts = ((.accounts // []) + $new)' \
"$CFG" > "$USER_CFG.tmp" && mv "$USER_CFG.tmp" "$USER_CFG"
Step 3 — Token check
For each account in the merged config, check the keychain under the consumed
schema (service Claude-Rotation-<key>, account $USER):
CRED="${CLAUDE_PLUGIN_ROOT}/lib/credential-store.sh"
ACCT="${CLAUDE_ROTATOR_KEYCHAIN_ACCOUNT:-$USER}"
jq -r '.accounts[] | (.label // .email)' "$USER_CFG" | while read -r key; do
if bash "$CRED" get "Claude-Rotation-$key" "$ACCT" >/dev/null 2>&1; then
echo "✓ $key"
else
echo "✗ $key (needs OAuth)"
fi
done
If every account is ✓, print a success line and jump to Step 5 — Summary.
(rotate.mjs --setup ... --skip-valid also re-checks token validity itself, so
a stale-but-present entry is re-captured during Step 4.)
Step 4 — OAuth init loop
For each ✗ account, run the setup script in the background and tail its log.
SCRIPT="${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/setup-account.mjs"
LOG="$HOME/.claude/logs/account-rotation/setup-${ID}-$(date +%s).log"
mkdir -p "$(dirname "$LOG")"
node "$SCRIPT" \
--email "$EMAIL" \
--display "$ACCOUNT_DISPLAY" \
--plan "$PLAN" \
--account-id "$ID" \
--gmail-poll \
>"$LOG" 2>&1 &
echo "PID=$! LOG=$LOG"
- Launch with
run_in_background: true.
- Use
Monitor (or Read of the log file) to surface progress lines.
setup-account.mjs upserts the account into $USER_CFG, then delegates to
rotate.mjs --setup --only=<email> --auto --skip-valid, which:
- Skips immediately if a valid token already exists (
--skip-valid).
- Runs the browser-driver cascade: attach to a real Chrome on CDP
:9222
(passes Cloudflare Turnstile) → else spawn Chrome with a real profile →
else bundled Chromium.
- Submits the email and polls Gmail via
gog for the magic link, then
completes login (handling the org chooser).
- Verifies the token against
api.anthropic.com/api/oauth/usage.
- Writes it to the keychain as
Claude-Rotation-<key> (account $USER),
value { "claudeAiOauth": { "accessToken": ... } }.
- It emits a single-line JSON result:
{"ok":true,"accountId":...,"email":...}
on success, or {"ok":false,...,"error":"oauth_failed"} on failure.
- 2FA / Google SSO: some accounts (Google Workspace domains) require an
interactive Google verification that automation cannot complete unattended.
If
rotate.mjs logs a 2FA / verification prompt or times out, surface the log
to the user and let them complete the login in the cascade's visible Chrome.
Do NOT attempt to auto-solve 2FA.
After each account completes (success or failure):
Result for <email>:
[✓ Success — continue with next] ← only if more remain
[✗ Failed — view log and retry]
[Stop here]
If success and no more accounts remain, jump to Step 5.
Step 4.5 — CRS relay-pool priority daemon (optional)
If the user runs a claude-relay-service (CRS) pool (load-balances Claude
requests across many accounts at once, exposing a per-account schedulable
flag), offer to install the priority daemon that auto-deprioritizes
near-maxed accounts and re-enables them on recovery. This is independent of the
keychain rotator above — skip it for keychain-only setups.
AskUserQuestion:
Do you run a claude-relay-service (CRS) pool you want auto-prioritized?
[Yes — configure + install] — set base URL + admin creds, install the 120s daemon
[Not now] — skip (you can run /ops:rotate-setup again later)
[What is this?] — one-paragraph explainer, then re-ask
On [Yes]:
- Base URL + admin user. Ask for the CRS base URL (default
http://127.0.0.1:3000) and admin username (default cradmin). Write them
into the rotator config's crs block (create from config.example.json if
missing), and set crs.enabled=true:
CFG="$USER_CFG"
jq --arg url "$CRS_URL" --arg u "$CRS_USER" \
'.crs = ((.crs // {}) + {enabled:true, baseUrl:$url, adminUser:$u})' \
"$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG"
- Admin password → credential store (never written to config). Ask the user
to paste the CRS admin password, then:
CRED="${CLAUDE_PLUGIN_ROOT}/lib/credential-store.sh"
ACCT="${CLAUDE_ROTATOR_KEYCHAIN_ACCOUNT:-$USER}"
printf '%s' "$CRS_ADMIN_PW" | bash "$CRED" set-stdin "CRS-Admin-$CRS_USER" "$ACCT"
(The CRS admin password is printed once in the container's
data/init.json — adminUsername/adminPassword — on first boot.)
- Smoke-test before installing. Confirm the creds + reachability with a
dry-run tick (no writes):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/crs-priority-daemon.sh" --status
If it errors (login failed / unreachable), surface the message and let the
user re-enter creds — do NOT install a broken daemon.
- Install the timer (background-friendly):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install-crs-priority-agent.sh"
macOS → launchd every 120s (RunAtLoad fires the first tick). Linux → the
installer prints the equivalent systemd-timer snippet.
Tuning (optional, crs block): off5h/off7d (deprioritize thresholds),
on5h/on7d (re-enable thresholds, hysteresis), floor (min usable accounts),
freshMinutes (max age of utilization data trusted for proactive deprioritize).
Weekly-cap reconciliation (crs.weeklyReconcile, default on) is built into the
priority daemon itself — no separate install step. It clears a stale
weeklyRateLimitEndAt hold once live 7d utilization drops back under on7d,
and is a no-op on any deployment that never sets that field. Set
crs.weeklyReconcile=false (or $CRS_WEEKLY_RECONCILE=0) to disable it.
Step 4.6 — CRS reconciler add-ons (optional)
Only offer this if Step 4.5 configured a CRS pool (crs.enabled=true) — these
reconcilers assume one exists. Two independent, opt-in daemons close gaps the
priority daemon (Step 4.5) doesn't cover:
- 429-cooldown: holds an account out of rotation only on a real
rateLimitStatus.isRateLimited=true from CRS (never a utilization
heuristic). Fast cadence (60s) since it reacts to a live rate limit.
- 401-refresher: proactively refreshes each account's CRS-pool OAuth
token before it expires, so accounts don't silently start 401ing between
priority-daemon ticks. Slower cadence (300s) — refreshes ahead of a 30min
expiry window.
AskUserQuestion:
Enable the optional CRS reconcilers?
[Both] — 429-cooldown + 401-refresher (recommended if you run a busy pool)
[429-cooldown only] — fast rate-limit hold, skip proactive token refresh
[401-refresher only] — proactive token refresh, skip rate-limit hold
[Skip] — neither (you can re-run /ops:rotate-setup --crs later)
On anything but [Skip]:
-
Write the config flags.
CFG="$USER_CFG"
jq --argjson cooldown "$COOLDOWN_ENABLED" --argjson tokenRefresh "$TOKEN_REFRESH_ENABLED" \
'.crs = ((.crs // {}) + {cooldownEnabled:$cooldown, tokenRefreshEnabled:$tokenRefresh})' \
"$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG"
($COOLDOWN_ENABLED/$TOKEN_REFRESH_ENABLED are true/false per the
selection above.) Optional: also ask for crs.stateDir/crs.logDir if the
user wants non-default paths — see config.example.json for the full
annotated schema. Both reconcilers default to
<plugin-data-dir>/account-rotation if left unset.
-
Smoke-test before installing (each enabled reconciler, no writes):
[[ "$COOLDOWN_ENABLED" == "true" ]] && node "${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/crs-429-cooldown.mjs" --status
[[ "$TOKEN_REFRESH_ENABLED" == "true" ]] && node "${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/crs-401-refresher.mjs" --status
If either errors (login failed / unreachable), surface the message and let
the user re-check Step 4.5's CRS creds — do NOT install a broken daemon.
-
Install (idempotent — installs whichever flags are true, uninstalls
whichever were turned back off):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install-crs-reconcilers-agent.sh"
macOS → launchd, 60s / 300s cadence (RunAtLoad fires the first tick).
Linux → the installer prints the equivalent systemd-timer snippets.
Step 4.7 — Magic-link autoloop (optional, unattended re-auth)
Only offer this if Step 4.6's 401-refresher was enabled — this reconciler
reads its needs-reauth flags. Unlike the other reconcilers, this one
dispatches a REAL browser-based re-auth attempt (via rotate.mjs --setup,
the same Gmail-via-gog flow this wizard itself uses in Step 4) — make sure
the user understands that before enabling it.
AskUserQuestion:
Enable unattended re-auth for accounts with a confirmed dead token?
[Yes — enable] — magic-link-autoloop dispatches rotate.mjs --setup automatically
[Not now] — a human handles re-auth manually when 401-refresher flags an account
[What is this?] — one-paragraph explainer, then re-ask
On [Yes]:
-
Write the config flag.
CFG="$USER_CFG"
jq '.crs = ((.crs // {}) + {enableMagicLinkRecovery:true})' \
"$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG"
Optional: ask for a non-default crs.magicLinkRetryCooldownMs (default 6h) —
see config.example.json.
-
Smoke-test (no writes, no dispatch):
node "${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation/magic-link-autoloop.mjs" --status
-
Install (folded into the same idempotent installer as Step 4.6):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install-crs-reconcilers-agent.sh"
macOS → launchd, 600s cadence, RunAtLoad=false (does NOT fire immediately
on install, unlike the other reconcilers — first tick waits for the normal
schedule so a fresh install never triggers a surprise browser launch).
Linux → the installer prints the equivalent systemd-timer snippet.
Note on provider scope: this reconciler's own logic (which account, when, how
often) has no email-provider dependency — it only decides what to retry and
delegates the actual OAuth+email-poll work to rotate.mjs --setup, which is
Gmail-via-gog today. A fully provider-agnostic email backend (e.g. IMAP)
would be a rotate.mjs-internals change, out of scope here.
Step 5 — Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPS ► ROTATE-SETUP COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Accounts initialized:
✓ <id> (<plan>)
✓ <id> (<plan>)
✗ <id> (failed — re-run /ops:rotate-setup --account <email>)
Config: ~/.claude/plugins/data/ops-ops-marketplace/account-rotation-config.json
Keychain: Claude-Rotation-<key> (account: $USER) · key = label or email
CRS priority daemon: ✓ installed (every 120s) | ✗ not configured
CRS 429-cooldown: ✓ installed (every 60s) | ✗ not enabled
CRS 401-refresher: ✓ installed (every 300s) | ✗ not enabled
Magic-link autoloop: ✓ installed (every 600s) | ✗ not enabled
To enable automatic rotation, open /plugins → claude-ops → settings and
toggle "Multi-account Claude rotator" (account_rotation_enabled).
──────────────────────────────────────────────────────
(Show the CRS priority-daemon line only if Step 4.5 ran; show the two Step 4.6
reconciler lines only if Step 4.6 ran; show the magic-link line only if Step
4.7 ran. All four CRS daemons are independent of the account_rotation_enabled
toggle — each is gated by its own config flag (crs.enabled,
crs.cooldownEnabled, crs.tokenRefreshEnabled, crs.enableMagicLinkRecovery)
plus whether its launchd/systemd timer is installed.)
Exit. Do NOT auto-enable account_rotation_enabled — that decision belongs
to the user, made explicitly through the plugin settings UI.
Argument handling
--all (default): full wizard as described above.--account <email>: skip Step 2; only init the matching account.--add: skip token check; jump straight to Step 2 add loop, then init.--crs: jump straight to Step 4.5 (configure + install the CRS priority daemon), then Step 4.6 (offer the reconciler add-ons), skipping the keychain-account OAuth steps.--reconcilers: jump straight to Step 4.6 (offer/reconfigure the 429-cooldown and 401-refresher reconcilers, then Step 4.7's magic-link autoloop offer) — requires Step 4.5 already configured (crs.enabled=true); if not, print the same message as --crs needing configuration first and exit.
Failure modes
| Symptom | Cause | Action |
|---|
oauth_failed (rotate.mjs exit ≠ 0) | login did not complete — Turnstile, Google SSO/2FA, or timeout | Open $LOG + rotation.log; if the cascade is waiting on a visible Chrome, let the user finish login there, then re-run |
playwright install failed | npm offline / sandbox | Run npx playwright install chromium in ${CLAUDE_PLUGIN_ROOT}/scripts/account-rotation, then retry |
token still ✗ after success | account label/email mismatch vs config | Confirm the config key (label // email) matches the Claude-Rotation-<key> service name |
| no CDP browser available | no Chrome on :9222 and none installed | rotate.mjs falls back to bundled Chromium, which Turnstile may block — install/launch Chrome so the cascade can attach |
| Google SSO / 2FA prompt | Workspace-domain account needs interactive Google login | Let the user complete login in the cascade's visible Chrome; do NOT auto-solve 2FA |
CRS --status "login failed" | wrong admin user/password or CRS not reachable | Re-enter creds (Step 4.5); admin creds are in the CRS container data/init.json; verify curl $CRS_URL/health |
| CRS daemon installed but no effect | crs.enabled=false, or all accounts already correctly flagged | Check crs.enabled in config; tail logs/crs-priority.log; a steady-state tick logs 0 change(s) |
CRS reconciler --status errors | wrong admin creds or CRS unreachable (same creds as priority daemon) | Re-check Step 4.5's CRS creds; curl $CRS_URL/health |
| CRS reconciler installed but no effect | crs.cooldownEnabled/crs.tokenRefreshEnabled false, or no account currently needs it | Check the relevant flag in config; tail logs/crs-429-cooldown.log or crs-401-refresher.log — both are safe no-ops when nothing needs action |
| magic-link-autoloop never dispatches | crs.enableMagicLinkRecovery false, 401-refresher not enabled/hasn't flagged anyone, or account is on magicLinkRetryCooldownMs cooldown | node magic-link-autoloop.mjs --status; confirm 401-refresher is enabled and has a needsReauth entry |
| magic-link-autoloop dispatches too often | magicLinkRetryCooldownMs too low for a persistently-broken account | Raise the cooldown in config; each attempt is a real browser-automation run, not free |
