pi-multi-auth

pi-multi-auth is a Pi extension for multi-provider credential management, OAuth login, and quota-aware account rotation.

• npm: https://www.npmjs.com/package/pi-multi-auth
• GitHub: https://github.com/MasuRii/pi-multi-auth

Capabilities

• Wraps discovered Pi providers with multi-account rotation, quota-aware cooldowns, failover, health scoring, and optional pool selection.
• Supports OAuth credential management for providers exposed by Pi and registers first-class Cline, Kilo, Kimi For Coding, and Qwen OAuth login and refresh handling.
• Applies per-credential request overrides for provider base URLs and headers, with Cloudflare Workers AI credentials using account-scoped OpenAI-compatible base URLs and token/account discovery during credential setup.
• Enriches status-only provider failures with bounded diagnostic probes so authentication, permission, billing, and rate-limit errors include actionable provider response details when available.
• Provides lightweight rotation for API-key providers that do not expose external usage state, including delegated parent-session lease reuse.
• Filters removed legacy Google Gemini CLI and Google Antigravity providers so stale provider definitions are not offered for credential setup or usage refreshes.
• Persists extension state and usage snapshots under Pi's runtime directory while keeping local config.json and debug output outside the published package.
• Coordinates fresh usage refreshes across selection, startup, modal, and manual refresh flows with bounded concurrency, candidate windows, cooldowns, and circuit breaking.

Provider capability matrix

The following table shows credential and usage support for each recognized provider. Providers marked API Key appear in the credential setup dialog; providers marked OAuth support browser-based or device-code login flows.

| Provider | API Key | OAuth | Usage / Quota | Notes | |---|---|---|---|---| | Anthropic | ✅ | — | ✅ | Usage via dedicated Anthropic endpoint | | Amazon Bedrock | ✅ | — | — | | | Azure OpenAI Responses | ✅ | — | — | | | BlazeAPI | ✅ | — | ✅ | Usage via /api/usage (daily requests + premium credits); rotation defaults to usage-based and routes credentials by plan tier (Premium → Pro → Free) with automatic fallback when the active tier's daily-request or premium-credit budget is exhausted | | Cerebras | ✅ | — | — | | | Cline | — | ✅ | — | OAuth only; browser callback | | Cloudflare Workers AI | ✅ | — | — | Requires account-scoped base URL | | Cloudflare AI Gateway | ✅ | — | — | | | DeepSeek | ✅ | — | — | | | Fireworks | ✅ | — | — | | | GitHub Copilot | ✅ | — | ✅ | Legacy discovery; usage via Copilot API | | Google Gemini | ✅ | — | — | | | Google Vertex AI | ✅ | — | — | | | Groq | ✅ | — | — | | | Hugging Face | ✅ | — | — | | | Kimi For Coding | ✅ | ✅ | ✅ | Device-code OAuth; usage via /usages endpoint | | Kilo | — | ✅ | — | OAuth only; device authorization | | MiniMax | ✅ | — | — | | | MiniMax (China) | ✅ | — | — | | | Mistral | ✅ | — | — | | | OpenAI | ✅ | — | ✅ | Usage via Codex entitlement | | OpenAI Codex | ✅ | — | ✅ | Legacy discovery; Codex usage + entitlement | | OpenCode Go | ✅ | — | — | | | OpenCode Zen | ✅ | — | — | | | OpenRouter | ✅ | — | — | | | Qwen | — | ✅ | — | OAuth only; device code with PKCE | | Vercel AI Gateway | ✅ | — | — | | | xAI | ✅ | — | — | | | Xiaomi MiMo | ✅ | — | — | | | ZAI | ✅ | — | — | |

Legacy providers openai-codex and github-copilot are retained for discovery and migration seed paths. Removed providers Google Gemini CLI and Google Antigravity are filtered from credential setup and usage refreshes.

Repository structure

