feat: Multi-Account OAuth Rotation with Settings UI

[mguttmann]

Problem Statement

Users with Claude Max subscriptions frequently hit rate limits, causing workflow interruptions. While OpenCode supports OAuth login, there was no way to:

1. Login with multiple accounts for the same provider
2. Manually switch between accounts
3. See rate limit usage across accounts
4. Automatically rotate to another account when one hits limits

Additionally, the desktop app lacked a centralized settings interface for managing providers and viewing usage statistics.

Solution Overview

This feature introduces comprehensive multi-account OAuth support with:

• Automatic rotation when accounts hit rate limits
• Manual switching via CLI and desktop UI
• Usage statistics display (currently Anthropic only)
• New Settings menu in desktop app

Feature Details

1. Multi-Account OAuth Rotation (Backend)

Core Changes:

• `Auth.OAuthPool.setActive(providerID, namespace, recordID)` - Set active account
• `Auth.OAuthPool.snapshot()` - Now returns `activeID` for credential selection
• `Auth.OAuthPool.getAccounts()` - Correctly identifies active account
• `fetchAnthropicUsage()` - Respects `provider.active[namespace]`

Credential Selection Flow: ```

1. snapshot() returns { records, orderedIDs, activeID }
2. candidates = [activeID, ...other accounts]
3. pickNextCandidate() selects first non-cooldown account
4. On 429 → account gets cooldown, next account used ```

2. API Endpoint

`POST /auth/active` ```json Request: { "providerID": "anthropic", "recordID": "..." } Response: { "success": true, "anthropicUsage": {...} } ```

Returns updated usage data for immediate UI refresh without full reload.

3. Desktop App - Settings Menu

New `DialogSettings` component with tabs:

Tab	Features
Providers	Connected providers list, add new providers with search
Provider Detail	Account list, usage bars, switch functionality
About	GitHub, docs, Discord links, keyboard shortcuts

Navigation Flow: ``` Settings → Providers → [Click Provider] → Detail View → [Add Provider] → Search View ```

4. Desktop App - Context Panel Integration

When viewing a session using Anthropic:

• Anthropic Rate Limits section appears after Context Breakdown
• Shows 5-hour, 7-day (all), 7-day (sonnet) usage bars
• Account switch buttons when multiple accounts configured
• Matches existing Context Breakdown visual style

5. CLI Enhancements

Command	Description
`opencode auth list`	Shows providers with account counts
`opencode auth usage`	Detailed usage per account with rate limits
`opencode auth switch`	Interactive account switching

All provider lists are now sorted alphabetically.

Technical Implementation

Files Changed

File	Changes
`packages/opencode/src/auth/index.ts`	`setActive()`, `snapshot()`, `getAccounts()`, `fetchAnthropicUsage()`
`packages/opencode/src/auth/rotating-fetch.ts`	Prefer `activeID` in candidate selection
`packages/opencode/src/server/server.ts`	`POST /auth/active` endpoint
`packages/opencode/src/cli/cmd/auth.ts`	`usage`, `switch` commands, sorting
`packages/app/src/components/dialog-settings.tsx`	New settings dialog
`packages/app/src/components/session/session-context-tab.tsx`	Anthropic usage section
`packages/app/src/pages/layout.tsx`	Settings button integration

Auto-Rotation Preserved

The automatic rotation on rate limit (429) is preserved: ```typescript if (response.status === 429) { await Auth.OAuthPool.recordOutcome({...cooldownUntil}) await Auth.OAuthPool.moveToBack(providerID, namespace, nextID) continue // → Try next account } ```

Current Limitations

• Usage statistics: Only available for Anthropic (OAuth API limitation)
• Multi-account support: Anthropic, OpenAI, GitHub Copilot (OAuth providers)
• Other providers: Contributions welcome for usage stats

Testing

CLI

```bash opencode auth list # Should show account counts opencode auth usage # Should show per-account stats opencode auth switch # Should allow switching ```

Desktop

1. Settings → Providers → Click connected provider
2. Verify usage bars display correctly
3. Switch accounts, verify bars update
4. Context panel → Verify Anthropic section appears

Screenshots

To be added

Related

• Builds on #8912 (OAuth rate limits dashboard)
• Addresses user feedback about rate limit management

[github-actions[bot]]

This issue might be a duplicate of existing issues. Please check:

• #8591: feat: OAuth Marathon - multi-account credential rotation
• #8864: Feature Request: Multi-Account Support with Automatic Failover
• #8911: feat: Add OAuth rate limits and usage dashboard

Feel free to ignore if none of these address your specific case.

[mguttmann]

[mguttmann]

Relationship to Related Issues

Thanks for the references! Here's how this issue relates:

Issue/PR	Relationship
#8911	✅ This issue builds upon #8911 (OAuth rate limits dashboard). We merged the basic usage display, and this issue extends it with multi-account switching and the full Settings UI.
#8591 / #8864	✅ This issue implements the feature requests from these issues. The multi-account credential rotation with automatic failover is now complete.
#8590	🔄 This issue provides a complete implementation of the OAuth Marathon concept with both CLI and desktop UI support.

Key additions beyond previous work:

• Full Settings menu with provider management
• Inline account switching in Context panel
• CLI commands (auth switch, enhanced auth usage)
• Proper reactive UI updates without full page refresh
• Alphabetically sorted provider lists

This can be considered the completion of the multi-account OAuth feature set.