OpenCode Model Fallback Chain

Never let a stalled model break your flow. Automatic retries with backup models when things go wrong.

When you're deep in the zone, the last thing you want is an AI model that times out, hits a rate limit, or throws an error. This plugin keeps you moving by automatically retrying failed or slow prompts with backup models from your configured fallback chain — starting with free tiers and falling back to paid only when necessary.

Why You Need This

• API outages happen — Your primary provider goes down, but you have backups ready
• Rate limits strike at the worst times — "Too many requests" shouldn't mean "stop working"
• Some models are just slow — Set a timeout and let faster alternatives take over
• Free models are flaky — Start with free tiers and seamlessly fall back to paid only when needed
• You want reliability without thinking about it — Configure once, forget about it

Features

• Automatic failover — Detects timeouts and errors, switches to the next model instantly
• Multiple fallback chains — Different backup sequences for different primary models
• Smart retry logic — Only retries on recoverable errors (timeouts, 5xx, rate limits)
• Clean conversation history — Retries reuse the same message ID, no thread pollution
• Visual feedback — Toast notifications show when fallback happens
• Flexible configuration — Project-level, global, or environment-based config

Installation

Add the plugin to your OpenCode configuration:

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

Configuration

Define your fallback chains using model IDs from opencode models. Each chain is a prioritized list — if the first model fails, it tries the second, then the third, and so on.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-model-fallback-chain"],
  "experimental": {
    "modelFallbackChain": {
      "timeoutMs": 60000,
      "chains": [
        [
          "opencode/kimi-k2.5-free",
          "opencode/kimi-k2.5",
          "nvidia/moonshotai/kimi-k2.5"
        ],
        [
          "anthropic/claude-sonnet-4",
          "openrouter/anthropic/claude-sonnet-4"
        ]
      ]
    }
  }
}

Configuration Options

| Key | Type | Default | Description | |-----|------|---------|-------------| | chains | string[][] | (required) | Array of fallback chains. Each chain is an array of provider/model strings. | | timeoutMs | number | 60000 | Milliseconds to wait before considering a model stalled and triggering fallback. Minimum: 1000. |

Configuration Sources

The plugin searches for configuration in this order:

1. OpenCode SDK config payload (if provided)
2. Project config — opencode.jsonc or .opencode/opencode.jsonc
3. Environment variable — OPENCODE_CONFIG or OPENCODE_CONFIG_DIR
4. Global config — ~/.config/opencode/opencode.jsonc or ~/.opencode/opencode.jsonc

How It Works

Timeout Handling

When you send a message, the plugin starts a timer. If the model doesn't respond within timeoutMs:

1. The in-flight request is aborted
2. The next model in the chain is automatically selected
3. Your prompt is resent with the same message ID (no conversation clutter)
4. A toast appears: "provider/model failed, retrying with backup/model..."

Note: The last model in a chain is never interrupted by the plugin timeout — it gets the full time it needs.

Error Handling

When a model returns an error, the plugin checks if it's retryable:

• Retryable: Timeouts, 5xx server errors, 408/429 rate limits, retryable API errors
• Not retryable: Authentication errors, message length errors, user-aborted requests (unless timeout-related)

If retryable, it rotates to the next model in the chain (round-robin, wrapping back to the first after the last).

Fallback Chain Selection

The plugin automatically matches your selected model to its corresponding chain. If you're using opencode/kimi-k2.5-free, it finds the chain containing that model and follows the sequence.

Example Use Cases

Cost-Optimized Fallback

Start with free/cheaper models, automatically escalate to premium only when the free ones are slow or unavailable:

{
  "experimental": {
    "modelFallbackChain": {
      "timeoutMs": 45000,
      "chains": [
        [
          "opencode/kimi-k2.5-free",
          "opencode/kimi-k2.5",
          "anthropic/claude-sonnet-4"
        ]
      ]
    }
  }
}

High-Availability Setup

Ensure you always have a working model, even during outages:

{
  "experimental": {
    "modelFallbackChain": {
      "timeoutMs": 30000,
      "chains": [
        [
          "anthropic/claude-opus-4",
          "openrouter/anthropic/claude-opus-4",
          "google/gemini-2.5-pro"
        ]
      ]
    }
  }
}

Multiple Model Tiers

Different chains for different needs:

{
  "experimental": {
    "modelFallbackChain": {
      "timeoutMs": 60000,
      "chains": [
        ["anthropic/claude-opus-4", "openrouter/anthropic/claude-opus-4"],
        ["anthropic/claude-sonnet-4", "google/gemini-2.5-flash"],
        ["opencode/kimi-k2.5-free", "opencode/kimi-k2.5"]
      ]
    }
  }
}

Requirements

• OpenCode CLI with plugin support
• Compatible models configured in your OpenCode setup

License

MIT © David Guijarro