Provider Fallback Plugin

AI provider fallback management for OpenCode/Claude Code with automatic failover, usage analytics, and MCP integration.

Features

• 116 Models across 14 families (Claude, GPT, Gemini, Antigravity, GLM, Llama, etc.)
• 25 Providers with multi-auth support (subscription, OAuth, API key)
• Automatic Fallback when rate limits or quota exceeded
• Usage Analytics with provider comparison and cost tracking
• MCP Server for external integrations
• Per-Project Settings via .opencode/provider-fallback.local.md

Installation

Via npm (Recommended)

npm install -g provider-fallback-plugin

Then add to your OpenCode config (~/.config/opencode/opencode.json):

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

Manual Installation

git clone https://github.com/AttendantLion8/provider-fallback-plugin.git ~/plugins/provider-fallback-plugin
cd ~/plugins/provider-fallback-plugin
node scripts/install.js

Commands

Provider Families

Model Families

Usage Analytics

# View analytics dashboard
node scripts/show-analytics.js

# View with options
node scripts/show-analytics.js 7d --costs --compare

# Reset analytics
node scripts/reset-analytics.js --force

MCP Server

# Start MCP server
node mcp/server.js

# Or with custom port
MCP_PORT=3848 node mcp/server.js

Available Tools:

• provider.list / provider.active / provider.switch
• model.list / model.info
• analytics.summary / analytics.providers / analytics.costs
• auth.status / auth.check

Per-Project Configuration

Create .opencode/provider-fallback.local.md:

---
default_model: claude-sonnet-4-20250514
auto_switch: true
priority_override:
  - opencode-antigravity-auth
  - anthropic-subscription
  - openai-subscription
daily_limit: 1000
monthly_limit: 25000
---

Environment Variables

# Anthropic
ANTHROPIC_SUBSCRIPTION_KEY=...
ANTHROPIC_OAUTH_TOKEN=...
ANTHROPIC_API_KEY=...

# OpenAI
OPENAI_SUBSCRIPTION_KEY=...
OPENAI_OAUTH_TOKEN=...
OPENAI_API_KEY=...

# Google
GOOGLE_AI_SUBSCRIPTION=...
GOOGLE_OAUTH_TOKEN=...
GOOGLE_API_KEY=...

# OpenCode Antigravity
OPENCODE_ANTIGRAVITY_TOKEN=...
ANTIGRAVITY_AUTH_TOKEN=...
OC_ANTIGRAVITY_KEY=...

# AWS/Azure
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AZURE_OPENAI_API_KEY=...

# Others
OPENROUTER_API_KEY=...
TOGETHER_API_KEY=...
GROQ_API_KEY=...
XAI_API_KEY=...
MISTRAL_API_KEY=...
DEEPSEEK_API_KEY=...
COHERE_API_KEY=...

File Structure

provider-fallback-plugin/
├── .opencode-plugin/
│   └── plugin.json           # Plugin manifest
├── agents/
│   └── provider-advisor.md   # Provider recommendation agent
├── commands/                 # 7 slash commands
├── hooks/
│   ├── hooks.json           # SessionStart + Notification hooks
│   └── scripts/             # Hook handler scripts
├── lib/
│   ├── analytics.js         # Usage tracking
│   ├── auth.js              # Authentication
│   ├── index.js             # Main export
│   ├── models.js            # 116 models
│   └── providers.js         # 25 providers
├── mcp/
│   ├── README.md            # MCP documentation
│   └── server.js            # MCP server
├── scripts/
│   ├── install.js           # Installation script
│   ├── show-analytics.js    # Analytics viewer
│   ├── reset-analytics.js   # Reset analytics
│   └── uninstall.js         # Uninstallation
├── skills/
│   └── provider-management/ # Skill documentation
├── templates/
│   └── provider-fallback.local.md
├── tests/
│   └── test.js              # Validation tests
├── package.json
└── README.md

Testing

node tests/test.js

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © 2025 AttendantLion8