pi-multi-account

Automatic multi-account failover & rotation for Pi Agent, across Anthropic (Claude), OpenAI / ChatGPT Codex, Kimi For Coding, Cursor, Qwen / Alibaba, and Ollama.

When the account you are using hits a quota or rate limit, pi-multi-account transparently switches to the next authenticated account/model and (optionally) resumes the interrupted task — so a long agent run does not die just because one account ran out of budget.

What it does

• Auto-discovers every authenticated account from ~/.pi/agent/auth.json (Anthropic Claude Pro/Max, OpenAI/ChatGPT Codex, Kimi For Coding, Cursor, Qwen/Alibaba, and Ollama) and builds the failover rotation dynamically — no manual config editing.
• Grows the rotation on login. Run /login, choose Use a subscription, then select a numbered slot such as anthropic-account-3 or openai-codex-account-5. The next discovery sweep adds it to the rotation automatically.
• Pins a preferred model per account group. /multi-account pin provider/model persists a routing preference across sibling accounts; unpin removes it and pins explains its current applicability. It never changes the current model, Pi's registry, cooldowns, startup defaults, or automatic quality-band rules.
• Auto-discovers new Codex models per account. At session start (and on reload / rediscover) it reads OpenAI's authenticated model catalog, mirrors each account's actually available models onto its Pi alias, and follows OpenAI's server priority. A new flagship can therefore win immediately without an extension release or a hard-coded model id.
• Handles auth failures without poisoning healthy OAuth accounts. A generic final 401 briefly cools down a refreshable account and moves the current task forward. Explicit provider verdicts such as authentication token has been invalidated force an early refresh; if the refresh token is dead too, the slot is removed and Pi prints the interactive /login recovery steps.
• Fails over on quota / rate-limit (429 / 402 / 403 and friends): the exhausted account goes on cooldown (parsed from the provider's own reset metadata when available) and Pi first tries another account with the same model. If it must leave the family, it preserves the model's quality band — Sol/Opus/other frontier flagships stay frontier; Terra/Sonnet stay balanced; Luna/Haiku stay fast — and keeps the session's thinking level. A fresh provider verdict of blocked or 100% is skipped automatically instead of wasting the turn; manual next remains an explicit one-attempt override for stale telemetry.
• Optional immediate auto-continue: resumes the interrupted turn after a switch from the last safe point. A continuation that exhausts its newly selected account keeps advancing instead of stopping after the first hop. Temporary 5xx/overload errors and Cursor stalls retry the exact selected provider/account/model, without marking its quota exhausted. After four failed attempts (or an earlier recovery breaker), automatic retries stop with an explicit explanation; temporary errors never authorize a switch. Same-route retries are labelled as retries, not fake switches. A rejected Pi follow-up remains armed instead of losing the task. A failed or cancelled automatic compaction still continues the task instead of leaving the session parked in Working.
• Never hides a fresh user message in a private cooldown queue. If no account is ready, the message remains in Pi's visible transcript and Pi owns its normal delivery/retry path.
• Session-bound overnight resume, independently configurable: if every compatible account is cooling down, the live Pi session keeps the task armed by default even when ordinary post-switch autoContinue is off. It polls every account (quota monitoring remains active when the footer is hidden), reacts to fresh provider recovery evidence, and continues on the first genuinely usable route. A new user message, /multi-account stop, session exit, or Esc during a running turn cancels the chain.
• Deduplicates provably identical accounts so duplicate Codex workspace memberships and identical credentials do not consume multiple rotation slots or get separate cooldowns. Different users in one Team/Business workspace remain distinct. New provable duplicate logins are rejected before the redundant slot is saved.
• Keeps YOUR reasoning level across automatic switches. Whatever the session runs at — your Pi default, /thinking, or a per-agent --thinking low — is preserved and restored after every account/model switch, so it never drifts downward when a weaker fallback model clamps it. Manual /model selections adopt Pi's per-model thinking default in auto mode; an explicit CLI --thinking or forced reasoningLevel remains authoritative. The extension does not otherwise override your level, and extreme levels such as xhigh / Max / Ultra are never forced.
• Shows live limits for the active account in Pi's footer: remaining 5-hour/session and weekly allowance plus reset countdowns for Codex, Anthropic, and Ollama Cloud accounts, SuperGrok / xAI subscription credit usage for /login xai OAuth (not Cursor Grok, not XAI_API_KEY), and GLM Coding Plan CN 5-hour/weekly credit quota for zai-coding-cn. GLM CN uses the raw Coding Plan API key only at https://open.bigmodel.cn/api/monitor/usage/quota/limit; global zai keys are not sent there. Missing or malformed quota is unknown, never assumed unused.

Install

pi install npm:pi-multi-account

Restart Pi or run /reload after installation.

Requires Node 22+ and Agent Pi / pi-ai **>=0.85.1, <0.88.0; >=0.99.0, <0.100.0; or >=1.0.0, <2.0.0**. CI covers Pi **0.85.1, 0.86.1, 0.87.1, 0.99.2 and 1.0.0**; Pi 0.99+ requires Node >=22.19.0. Both Pi SDK packages are peers supplied by the running host. OAuth, catalogs and transports use public host-bound imports; do not install a private runtime pi-ai copy alongside this extension. Standalone SDK callers must supply matching Pi SDK versions. Pi 0.99+ support retains numbered account aliases and existing rotation/continuation semantics; it does not introduce a virtual model. Pi-owned virtual selections and image/classifier models are not account chat failover targets.

This release does not arbitrate multiple extensions calling pi.setModel. Keep one automatic foreground selection owner: independent routing extensions can otherwise overwrite each other's choices. Account failover still owns ordinary selected chat accounts; virtual models remain host-owned.

Kimi OAuth spares remain available in /login, but are not written to models.json: without a Kimi child OAuth proxy those aliases would be resolvable but unauthenticated. Only real API-key Kimi slots are published for extension-free children. Existing user entries are not deleted; a previously generated unused Kimi alias can be removed from models.json and will not reappear.

Anthropic (Claude Pro/Max) works out of the box. OAuth login and request shaping for the base anthropic provider and every anthropic-account-* alias are built in — no separate pi-anthropic-auth install is required. If you already have pi-anthropic-auth, the two coexist safely (the shaping is idempotent). OpenAI Codex / ChatGPT and Qwen accounts work as well.

Recommended setting

Set Pi provider-level retries to zero so the SDK does not keep retrying an exhausted account before failover kicks in. Pi's separate agent-level retry loop may remain enabled: the extension cancels its pending wake if that retry succeeds. Repeated temporary failures get bounded recovery on the same route, then an explicit stop—not provider failover. In ~/.pi/agent/settings.json:

{ "retry": { "provider": { "maxRetries": 0 } } }

Usage

Add accounts by opening the login picker:

/login
Use a subscription
ChatGPT Plus/Pro (Codex openai-codex-account-2)
/multi-account rediscover

Pi 0.79.3 does not accept a provider argument after /login; select the account slot from the interactive provider picker instead.

Check what's in the rotation at any time:

/multi-account status

Force-refresh and display detailed limits for the active account:

/multi-account limits refresh

Example status output:

pi-multi-account: enabled · auto-discover ON
Current: anthropic/claude-opus-4-8
Current limits: Claude | 5h 0% left/2h14m | 7d 92% left/1d18h
Rotation (3): anthropic → openai-codex → openai-codex-account-2
Registered login slots: anthropic-account-2, openai-codex-account-2
Cooldowns: none
Invalidated (need re-login): none
Pending auto-resume: none

Commands

All three names are aliases for the same command: /multi-account, /provider-failover, /failover.

Model pins

/multi-account pin openai-codex-account-2/gpt-5.4
/multi-account pins
/multi-account unpin openai-codex

Pins live in provider-failover.json under pinnedModels, keyed by account group (for example openai-codex, anthropic or a custom provider's base ID). Other sessions adopt edits on reload or restart. Extension configuration commands share a locked read-latest transaction; unrelated settings and other groups' pins survive concurrent extension writes. A failed/cancelled write does not change the runtime preference.

A pin leads the group's underlying preference/catalog order, but a healthy exact-model sibling still wins. A pin is not evidence that an older model is a newer flagship. Missing models remain saved but inactive until the catalog supplies them; cooling or unauthenticated accounts stay ineligible. A cheaper pin cannot demote frontier work. Select the cheaper model explicitly with /model, pick or switch provider/model to enter that quality band. A provider-only switch and automatic compaction cannot use a pin as cheaper-tier consent. Pi-owned virtual/image/classifier models cannot be pinned as account chat fallbacks.

How rotation membership works

• Joins the rotation when an account has a present, non-expired credential in auth.json (after /login).
• Leaves the rotation when the credential is logged out / removed, its access token is expired with no refresh token, an API key is rejected, or a refreshable OAuth credential produces three distinct final auth failures without a success in between.
• Quota / rate-limit does not invalidate an account — it puts it on a temporary cooldown and the account returns once the cooldown expires.
• Duplicate identities share one rotation position and one cooldown, and status/startup identifies the redundant slot. Codex/ChatGPT is matched by the JWT's stable chatgpt_account_user_id workspace-membership claim; tokens without it use the documented chatgpt_user_id plus workspace id, with stored accountId as the final legacy fallback. Identical API keys or literal identical tokens are also matched. Separate Anthropic OAuth logins cannot be proven identical because Anthropic's stored credential exposes no stable account identifier.

Rotation refresh is triggered by changes to auth.json (detected on session/turn start) or on demand with /multi-account rediscover.

After re-authenticating an invalidated slot, restart any older Pi processes that were already running. Pi keeps a still-unexpired access token in each process's memory, so an old process can continue using the invalidated token even after a new /login updates auth.json.

Configuration

A default config is created at ~/.pi/agent/provider-failover.json on first run. Useful keys:

State (cooldowns, invalidations, recent switches, credential-free Codex model catalogs, and a diagnostic pending marker) is persisted to ~/.pi/agent/provider-failover-state.json. The actual pending task is session-local: one Pi window never consumes or resumes another window's work. Pending work is discarded when its owning session closes.

Session model ownership

Requires the supported Agent Pi versions listed above. Pi's session branch and explicit SDK/CLI launch model are authoritative. Shared account telemetry and legacy lastUserModel / lastUserThinkingLevel state cannot replace another pane's live selection, and shutdown does not publish that selection as a global default. Cold-catalog repair uses this session's model history once at startup. Configure Pi's saved default explicitly for new sessions.

Host-owned background completions

When the host exposes registerCompletionRouter, Multi Account registers one credentialless completion router with it. This is capability-detected, not inferred from the Pi version: stock Pi 0.85.1 does not expose this optional API, so the integration remains inactive there. Extensions can request isolated background completions through Pi without importing or calling Multi Account. The router sees operation IDs, model identities, attempt outcomes, and provider response facts only; prompts and credentials remain inside the host.

Background attempts share the same cooldown and invalidation state as foreground routing. Quota, authentication, model, and transport failures can select a healthy fallback; parser and consumer failures do not affect route health. The route lease is operation-local: it never calls pi.setModel, queues a continuation, or changes the user's selected foreground model.

pi-subagents and delegation-broker compatibility

pi-subagents marks native child processes with PI_SUBAGENT_CHILD=1 and owns their explicit model plus fallbackModels chain. Under terminal Pi, a distinct concurrent in-process child also stays passive while a root activation is live. A replacement with the same nonempty session ID reacquires that root's failover ownership without closing its child proxy. The root lease is released at final session shutdown, so /reload and /new do not permanently lose routing ownership. In passive children this extension stays loaded only for provider/account registration, OAuth request shaping, and catalog support. It deliberately does not restore the interactive process's remembered model, persist the child's model as a user preference, switch models, queue work, or auto-continue after errors. The original provider error is returned unchanged so the parent runner can advance its verified fallback chain without a second router competing for model identity.

Multi-session hosts (pi-web and other in-process SDK hosts)

Some hosts run many independent sessions in a single long-lived process — pi-web's session daemon, or in-process SDK hosts such as Enso (one session per chat thread). Terminal Pi's in-process root-activation lease would incorrectly demote every session but the first to passive in those hosts.

• Under pi-web (PI_WEB_SESSION=1, set by the daemon itself) every session activates as an independent root automatically.
• Any other multi-session host opts in by exporting PI_MULTI_ACCOUNT_INDEPENDENT_ROOTS=1 in the host process. Set this only when each session truly owns its model; sessions that share one model identity must keep the default single-root behavior.
• Genuine pi-subagents children are unaffected either way: they run in a runner process marked PI_SUBAGENT_CHILD=1, which always takes precedence and stays passive.

Hosts should not set PI_WEB_SESSION themselves — other extensions read it to detect pi-web specifically.

In one process, independent roots share one canonical loopback proxy and its child-facing auth/models publication while any root has the child proxy enabled. Closing one root cannot expose its sibling's real OAuth or remove the route its bare children use; the final live root closes the listener and restores the original auth. A rehydrated session with the same ID replaces the old instance's failover ownership rather than counting as a second root. Another process holding the canonical port remains the publisher; a foreign listener is never allowed to overwrite its shared files.

Roots with childProxy: false still participate in the shared lifetime if another root publishes placeholders. Any public numbered alias they registered earlier is moved to loopback before the placeholder appears; they keep the canonical listener alive if the publisher exits first, and only the final root restores auth. With no other publishing root, disabling childProxy retains the usual direct route. Hosts should still keep one consistent setting across concurrent roots.

pi-delegation-broker is an optional companion for splitting work among isolated child agents, with task budgets, reports and verification. Each extension works independently and depends on Agent Pi, not on the other extension. Together, Multi Account manages your interactive account rotation while the broker delegates through Pi's registered providers and models. Neither installs or initializes the other.

Staying unstuck (resilience)

A failover is only useful if the agent actually keeps working afterward. These guarantees keep a switch from silently freezing the session:

• Compaction survives account limits — and never leaves the spinner running. When your context fills up and the active account is rate-limited, the summary is generated on a healthy account. If that attempt times out it is aborted (not leaked) and the next live account is tried. If none can finish, compaction is cancelled so "Compacting context…" stops; Pi's default is never given a spent account.
• Resumes only happen when there is something to resume. The extension continues a turn only when it actually ended in an error it can pick up from — it never tries to "continue" a finished reply (the cause of the cryptic Cannot continue from message role: assistant error).
• A forward-progress watchdog that acts. If a resumed turn goes completely silent (no streaming, no tool activity, no provider response) and no tool is running, the extension auto-cancels the wedged turn and retries the same provider/model within the recovery budget — you do not have to press Esc or re-type the prompt. A long, silent build/test command is never mistaken for a wedge.
• A circuit breaker as the floor. If automatic recovery keeps failing, the extension drops to advisory mode: confirmed quota limits can still select a fresh account, but temporary errors preserve the selected route and stop the auto-continue that was failing, so a bad state can never spiral into repeated hangs. It re-enables itself on the next success, a new prompt, or /multi-account reset.
• A black box for diagnosis. Every decision (switch, error and how it was classified, watchdog action, breaker trip, compaction routing) is appended to ~/.pi/agent/provider-failover-debug.log. If anything misbehaves, run /multi-account log — the exact sequence is there, so a bug can be reproduced and fixed instead of guessed at. The file is bounded in size and redacts token-shaped material; review private project details before sharing it.

Privacy & security

pi-multi-account reads credentials through Pi and its account store. Account removal, OAuth refresh and parent-owned proxy publication can update the credential files under Pi-compatible locks. Proxy publication keeps a private recovery copy before replacing a credential with a loopback placeholder, and restores the real credential before deleting that copy. Credentials are never stored in rotation state. Account/token values are reduced to a short irreversible SHA-256 fingerprint for re-login detection and deduplication. Credentials are sent only to their own provider endpoints: usage/account probes (chatgpt.com/backend-api/wham/usage, api.anthropic.com/api/oauth/usage, cli-chat-proxy.grok.com/v1/billing, open.bigmodel.cn/api/monitor/usage/quota/limit (CN Coding Plan keys only), Ollama Cloud's /api/me and /api/usage, or Ollama's loopback-only http://127.0.0.1:11434/api/me fallback), OpenAI's authenticated chatgpt.com/backend-api/codex/models catalog, and provider OAuth token endpoints when Pi's authentication implementation refreshes a login (for xAI, auth.x.ai/oauth2/token). Cached state contains percentages, reset times, plan/credit metadata, model metadata, provider-reported account email/alias, and the fingerprint, never the token. Config, state, and the debug log are written with 0600 permissions. The debug log records only provider/model ids, decisions, and truncated reasons — token-shaped material is redacted defensively — Review logs for private project details before sharing an issue. Disable it with "debugLog": false or /multi-account log off.

Compatibility validation

npm run release:check runs TypeScript, the full suite, and package/privacy checks. CI also runs the suite on the supported newer Pi versions. Host-binding tests load the real extension wrapper through Pi with a deliberately incompatible nested pi-ai, inspect native request bodies, and complete a streamed tool-call/result cycle without real credentials or provider traffic. A real pi --no-extensions subprocess also exercises a numbered Anthropic OAuth slot and native read tool roundtrip against a fake upstream. Its non-secret OAuth-shaped placeholder preserves native identity and tool mapping; real credentials remain in the parent. Legacy publications migrate only with an intact parent-side recovery copy. Production refresh persists into the private sidecar under the auth lock without briefly replacing the child's placeholder. API-key aliases remain direct native publications; stale loopback metadata accepts only the current key. Cancellation aborts the proxy's upstream request; ordinary API-key request semantics remain unchanged. These are deterministic regressions, not a claim of live Anthropic or Codex-image acceptance.

The optional companion Goal integration is selected explicitly; it never assumes a personal path:

PI_GOAL_TEST_ENTRY=/path/to/pi-goal/dist/index.ts node --test test/goal-quota-recovery.integration.test.ts
PI_GOAL_TEST_ENTRY=/path/to/pi-goal/dist/index.ts PI_GOAL_EXHAUST_ALL=1 node --test test/goal-quota-recovery.integration.test.ts
PI_GOAL_TEST_ENTRY=/path/to/pi-goal/dist/index.ts PI_GOAL_EXHAUST_ALL=1 PI_GOAL_RECOVER_ALL=1 node --test test/goal-quota-recovery.integration.test.ts

These exercise successful multi-hop continuation, quiet all-account waiting with explicit pause, and resumption after quota recovery. The test is explicitly skipped when no companion path is supplied.

License

MIT

Help make these tools more reliable

Use them on real work? Share a reproducible issue, a small regression test, a documentation improvement, or a focused PR. Include Pi/extension versions and expected versus actual behavior; remove credentials and private task data. Shared fixes cover more providers and workflows than one maintainer can test alone.