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
5. Delete individual accounts when no longer needed

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)
• Delete individual accounts via CLI and desktop UI
• 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.removeRecord(providerID, recordID) - Delete individual 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 Endpoints

POST /auth/active

Request:  { "providerID": "anthropic", "recordID": "..." }
Response: { "success": true, "anthropicUsage": {...} }

DELETE /auth/account

Request:  { "providerID": "anthropic", "recordID": "..." }
Response: { "success": true, "remaining": 2 }

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, delete buttons
About	GitHub, docs, Discord links, keyboard shortcuts

Delete Account Flow:

1. Click X button on account
2. Confirmation dialog appears
3. Account removed from storage
4. Auto-navigate back when last account removed

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
opencode auth logout	Now supports selecting individual accounts

All provider lists are now sorted alphabetically.

Logout Account Selection:

$ opencode auth logout

┌  Remove credential
│
◆  Select provider
│  ● Anthropic (oauth)
│
◆  Remove which account?
│  ○ Remove all accounts (3 accounts)
│  ○ Account 1
│  ○ Account 2 
│  ● Account 3
│
◐  Account removed. 2 accounts remaining.
│
└  Done

Technical Implementation

Files Changed

File	Changes
packages/opencode/src/auth/index.ts	setActive(), removeRecord(), snapshot(), getAccounts(), fetchAnthropicUsage()
packages/opencode/src/auth/rotating-fetch.ts	Prefer activeID in candidate selection
packages/opencode/src/server/server.ts	POST /auth/active, DELETE /auth/account endpoints
packages/opencode/src/cli/cmd/auth.ts	usage, switch commands, logout account selection, sorting
packages/app/src/components/dialog-settings.tsx	New settings dialog with delete buttons
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:

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

opencode auth list      # Should show account counts
opencode auth usage     # Should show per-account stats
opencode auth switch    # Should allow switching
opencode auth logout    # Should allow selecting individual accounts

Desktop

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

Related

• Builds on feat(app): Add OAuth rate limits and usage dashboard #8912 (OAuth rate limits dashboard)
• Addresses user feedback about rate limit management

Implementation

PR #9069 implements all features described above.

[github-actions]

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

• feat: OAuth Marathon - multi-account credential rotation #8591: feat: OAuth Marathon - multi-account credential rotation
• Feature Request: Multi-Account Support with Automatic Failover #8864: Feature Request: Multi-Account Support with Automatic Failover
• feat: Add OAuth rate limits and usage dashboard #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.

[kfiramar]

Please bring this feature to life!

[mguttmann]

Implementation Update

PR #9069 has been rebased onto latest dev (v1.1.30+) and is ready for review.

What's implemented:

• ✅ Multiple OAuth accounts per provider with automatic failover
• ✅ Auth usage dashboard showing rate limits and account health
• ✅ Delete individual OAuth accounts from UI
• ✅ CLI: opencode auth usage, opencode auth switch
• ✅ API: /auth/usage, /auth/active, /auth/account

Related PRs:

• feat: Multi-Account OAuth Rotation with Settings UI and CLI Enhancements #9069 - This feature (Multi-Account OAuth) ← ready for review
• feat: YOLO Mode - Skip All Permission Prompts (CLI + Desktop) #9073 - YOLO Mode (depends on feat: Multi-Account OAuth Rotation with Settings UI and CLI Enhancements #9069)
• feat(auth): Auto-Relogin via Persistent Browser Sessions #9455 - Auto-Relogin (depends on feat: Multi-Account OAuth Rotation with Settings UI and CLI Enhancements #9069)

Branch: feat/multi-account-oauth-rotation-and-settings

[mguttmann]

Closing in favor of combined issue with all features