There is a small population of Claude Code users who already solved their rate-limit problem the old way. They wrote a shell script that watches for 429 errors, swaps ~/.claude/.credentials.json between two or three OAuth profiles they collected manually, and restarts Claude Code. Or they installed a browser extension that auto-clicks the "Switch Account" flow in claude.ai. Or they have a tmux pane open with pc-rotate.sh (some flavor of it) running in a while true; do … sleep 60; done loop.
This works, in the same way that any home-built infrastructure works — until it doesn't. The patterns most of these scripts use have specific failure modes that are not obvious until you have been running them for weeks. This post lays out what those failure modes are and what Power Claude does differently.
If you have already invested time in your rotation script, the case for migration is not "ours is more polished." The case is that the script's architecture has the wrong shape, and the work-arounds you have layered on top are not solving the underlying problems.
What Most Home-Built Rotation Scripts Look Like
The typical script has the same three pieces:
- A trigger. Some way to notice that the current account hit a rate limit. The most common implementation is a
greploop over the Claude Code log or session JSONL files watching for429orrate_limitstrings. A more sophisticated version installs aStophook in~/.claude/settings.jsonthat fires when Claude finishes a turn and inspects the last message.
- A swap. Some way to switch credentials. The common pattern is keeping multiple
credentials-<name>.jsonfiles in a side directory andcp-ing the next one over~/.claude/.credentials.json. A few users have written browser-automation flows that driveclaude loginprogrammatically to refresh tokens.
- A restart. Some way to make Claude Code pick up the new credentials. The blunt pattern: kill the Claude Code process and re-launch it. The slightly cleaner pattern: rely on Claude Code's own file watcher to notice the credential change and continue with the new account on the next turn.
The architecture works in the demo case — one account hits 429, you swap the credentials file, Claude Code retries on the next account, and the session continues. The problems show up at the edges.
What These Scripts Get Wrong
Waiting for the 429 to fire at all. The fundamental architectural mistake in almost every home-built rotation script is that it is reactive. It watches for the rate-limit error and then swaps. By the time the 429 has fired, you have already wasted the request, Claude Code has already paused, and the session has already taken a context hit. The swap recovers the next request, but the failed turn is dead — you cannot un-429 it.
Anthropic actually tells you when you are about to hit a rate limit. Every successful API response carries anthropic-ratelimit-unified-5h-utilization and anthropic-ratelimit-unified-7d-utilization headers — your current quota usage as a fraction. A script that reads these headers can rotate at 95% utilization, before any 429 fires. The 429-watching pattern ignores this signal entirely.
Per-minute throttling looks like exhaustion. Anthropic enforces four rate-limit windows per account: 5-hour, 7-day, tokens-per-minute (TPM), and requests-per-minute (RPM). The first two are the ones most users think about. The second two are the ones that bite during heavy agent fan-out with sub-agents: you have plenty of 5-hour budget left, but a burst of parallel tool calls saturates the per-minute limit and Anthropic returns 429 with a Retry-After: 30 or similar. Most home-built scripts treat any 429 as account exhaustion, rotate to the next account, and watch that one immediately get throttled too. The right behavior is to recognize per-minute throttling, route the next request to a different account temporarily, and let the throttled account back in when the minute window passes. Doing this correctly requires per-account cooldown tracking with Retry-After headers as the signal — not a flat blacklist.
Anti-ping-pong is a heuristic, not structural. The naive rotation pattern (round-robin through accounts on any 429) eventually rotates back to an account that is still cooling. A small fraction of scripts handle this with "wait N seconds before retrying any account that just 429'd." This works some of the time, fails when N is wrong, and breaks entirely if your accounts have asymmetric quotas. The correct pattern is per-429 cooldown: each 429 marks its own account out for exactly its Retry-After value. The selector cannot pick a cooling account regardless of order, so ping-pong is structurally impossible.
No session continuity across the swap. When the swap is a credentials-file cp and a Claude Code restart, the session ends. Whatever was in the conversation thread is gone. The --resume flag can recover the transcript, but if the session had been auto-compacted multiple times, you are resuming from a summary of a summary — a degraded thread. The cleaner architecture is to rotate at the proxy layer, between Claude Code and Anthropic, so the Claude Code session never sees the swap. The conversation thread, tool state, and context all persist across the rotation.
Trivial stops still kill the session. Even if the script handles every rate-limit case perfectly, the session still stops when Claude itself decides to pause. "Should I continue?" "Let me know when to proceed." "Good stopping point." A rotation script does not see these — they are not 429s. They are Stop events with no error. The script keeps running, but the session is sitting there waiting for input that is not coming. Most home-built rotation flows have no answer for this; they were built around the 429 problem.
Pool exhaustion is unhandled. If all your accounts cool simultaneously, the script has nothing to swap to. The typical fallback is "just keep retrying until something works." This burns through your Retry-After budgets and ends with the same dead session you started with. The correct behavior is to compute the soonest reset time across the pool (from Anthropic's anthropic-ratelimit-unified-5h-reset and -7d-reset headers, which the script almost certainly is not reading) and schedule a wake event for that moment instead of looping.
Credential file corruption. This is the one nobody talks about. If your rotation runs while Claude Code is in the middle of refreshing its OAuth token, the cp overwrites a file that Claude Code is also writing to. The result is a half-written .credentials.json and a broken session for both accounts. The right pattern is atomic rename (mv -f new-creds.json.tmp ~/.claude/.credentials.json) with file locking, but most scripts use plain cp.
What Power Claude Does Differently
Power Claude was built around the architecture that solves the problems above. The mechanism changes; the goal — keep the session running across rate-limit events — is the same one your script was already pursuing.
A proxy, not a hook. Power Claude runs a zero-dependency local HTTP proxy on port 3456. Claude Code is configured (automatically, via CLAUDE_API_URL injection into your terminal) to send its API calls to the proxy instead of directly to api.anthropic.com. The proxy forwards the request, reads the response headers (including the rate-limit utilization), and decides whether to switch the active account for the next call. The rotation happens between requests, before any 429 fires.
Pre-emptive switching by utilization, not by error. When the active account's 5-hour or 7-day utilization crosses a threshold (default 98%), the proxy switches subsequent requests to the next healthy account. Claude Code never sees a 429. The configuration is exposed through powerClaude.proxy.switchThreshold if you want to tune it down to 95% or 90%.
Power Mode — proactive parallel routing. Standard rotation drains one account before moving to the next. Power Mode routes every request to the least-loaded account in your pool simultaneously, so all your accounts fill in parallel. With three accounts in Power Mode, the effective ceiling on every rate-limit window — 5-hour, 7-day, TPM, RPM — is approximately 3× a single account. Per-minute throttling that used to choke heavy sub-agent fan-out on a single account simply does not happen because the per-minute pressure spreads across the pool.
Smart 429 routing — per-account cooldown. When a 429 does fire (which is rare in the proactive mode, but always possible at the per-minute level), the proxy does not sleep Retry-After seconds and retry the same account. It marks that account out for exactly Retry-After and tries a healthy alternate first. The dashboard tracks "throttle waits avoided" cumulatively so you can see this doing its job. Anti-ping-pong is structural: each 429 marks its account out for its Retry-After, so the selector cannot pick a cooling account regardless of order.
Atomic credential rotation. When the proxy switches accounts, it overwrites ~/.claude/.credentials.json with an atomic rename (fs.renameSync after writing the new content to a tmp file in the same directory). Claude Code's file watcher sees a clean swap, never a half-written file.
Auto-Resume on full-pool exhaustion. If every account in the pool does cool together, Power Claude reads the anthropic-ratelimit-unified-5h-reset and anthropic-ratelimit-unified-7d-reset headers from the most-recent responses, computes the soonest reset moment, and schedules a systemd-run timer for that moment. When the timer fires, the session resumes silently. See Auto-Resume.
Auto-Nudge on trivial stops. The Stop hook scans the model's last message against a catalog of regex patterns that match trivial-stop signatures and re-injects the turn with a targeted correction prompt. The default catalog covers "ask permission to continue," "offer multi-choice," "tell user to do work," and "pseudo-checkpoint." See Auto-Nudge for the full catalog and the shadow-mode option.
Watchdog for session death. The watchdog polls every 30 seconds and detects heartbeat-stale, tool-truncation, ended-with-pending-tasks, and rate-limit states — catching the cases where Claude Code itself died (IDE crash, OOM, network drop, process kill) and the rotation script would have had nothing to swap.
The Migration Path
If you are coming from a custom rotation flow, the migration is mostly subtractive — you turn things off, not on.
Step 1: Install Power Claude. Either via VS Code marketplace (code --install-extension neural-llm.power-claude). The two share the same ~/.power-claude/ runtime directory, so you can have both installed.
Step 2: Import your existing accounts. If your script keeps credentials-<name>.json files in a side directory, pc add walks you through claude login for a fresh account profile, or you can use pc save-profile <name> after authenticating directly with claude login. Existing OAuth tokens migrate cleanly.
Step 3: Disable your old rotation script. This is the step most people delay. The old script and Power Claude will both try to write ~/.claude/.credentials.json, and the conflict is exactly the kind of half-written-file race condition that breaks both. Stop the cron job, kill the tmux pane, uninstall the browser extension. If your old script installed a Stop hook in ~/.claude/settings.json, remove that entry — Power Claude's hooks have different markers and do not conflict, but a stale 429-watcher hook will fire on every Stop event for no reason.
Step 4: Confirm the proxy is active. Run pc status (or open the Power Claude dashboard in VS Code). The status bar should show the active account, current utilization, and pool size. If Claude Code is not routing through the proxy, the most common cause is that CLAUDE_API_URL is not set in your shell — open a fresh terminal after install and check echo $CLAUDE_API_URL. The extension injects this automatically into new terminals; the CLI installer appends it to your shell rc.
Step 5: Enable Power Mode. From the Power Claude Settings panel, flip the Power Mode toggle. Or run power-claude balanced on from the CLI. The status bar will show âš¡ Balanced [N] ~Nx when active. Confirm Auto-Nudge is also enabled (default on).
Step 6: Decommission your old setup. Delete the old shell scripts, remove the ~/.claude/credentials-<name>.json files (Power Claude profiles live at ~/.power-claude/profiles/), and clean up any cron entries or systemd timers from the old approach. If you were using a browser extension for any of this, uninstall it.
Step 7: Run a long session. The first real test is a multi-hour Claude Code session that would have hit a rate limit on your old setup. Check the Power Claude dashboard afterwards — the Sessions tab shows every rotation event, every nudge fire, and every utilization curve. If you see rotations happening pre-emptively (before any 429 in the logs), the migration succeeded.
What You Lose
The honest answer is: not much.
If your old script had specific behavior you cared about — a particular order of account selection, a particular logging format, a specific integration with a CI system — Power Claude has a CLI surface (pc list, pc switch, pc rotate, pc logs, pc serve) that exposes most of what you would want to script against. The pc logs --grep <pattern> command is roughly equivalent to whatever JSONL-grepping your old loop was doing. The pc rotate <account> command does a manual rotation if you want to override automatic selection for a single request.
What you lose is the maintenance burden — keeping your script's heuristics in sync with Anthropic's evolving rate-limit headers, debugging the per-minute throttle case on a 2am page, recovering from the file-race that corrupted credentials last Tuesday. The mechanisms Power Claude implements (header-driven pre-emptive rotation, per-account cooldown, atomic credential swap) are not novel insights; they are the architecture your script would converge on if you kept iterating on it. Migration just skips the iteration.
Quick Reference
Q: I already have a rotation script that works. Why migrate? A: "Works" usually means "handles the 429 case." Most home-built scripts have unhandled failure modes — per-minute throttling, anti-ping-pong, session death, trivial stops, atomic credential swap, full-pool exhaustion — that show up after weeks of use. Power Claude addresses all of them with one architecture.
Q: Can I run my old script alongside Power Claude during a transition? A: No. Both will try to write ~/.claude/.credentials.json, and the conflict will produce half-written files that break both. Disable the old script before enabling Power Claude.
Q: Will Power Claude work with my existing Claude Code session? A: Yes. The proxy is transparent to Claude Code; the session continues normally and starts rotating accounts automatically once the proxy is active and you have at least two accounts in the pool.
Q: Do I need to re-authenticate every account? A: Only the ones Power Claude does not already see. If your old script kept multiple credentials-<name>.json files in a side directory, you can either pc save-profile <name> for each one or run pc relogin <name> to walk through claude login cleanly.
Q: What about my custom logging? A: Power Claude writes structured events to ~/.power-claude/logs/events.jsonl. Use pc logs --grep <pattern> for ad-hoc queries or tail the file directly. The schema is documented and stable; any custom dashboard you had querying the old logs can be repointed.
Q: What if I was using a browser extension instead of a shell script? A: Same migration path. Uninstall the browser extension, install Power Claude, add your accounts. The browser-extension approach typically drove the claude.ai UI to swap accounts — Power Claude does this at the OAuth/credential layer, which is faster and more reliable than UI automation.
Q: How is pc rotate different from my script's rotation command? A: pc rotate triggers a manual swap to the next healthy account. pc rotate <name> swaps to a specific account. Both do an atomic credential write, update the proxy's active-account state, and emit a structured event to events.jsonl. The difference from a custom script is that you almost never need to call rotate manually — pre-emptive utilization-based rotation handles it automatically.
Q: Does Power Claude work if I am not in VS Code? A: Yes. The proxy is process-independent. Set CLAUDE_API_URL=http://127.0.0.1:3456 in your shell (the CLI installer does this automatically for new shells) and any claude invocation routes through the proxy. The CLI surface (pc list, pc status, pc watch) gives you the full dashboard from a terminal.