opencode-auto-fallback

OpenCode plugin that automatically detects model errors and switches to a fallback model chain — with intelligent retry backoff for transient failures.

Features

• Two-tier classification: immediate fallback for quota/auth errors, exponential backoff retry for rate limits and transient failures
• Fallback chain: ordered list of fallback models per agent, with variant/reasoning/temperature support
• Per-model timed cooldown: failed models are skipped until cooldown expires
• Default‑retry safety net: any unrecognized error is treated as retryable
• Zero config startup: auto-generates fallback.json with sensible defaults on first run
• Toast notifications: terminal toasts when fallback is triggered

Installation

1. Register in opencode config

Add "opencode-auto-fallback" to the plugin array in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-auto-fallback"],
}

2. Configuration (optional)

On first run, a default config is auto-created at ~/.config/opencode/fallback.json. You can customize it:

{
  "$schema": "https://raw.githubusercontent.com/HyeokjaeLee/opencode-auto-fallback/main/docs/fallback.schema.json",
  "enabled": true,
  "defaultFallback": ["anthropic/claude-opus-4-7"],
  "agentFallbacks": {
    "reviewer": [
      "zai-coding-plan/glm-5.1",
      {
        "model": "openai/gpt-5.5",
        "temperature": 0.5,
        "reasoningEffort": "medium",
      },
    ],
  },
  "cooldownMs": 60000,
  "maxRetries": 2,
  "logging": false,
}

Fallback Model Entry

Each entry in a fallback chain can be a simple string or an object:

// Simple
"openai/gpt-5.5"

// With options
{
  "model": "openai/gpt-5.5",
  "variant": "high",
  "temperature": 0.5,
  "reasoningEffort": "medium",
  "maxTokens": 8192
}

How It Works

Error Classification

Retry Flow

1st failure → abort → wait 2s   → re-prompt with SAME model
2nd failure → abort → wait 4s   → re-prompt with SAME model
3rd failure → abort → wait 8s   → re-prompt with SAME model
4th failure → FALLBACK CHAIN: try next model in ordered list

Immediate fallback errors (quota, auth) skip retries entirely and go straight to the fallback chain.

Fallback Chain

The plugin tries each model in the chain sequentially. Models in cooldown are automatically skipped. If all models are exhausted, the error is logged and a critical toast is shown.

Compatibility with Other Fallback Plugins

If another plugin with model fallback logic is installed alongside this one, enable only one to avoid conflicts. Both plugins will intercept the same error events via chat.message — the one loaded last in opencode.json takes precedence.

This plugin uses an aggressive abort + revert + re-prompt approach that resets the session state. Any pending fallback actions from other plugins are discarded. To use this plugin exclusively, disable fallback features in other plugins' configurations.

// ❌ Conflict — multiple fallback plugins active
"plugin": ["other-fallback-plugin", "opencode-auto-fallback"]

// ✅ Disable this plugin
{ "enabled": false }

// ✅ Disable the other plugin's fallback feature
// Check its documentation for the relevant config option

Development

# Install dependencies
bun install

# Type check
tsc --noEmit

# Run tests (64 tests)
bun vitest run

# Bump version (CI auto-publishes)
npm version patch --no-git-tag-version
git push