pi-opencode-go-rotation

Rotate between multiple OpenCode Go API keys. The extension is best-effort and reactive: it rotates only when opencode surfaces a matching assistant error message.

Install

pi install npm:@lnilluv/pi-opencode-go-rotation

Setup

Add your API keys:

/opencode add personal sk-xxxx
/opencode add work sk-yyyy
/opencode add backup sk-zzzz

The first key added becomes active immediately.

How it works

The extension sets the active key as a runtime override, which takes priority over OPENCODE_API_KEY environment variables and auth.json credentials.

The extension has two recovery paths:

1. Surfaced errors: when opencode returns a matching 429/rate-limit/quota error, the extension marks the current key as on cooldown, switches to the next key not on cooldown, and applies it via setRuntimeApiKey.
2. Silent stalls: when an opencode-go provider request has no response or stream activity for the watchdog window, the extension rotates keys, aborts the hung turn, and rewrites the abort as a retryable timeout error.

This is still reactive: it does not check usage or limits ahead of time.

Pi's built-in auto-retry picks up the new key on the next request.

Cooldowns default to 60 minutes. After cooldown expires, the key becomes available again.

Commands

| Command | Description | |---------|-------------| | /opencode or /opencode status | Show all keys, active key marker, cooldown status | | /opencode use <n> | Switch to key number n (1-based) | | /opencode next | Advance to the next configured key and clear its cooldown before activating it | | /opencode add <name> <key> | Add a new key | | /opencode rm <n> | Remove key number n | | /opencode reset | Clear all cooldowns | | /opencode cooldown <min> | Set or view cooldown duration in minutes | | /opencode watchdog [status\|on\|off\|<seconds>] | Configure silent-stall detection |

Configuration

Keys are stored in ~/.pi/agent/opencode-keys.json with file permissions 0600.

{
  "keys": [
    { "name": "personal", "key": "sk-xxx" },
    { "name": "work", "key": "sk-yyy" }
  ],
  "activeKeyIndex": 0,
  "cooldownMinutes": 60,
  "watchdogEnabled": true,
  "watchdogIdleMs": 90000,
  "cooldowns": {}
}

Retry settings

Pair with pi's auto-retry for best results. In ~/.pi/agent/settings.json:

{
  "retry": {
    "enabled": true,
    "maxRetries": 3
  }
}

Set maxRetries to at least the number of keys so all keys get a chance before pi gives up.

Limitations

• OpenCode Go currently has no API endpoint for checking usage, remaining quota, or limits proactively.
• The watchdog is scoped to the opencode-go provider only. Other providers are not aborted or rotated.
• A legitimate long-running request with no stream activity can be treated as stalled; tune with /opencode watchdog <seconds> or disable with /opencode watchdog off.
• When all keys are rate-limited simultaneously, the extension force-advances to the next key and clears its cooldown.
• Keys added via /opencode add are stored in plaintext. The config file is created with 0600 permissions.
• If opencode later adds an API endpoint for Go plan usage/limit verification, this extension can be updated to use it.

License

MIT