O-Switcher

Seamless OpenRouter profile rotation for OpenCode. Buy multiple cheap subscriptions and use them as one pool: when one profile hits quota or rate limits, O-Switcher keeps the backend moving to the next healthy profile.

Why?

• OpenRouter profiles have quota and rate-limit ceilings.
• Without O-Switcher, you re-auth manually and break flow.
• With O-Switcher, the current auth/profile remains the source of truth until there is real failure evidence.
• One cheap subscription pool behaves like one uninterrupted working pool.

Supported delivery paths

O-Switcher now documents only the supported OpenCode 1.4.x delivery surfaces:

• Plugins
  • plugin in opencode.json
  • .opencode/plugins/
  • ~/.config/opencode/plugins/
• Commands
  • command in opencode.json
  • .opencode/commands/
  • ~/.config/opencode/commands/

The supported contract is backend-first. If the backend plugin loads successfully, switching, diagnostics, and operator tools are available. Optional UI affordances are not the delivery contract.

Quick start

Published package

Add O-Switcher to your OpenCode config:

{
  "plugin": ["@albinocrabs/o-switcher@latest"]
}

That is enough to enable the backend plugin.

Deterministic local staging

If you are running from a local checkout, use the installer instead of keeping a live checkout path in plugin[]:

npm install
npm run install:opencode-local -- --target /path/to/your-project

The installer stages a supported local layout:

.opencode/
  plugins/
    o-switcher.js
    o-switcher/
      package.json
      dist/
      node_modules/
  commands/
    switcher.md

That gives you a staged backend plugin under .opencode/plugins/ and a staged /switcher command asset under .opencode/commands/ without relying on a live checkout path.

Control surface

O-Switcher exposes two supported operator layers:

1. Backend tools on the plugin surface:
   • switcherStatus
   • switcherDoctor
   • switcherUse
   • switcherNext
   • switcherPinCurrent
2. A staged /switcher custom command in .opencode/commands/switcher.md that routes to those backend tools.

The documented operator path is explicit command-driven control: inspect with switcherStatus and switcherDoctor, then switch with switcherUse, switcherNext, or switcherPinCurrent when needed.

Runtime behavior

• The active backend profile is the current source of truth.
• Ambiguous same-provider failures are recorded as warnings instead of triggering blind switching.
• switcherDoctor reports backend facts, warnings, and unknowns honestly.
• Diagnostics history records heartbeats, manual actions, and recent switch decisions.

When a request fails, O-Switcher applies bounded retries and bounded failover:

| Failure class | Backend action | | --- | --- | | Rate limited | Retry with cooldown/backoff | | Transient server failure | Retry with backoff | | Model unavailable | Try the next healthy target | | Auth failure | Stop and surface re-auth required | | Ambiguous same-provider failure | Record warning, no blind failover |

Configuration

Zero config works. Optional tuning in OpenCode 1.4.x goes through plugin tuple options:

{
  "plugin": [
    ["@albinocrabs/o-switcher@latest", {
      "retry": 3,
      "timeout": 30000
    }]
  ]
}

| Option | Default | Description | | --- | --- | --- | | retry | 3 | Max retry attempts per request | | timeout | 30000 | Request timeout in milliseconds |

Restart caveat

Opening a new OpenCode window is not a clean runtime restart. After changing plugin delivery or local staged assets, fully restart OpenCode before you trust the result.

Documentation

• Getting Started — supported install, local staging, troubleshooting
• API Reference — config, tools, supported vs unsupported surfaces
• Examples — published-package and staged-local examples
• Architecture — backend-first contract and current limitations

Development

git clone https://github.com/apolenkov/o-switcher.git
cd o-switcher
npm install
npm test
npm run typecheck
npm run build

See CONTRIBUTING.md for the full development guide.

Roadmap

O-Switcher started as a plugin, but the long-term goal is to upstream multi-profile failover ideas into OpenCode itself.

• Now: backend-first OpenCode plugin for OpenRouter profile rotation
• Next: harden the supported operator surface and document it end-to-end
• Vision: each provider can have multiple interchangeable profiles with transparent bounded failover

License

Apache-2.0