opencode-fallback

OpenCode plugin that automatically recovers from provider disconnects (resuming mid-response) and rate limits (switching to a fallback model). Also includes an optional auto-continue loop mode.

Features

• Disconnect Recovery: Detects when a provider drops the connection mid-response, captures partial output, and sends a continuation prompt so the model picks up exactly where it left off.
• Rate Limit Fallback: Detects rate-limit/quota errors and seamlessly re-sends the original request using a configurable fallback model.
• Auto-Continue Loop ("Ralph Loop"): Activate per-session autonomous looping that sends a configurable nudge prompt every time the session goes idle, keeping the model working continuously.

Installation

Add to your opencode.jsonc:

{
  "plugin": ["opencode-fallback"]
}

Configuration

The plugin auto-creates a default fallback.json in your OpenCode config directory on first run. Edit it to customize behavior.

Locations checked (in order):

1. ~/.config/opencode/fallback.json
2. ~/.config/opencode/config/fallback.json
3. ~/.config/opencode/plugins/fallback.json
4. ~/.config/opencode/plugin/fallback.json

Legacy rate-limit-fallback.json filenames are also supported in all the same locations.

Example config:

{
  "enabled": true,
  "fallbackModel": "anthropic/claude-opus-4-5",
  "cooldownMs": 300000,
  "logging": false,
  "resumeWithSameModel": true,
  "maxResumeAttempts": 3,
  "maxPartialContentLength": 12000,
  "rateLimitPatterns": [
    "rate limit",
    "usage limit",
    "too many requests",
    "quota exceeded"
  ],
  "disconnectPatterns": [
    "overloaded",
    "service unavailable",
    "bad gateway",
    "internal server error",
    "connection reset",
    "connection closed",
    "econnreset",
    "econnaborted",
    "socket hang up",
    "network error",
    "reset by peer",
    "broken pipe",
    "upstream connect error",
    "stream error",
    "unexpected end",
    "premature close",
    "disconnected",
    "request timed out",
    "connection timed out",
    "response timeout",
    "502",
    "503",
    "529"
  ],
  "loopEnabled": true,
  "loopStartPhrase": "Ralph loop mode enabled",
  "loopStopPhrase": "Ralph loop mode disabled",
  "loopPrompt": "Continue working on the task."
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable the plugin entirely | | fallbackModel | string | object | "anthropic/claude-opus-4-5" | Fallback model (see formats below) | | cooldownMs | number | 300000 | Rate-limit cooldown period in ms (default: 5 minutes) | | logging | boolean | false | Enable file-based debug logging | | rateLimitPatterns | string[] | (see above) | Case-insensitive substring patterns for rate-limit detection | | disconnectPatterns | string[] | (see above) | Word-boundary regex patterns for disconnect/stream-error detection | | resumeWithSameModel | boolean | true | On first disconnect, retry with the same model before escalating | | maxResumeAttempts | number | 3 | Max consecutive disconnect resume attempts before giving up | | maxPartialContentLength | number | 12000 | Max characters of partial content included in the continuation prompt (tail-truncated if exceeded) | | continuationPromptTemplate | string | (see below) | Template for the continuation prompt; use {{partial_content}} as placeholder | | loopEnabled | boolean | true | Master toggle for the auto-continue loop feature | | loopStartPhrase | string | "Ralph loop mode enabled" | Phrase in a user message that activates the loop for that session | | loopStopPhrase | string | "Ralph loop mode disabled" | Phrase in a user message that deactivates the loop for that session | | loopPrompt | string | "Continue working on the task." | Prompt text sent to keep the model working each loop iteration |

Fallback Model Format

The fallbackModel field accepts a "provider/model" string:

{
  "fallbackModel": "anthropic/claude-opus-4-5"
}

Or an explicit object:

{
  "fallbackModel": {
    "providerID": "anthropic",
    "modelID": "claude-opus-4-5"
  }
}

Continuation Prompt Template

The default template for disconnect recovery is:

Your previous response was interrupted mid-stream by a provider error.
Here is exactly what you had generated before the interruption:

---BEGIN PARTIAL RESPONSE---
{{partial_content}}
---END PARTIAL RESPONSE---

Continue your response EXACTLY where it was cut off. Do not repeat any of
the content above. Do not acknowledge the interruption. Just seamlessly
continue from the exact point where the text ends.

Override via the continuationPromptTemplate config field. The {{partial_content}} placeholder is replaced with the captured partial output.

Pattern Matching

The two pattern sets use different matching strategies:

• Rate-limit patterns use case-insensitive substring matching (safe for multi-word phrases like "rate limit").
• Disconnect patterns use case-insensitive word-boundary regex matching (\b...\b), preventing false positives like "eof" matching inside "thereof" or "502" matching inside longer numbers.

Logging

When logging: true, logs are written to:

~/.local/share/opencode/logs/fallback.log

Log entries include timestamps and structured details about detection events, recovery attempts, and errors.

How It Works

Disconnect Recovery

1. Detection: Listens for session.status retry events whose message matches a disconnect pattern.
2. Abort: Stops the current retry loop.
3. Capture: Fetches messages and extracts text from the last (interrupted) assistant response.
4. Revert: Reverts the session to the last user message, removing the incomplete assistant response.
5. Continue: Sends a continuation prompt that includes the partial content, instructing the model to pick up exactly where it left off.
6. Model selection: First attempt retries with the same model (it was a disconnect, not a model issue). Subsequent attempts escalate to the fallback model.
7. Backoff: Exponential delay between attempts (2s, 4s, 8s, up to 30s).
8. Guard: Stops after maxResumeAttempts consecutive failures.

If no partial content was captured (e.g., the response hadn't started), the original user message is re-sent instead.

Rate Limit Fallback

1. Detection: Listens for retry events whose message matches a rate-limit pattern.
2. Abort: Stops the retry loop.
3. Revert: Reverts the session to the last user message.
4. Re-send: Sends the original user message with the configured fallback model.
5. Cooldown: Starts a cooldown timer (default 5 minutes). During cooldown, subsequent rate limits on the same session are ignored to prevent re-trigger spam.

The conversation history stays clean -- no duplicate messages or "continue" artifacts.

Auto-Continue Loop

The loop feature is activated per-session using a magic phrase in any user message.

1. Include your configured start phrase (default: "Ralph loop mode enabled") in any message to activate the loop for that session.
2. Once active, every time the session goes idle, the plugin automatically sends the configured loop prompt (default: "Continue working on the task.").
3. Include the stop phrase (default: "Ralph loop mode disabled") to deactivate.

Notes:

• Stop takes priority over start if both phrases appear in the same message.
• The activation message itself does not trigger a loop iteration (the loop starts on the next idle event).
• The loop integrates with disconnect/rate-limit recovery: recovery runs first, and the loop resumes on the next idle.

Race Condition Handling

The plugin uses a timestamp-based grace window to avoid re-triggering on stale retry events that were queued before a plugin-initiated abort took effect. Any retry event arriving within 5 seconds of the last plugin abort is ignored.

Backwards Compatibility

• The legacy config filename rate-limit-fallback.json is still recognized.
• The legacy patterns field in the config file maps to rateLimitPatterns.
• The old type export RateLimitFallbackConfig is preserved as an alias for FallbackConfig.

Local Development

For local development, use a file:// URL in your config:

{
  "plugin": [
    "file:///path/to/opencode-fallback/index.ts"
  ]
}

License

MIT