https://github.com/rahadiana/opencode-multi-account
A plugin for OpenCode that automatically manages multiple API accounts. When one account hits its rate limit, the plugin will automatically switch to the next account based on priority.
https://github.com/rahadiana/opencode-multi-account
account-rotation opencode opencode-plugin
Last synced: 2 days ago
JSON representation
A plugin for OpenCode that automatically manages multiple API accounts. When one account hits its rate limit, the plugin will automatically switch to the next account based on priority.
- Host: GitHub
- URL: https://github.com/rahadiana/opencode-multi-account
- Owner: rahadiana
- License: mit
- Created: 2026-04-15T18:48:44.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-26T15:47:37.000Z (about 1 month ago)
- Last Synced: 2026-04-26T16:21:48.333Z (about 1 month ago)
- Topics: account-rotation, opencode, opencode-plugin
- Language: TypeScript
- Homepage: https://github.com/rahadiana/opencode-multi-account
- Size: 85.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🔌 OpenCode Multi-Account Manager Plugin
A plugin for [OpenCode](https://opencode.ai) that automatically manages multiple API accounts. When one account hits its rate limit, the plugin will **automatically switch to the next account** based on priority.
## ✨ Features
- **Priority Rotation** — Accounts are sorted by priority (P1 → P2 → P3, etc.)
- **Provider-Level Auto-Switch** — When a rate limit is detected for Provider X, rotation occurs only within Provider X's account pool.
- **All Providers Supported** — Compatible with 35+ providers supported by OpenCode (Anthropic, OpenAI, Google, Groq, DeepSeek, OpenRouter, xAI, etc.)
- **Provider Exhausted Notifications** — Alerts you when **all accounts for a provider are exhausted**.
- **Custom Tools** — Manage accounts directly from the OpenCode TUI.
- **Cooldown Tracking** — Rate-limited accounts automatically reactivate after the cooldown period.
## 🛠️ Installation
### Method 1: Via NPM (Recommended)
This plugin is officially published on npm. You can easily install it into OpenCode by adding it to your `opencode.json` configuration file:
```json
{
"plugin": ["@rahadiana/opencode-multi-account"]
}
```
### Method 2: Automatic AI Installation 🤖
You can instruct your AI assistant (like OpenCode, Claude, or Cursor) to install and configure this plugin for you automatically. Just provide them with this prompt:
> "Please install the OpenCode Multi-Account Manager plugin for me. You can read the instructions at `AI_PLUGIN_GUIDE.md` from this repository: https://github.com/rahadiana/opencode-multi-account"
### Method 3: Manual Installation from Source (For Developers)
If you are a developer wanting to test, modify, or contribute to this plugin, you can install it manually from the GitHub repository.
#### Prerequisites
- Node.js 18+ (latest LTS recommended)
- npm & Git
#### Developer Install (Linux/macOS)
```bash
# Clone the repository
git clone https://github.com/rahadiana/opencode-multi-account.git
cd opencode-multi-account
# Install dependencies and build
npm ci
npm run build
# Copy to global plugins directory
mkdir -p ~/.config/opencode/plugins
cp -r . ~/.config/opencode/plugins/multi-account
```
#### Developer Install (Windows PowerShell)
```powershell
# Clone the repository
git clone https://github.com/rahadiana/opencode-multi-account.git
cd opencode-multi-account
# Install dependencies and build
npm ci
npm run build
# Copy to global plugins directory
New-Item -Path "$env:USERPROFILE\.config\opencode\plugins" -ItemType Directory -Force
Copy-Item . "$env:USERPROFILE\.config\opencode\plugins\multi-account" -Recurse -Force
```
### Multi-Account Configuration Location
After installation, the plugin requires an `accounts.json` configuration file. Place it in the appropriate directory for your OS:
| OS | Config Directory |
|----|------------------|
| Linux / macOS | `~/.config/opencode/multi-account/` |
| Windows | `$env:USERPROFILE\.config\opencode\multi-account\` |
### Troubleshooting
- **Plugin not detected in OpenCode**: Ensure you've added it to `opencode.json` properly (if using npm) or that the folder is copied correctly (if installing from source).
- **Build failed (Source Install)**: Run `npm ci` again, check for TypeScript errors, and ensure Node 18+ is installed.
- **Account configuration not read**: Ensure `accounts.json` exists in the exact config directory mentioned above and contains valid JSON.
### Generator accounts.example.json
Use the following script to create or update `accounts.example.json`:
```bash
node scripts/generate_accounts_example.mjs
```
This script will:
- Read `accounts.json` (if it exists) and generate `accounts.example.json` with sanitized tokens.
- Create a default template if `accounts.json` is not found.
Make sure to run this script whenever the structure of `accounts.json` changes.
## 📖 Usage
This plugin provides custom tools that you can use directly in OpenCode:
- **`account_status`** — Check the status of all configured accounts (active, rate-limited, cooldown)
- **`account_list`** — View a list of all configured accounts with their priorities
- **`account_switch`** — Manually switch to a specific account by ID
- **`account_config_path`** — View the path to the accounts configuration file
### Example Usage
```
/account_status
/account_list
/account_switch
/account_config_path
```
## ⚙️ Configuration
The plugin uses an `accounts.json` configuration file to manage your API accounts.
### Configuration File Location
| OS | Path |
|----|------|
| Linux / macOS | `~/.config/opencode/multi-account/accounts.json` |
| Windows | `%USERPROFILE%\.config\opencode\multi-account\accounts.json` |
### accounts.json Format
```json
{
"accounts": [
{
"id": "anthropic-p1",
"name": "Anthropic Primary",
"provider": "anthropic",
"apiKey": "sk-ant-...",
"priority": 1,
"cooldownPeriod": 300000
},
{
"id": "anthropic-p2",
"name": "Anthropic Secondary",
"provider": "anthropic",
"apiKey": "sk-ant-...",
"priority": 2,
"cooldownPeriod": 300000
},
{
"id": "openai-p1",
"name": "OpenAI Primary",
"provider": "openai",
"apiKey": "sk-...",
"priority": 1,
"cooldownPeriod": 300000
}
]
}
```
### Configuration Fields
| Field | Required | Description |
|-------|----------|-------------|
| `id` | ✅ | Unique identifier for the account (e.g., `anthropic-p1`) |
| `name` | ✅ | Human-readable name for the account |
| `provider` | ✅ | Provider name (e.g., `anthropic`, `openai`, `google`) |
| `apiKey` | ✅ | Your API key for this provider |
| `priority` | ✅ | Priority level (1 = highest, higher numbers = lower priority) |
| `cooldownPeriod` | ✅ | Cooldown time in milliseconds after rate limit (e.g., `300000` = 5 minutes) |
| `baseUrl` | ❌ | Optional custom base URL for the provider API |
### Provider Support
The plugin supports 35+ providers including:
- **Anthropic** (Claude)
- **OpenAI** (GPT-4, GPT-3.5)
- **Google** (Gemini)
- **Groq**
- **DeepSeek**
- **OpenRouter**
- **xAI** (Grok)
- And many more supported by OpenCode