Skip to content

MULTI-ACCOUNT.md

Latest commit

 

History

History
205 lines (145 loc) · 5.44 KB

MULTI-ACCOUNT.md

File metadata and controls

205 lines (145 loc) · 5.44 KB
Raw

Multi-Account Setup

Add multiple Google accounts to increase your combined quota. The plugin automatically rotates between accounts when one is rate-limited.

opencode auth login  # Run again to add more accounts

Load Balancing Behavior

  • Sticky account selection — Sticks to the same account until rate-limited (preserves Anthropic's prompt cache)
  • Per-model-family limits — Rate limits tracked separately for Claude and Gemini models
  • Antigravity-first for Gemini — All Gemini requests use Antigravity quota first, then automatically fall back to Gemini CLI when exhausted across all accounts
  • Smart retry threshold — Short rate limits (≤5s) are retried on same account
  • Exponential backoff — Increasing delays for consecutive rate limits

Dual Quota Pools

For Gemini models, the plugin accesses two independent quota pools per account:

Quota Pool When Used
Antigravity Default for all requests
Gemini CLI Automatic fallback when Antigravity exhausted on ALL accounts

This effectively doubles your Gemini quota when you have quota_fallback enabled.

How Quota Fallback Works

  1. Request uses Antigravity quota on current account
  2. If rate-limited, plugin checks if ANY other account has Antigravity available
  3. If yes → switch to that account (stay on Antigravity)
  4. If no (all accounts exhausted) → fall back to Gemini CLI quota on current account
  5. Model names are automatically transformed (e.g., gemini-3-flash → gemini-3-flash-preview)

To enable automatic fallback between pools, set in antigravity.json:

{
  "quota_fallback": true
}

Checking Quotas

Check your current API usage across all accounts:

opencode auth login
# Select "Check quotas" from the menu

This shows remaining quota percentages and reset times for each model family:

  • Claude - Claude Opus/Sonnet quota
  • Gemini 3 Pro - Gemini 3 Pro quota
  • Gemini 3 Flash - Gemini 3 Flash quota

Standalone Quota Script

For checking quotas outside OpenCode (debugging, CI, etc.):

node scripts/check-quota.mjs                    # Check all accounts
node scripts/check-quota.mjs --account 2        # Check specific account
node scripts/check-quota.mjs --path /path/to/accounts.json  # Custom path

Managing Accounts

Enable or disable specific accounts to control which ones are used for requests:

opencode auth login
# Select "Manage accounts (enable/disable)"

Or select an account from the list and choose "Enable/Disable account".

Disabled accounts:

  • Are excluded from automatic rotation
  • Still appear in quota checks (marked [disabled])
  • Can be re-enabled at any time

This is useful when:

  • An account is temporarily banned or rate-limited for extended periods
  • You want to reserve certain accounts for specific use cases
  • Testing with a subset of accounts

Adding Accounts

When running opencode auth login with existing accounts:

2 account(s) saved:
  1. user1@gmail.com
  2. user2@gmail.com

(a)dd new account(s) or (f)resh start? [a/f]:

Choose a to add more accounts while keeping existing ones.

Account Storage

Accounts are stored in ~/.config/opencode/antigravity-accounts.json:

{
  "version": 3,
  "accounts": [
    {
      "email": "user1@gmail.com",
      "refreshToken": "1//0abc...",
      "projectId": "my-gcp-project",
      "enabled": true
    },
    {
      "email": "user2@gmail.com",
      "refreshToken": "1//0xyz...",
      "enabled": false
    }
  ],
  "activeIndex": 0,
  "activeIndexByFamily": {
    "claude": 0,
    "gemini": 0
  }
}

⚠️ Security: This file contains OAuth refresh tokens. Treat it like a password file.

Fields

Field Description
email Google account email
refreshToken OAuth refresh token (auto-managed)
projectId Optional. Required for Gemini CLI models. See Troubleshooting.
enabled Optional. Set to false to disable account rotation. Defaults to true.
activeIndex Currently active account index
activeIndexByFamily Per-model-family active account (claude/gemini tracked separately)

Token Revocation

If Google revokes a token (e.g., password change, security event), you'll see invalid_grant errors. The plugin automatically removes invalid accounts.

To manually reset:

rm ~/.config/opencode/antigravity-accounts.json
opencode auth login

Parallel Sessions (oh-my-opencode)

When using oh-my-opencode with parallel subagents, multiple processes may select the same account, causing rate limit errors.

Solution: Enable PID-based offset in antigravity.json:

{
  "pid_offset_enabled": true
}

This distributes sessions across accounts based on process ID.

Alternatively, add more accounts via opencode auth login.

Account Selection Strategies

Configure in antigravity.json:

{
  "account_selection_strategy": "hybrid"
}
Strategy Behavior Best For
sticky Same account until rate-limited Prompt cache preservation
round-robin Rotate to next account on every request Maximum throughput
hybrid Deterministic selection based on health score + token bucket + LRU Best overall distribution

See Configuration for more details.