This package follows a conventional src/ layout. The published entrypoint stays at the repository root as index.ts, runtime implementation lives under src/, and package exports map stable balancer subpaths to src/balancer/*.

pi-multi-auth/
├── index.ts
├── src/
│   ├── index.ts
│   ├── balancer/
│   ├── formatters/
│   ├── usage/
│   └── *.ts
├── tests/
├── .env.example
├── package.json
├── package-lock.json
├── tsconfig.json
├── tsconfig.test.json
├── README.md
├── CHANGELOG.md
└── LICENSE

Installation

npm package

pi install npm:pi-multi-auth

Local extension folder

Place this folder in one of Pi's extension discovery paths:

| Scope | Path | |-------|------| | Global default | ~/.pi/agent/extensions/pi-multi-auth (respects PI_CODING_AGENT_DIR) | | Project | .pi/extensions/pi-multi-auth |

Pi discovers the extension through the root index.ts entry listed in package.json, which forwards to src/index.ts.

The global path above is the default when PI_CODING_AGENT_DIR is unset; otherwise Pi resolves the global extension path under $PI_CODING_AGENT_DIR/extensions/pi-multi-auth.

Configuration

Runtime configuration lives in config.json at the extension root. The extension creates the file automatically with defaults on first load if it does not already exist.

| Key | Type | Default | Purpose | |-----|------|---------|---------| | debug | boolean | false | Enables JSONL debug logging under debug/pi-multi-auth-debug.jsonl | | hiddenProviders | string[] | [] | Hides selected providers from the multi-auth UI and runtime work | | rotationModes | Record<string, "round-robin" \| "usage-based" \| "balancer"> | {} | Overrides provider rotation modes outside multi-auth.json |

The published package intentionally excludes config.json and debug/; both are created locally as needed by the running extension. Usage snapshots are cached in Pi's runtime directory as multi-auth-usage-cache.json so operational and display-only usage state can survive extension restarts without publishing local state.

Credential request overrides

Credentials may include a request object with provider-specific request settings:

| Key | Type | Purpose | |-----|------|---------| | request.baseUrl | string | Overrides the model base URL for that credential after URL validation | | request.headers | Record<string, string> | Adds credential-scoped headers to the provider request |

Cloudflare Workers AI credentials must use https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1 as the OpenAI-compatible base URL. When adding a Cloudflare API-key credential, the extension can extract cfat_ tokens, account IDs, dashboard token URLs, or full Workers AI base URLs from pasted input. It discovers the base URL automatically when the token can list exactly one account; otherwise add request.baseUrl manually for the intended account.

Environment variables

The extension reads optional environment variables to override OAuth client settings, runtime paths, and display behavior. See .env.example for a copy-ready template.

OAuth client overrides

| Variable | Provider | Default | Purpose | |---|---|---|---| | KIMI_CODING_OAUTH_CLIENT_ID | Kimi For Coding | Built-in app ID | Override the OAuth application client ID | | QWEN_OAUTH_CLIENT_ID | Qwen | Built-in app ID | Override the OAuth application client ID |

Runtime path overrides

| Variable | Default | Purpose | |---|---|---| | PI_DELEGATED_AUTH_RUNTIME_DIR | Pi agent runtime directory | Override the directory for usage cache and multi-auth.json | | PI_MULTI_AUTH_RUNTIME_DIR | Pi agent runtime directory | Legacy alias for PI_DELEGATED_AUTH_RUNTIME_DIR; used only when the delegated variable is unset | | PI_CODING_AGENT_DIR | ~/.pi/agent | Override the Pi agent directory (affects models.json and runtime path resolution) |

Display overrides

| Variable | Default | Purpose | |---|---|---| | PI_MULTI_AUTH_ASCII_BORDERS | Auto-detected | Force ASCII border rendering in the extension TUI (1, true, yes, on) |

Validation

npm run build
npm run lint
npm run test
npm run check

Related Pi Extensions

• pi-permission-system — Permission enforcement for tool and command access
• pi-tool-display — Compact tool rendering and diff visualization
• pi-MUST-have-extension — RFC 2119 keyword normalization for prompts
• pi-rtk-optimizer — RTK command rewriting and output compaction

License

MIT