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 backend command entrypoint 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
   • switcherAutoOn
   • switcherAutoOff
2. A staged /switcher custom command in .opencode/commands/switcher.md that routes to those backend tools.

auto mode remains available but is explicitly beta. Manual control is the safer operator path when you want the healthy current auth token to stay pinned.

Runtime behavior

• The current auth/profile is the source of truth.
• Ambiguous same-provider failures do not trigger automatic failover.
• 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:

Configuration

Zero config works. Optional tuning:

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

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 close remaining beta gaps
• Vision: each provider can have multiple interchangeable profiles with transparent bounded failover

License

Apache-2.0