git:20260926.cd4bc56 to git:20260930.125d30f

---

name: provider-manager

category: orchestration

description: >

Autonomous AI provider and subscription management toolkit. Enables seamless

account discovery, credential switching, automated zero-touch browser-session

OAuth re-authentication, and proactive rate-limit failover rotation across

Claude Code CLI, Orca, and macOS Keychain. Use when: switching Claude accounts,

rotating providers on rate limits or 429 errors, inspecting subscription quotas

or tier limits, headless re-authenticating Claude Code without physical display

access, or synchronizing credentials between Orca and Claude Code. Triggers:

"switch claude account", "rotate provider", "rate limit reached", "change claude credentials",

"login headless", "orca credentials", "provider-manager", "subscription limit".

license: MIT

---

# Provider Manager

Autonomous provider and subscription credential manager for macOS environments running **Claude Code CLI** and **Orca**.

Transforms provider switching and re-authentication from a manual, GUI-dependent process into an **autonomous agent reflex**.

---

## Capabilities

1. **Multi-Account Discovery**: Enumerates all managed accounts, active status, organization UUIDs, subscription tiers (e.g. `max`, `pro`), and Keychain token health.

2. **Instant Account Switching**: Swaps active credentials in < 1 second across Claude Code (`~/.claude.json`, scoped/unscoped Keychain items) and Orca (`orca-data.json`, `Orca Claude Code Managed Credentials`).

3. **Headless Browser-Session OAuth**: Recovers active web sessions from Arc or Chrome profiles via macOS Keychain Safe Storage decryption, automatically authorizes Claude's PKCE OAuth flow, and injects the authorization code without physical screen or GUI access.

4. **Autonomous Rate-Limit Rotation**: When an agent hits an HTTP 429 (`rate_limit_error`) or 5-hour quota exhaustion, it rotates to the next available account and immediately resumes execution.

---

## Quick Reference Commands

All commands can be invoked directly from the CLI or within agent scripts:

```bash

# 1. List all accounts and token health

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py list

# Machine-readable JSON output

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py list --json

# 2. Check current active authentication & subscription status

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py status

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py switch dev@company.com

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py switch team@company.com

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py rotate --reason "rate_limit_429"

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py login-headless --email team@company.com

```

---

## Autonomous Agent Reflex: Rate Limit Failover

When an agent tool call or API request encounters a rate limit (HTTP 429 / quota exceeded):

1. **Rotate Credential**:

```bash

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py rotate --reason "rate_limit_429" --json

```

2. **If Token Missing/Expired**:

```bash

python3 ~/.agents/skills/provider-manager/scripts/provider_manager.py login-headless --email <candidate_email>

```

3. **Verify & Resume**:

```bash

claude auth status

```

Immediately retry the failed step.

---

## Architecture & Detailed References

* [references/architecture.md](references/architecture.md) — Comprehensive technical reference for Keychain schemas, Orca configuration, and Claude Web OAuth internals.

* [references/rotation-playbook.md](references/rotation-playbook.md) — Step-by-step procedures for autonomous agents when handling quota warnings and 429 errors.