opencode-swap

Multi-account switcher for OpenCode.

OpenCode has no built-in way to keep several accounts for one provider around and flip between them. opencode-swap is a small standalone CLI that does exactly that: it keeps a securely-stored copy of each account's OpenCode auth state and swaps the one OpenCode currently considers "active."

opencode-swap use openai personal && opencode

Core workflow stays standalone: no background process or proxy runs while OpenCode is. An optional terminal UI plugin adds account status and commands without taking ownership of credentials or swaps.

Status

Early. Core behavior is covered by automated tests and has been exercised against a real OpenCode installation. See docs/roadmap.md for what's done and what's left.

⚠️ OpenAI is the only provider tested end to end with real accounts. Other provider implementations were derived from OpenCode source and synthetic tests. Maintainer does not have accounts for those services, so testers are wanted for every non-OpenAI provider.

🧪 Testers wanted. If you use any non-OpenAI provider, please open an issue with the provider, auth method, OpenCode version, and sanitized failure details. Never include credentials. docs/provider-research-prompt.md has a copy-paste OpenCode prompt that gathers safe source evidence for one provider.

🤖 This project is built largely with agentic AI coding tools, under human review. Read the code before trusting it with your credentials.

Looking for load balancing?

opencode-swap activates one account at a time. If you instead want requests spread across several accounts at runtime, that's a different problem, and opencode-balancer is the project for it. docs/security.md covers the storage trade-offs each approach makes.

Install

Two pieces ship from this repo: the CLI, which does all the work, and an optional OpenCode TUI plugin that surfaces it inside the TUI. Install the CLI first — the plugin shells out to it.

1. CLI (required)

uv tool install opencode-swap     # or: pipx install opencode-swap
opencode-swap --help

uvx opencode-swap --help works too, without installing anything permanently.

2. OpenCode TUI plugin (optional)

Adds the active account and its usage to the session prompt, plus /swap, /swap-next, and /swap-refresh in the command palette:

opencode plugin @leinardi/opencode-swap --global

Restart OpenCode afterwards. The plugin invokes opencode-swap from your PATH, so it needs the CLI from step 1 already installed. See OpenCode TUI integration for what it renders and when it stays hidden.

From source

git clone https://github.com/leinardi/opencode-swap.git
cd opencode-swap
uv sync
uv run opencode-swap --help

uv tool install . from the checkout also works if you want opencode-swap and ocs on your PATH from a local checkout.

Quickstart

# 1. Log into OpenCode normally with your first account.
opencode auth login

# 2. Import whichever account is currently active into opencode-swap.
opencode-swap add openai personal

# 3. Log into a second account.
opencode auth login   # choose/authenticate a different ChatGPT account
opencode-swap add openai work

# 4. See what's saved.
opencode-swap list
#   personal   ...abcd   -
# * work       ...ef01   -

# 5. Switch whenever you like.
opencode-swap use openai personal
opencode

Names are yours to choose (lowercase letters/digits/-/_/.). Re-running add with the provider and name of an already-imported account refreshes its stored tokens in place; it won't create a duplicate.

Commands

use, switch, remove, and restore ask for confirmation unless you pass -y/--yes (and refuse to prompt at all on a non-interactive terminal, so pass -y in scripts). use also warns if it detects a running opencode process, since switching while OpenCode might be mid-token-refresh is the one real race condition this tool can't fully close (see docs/security.md).

No command ever prints an access token, refresh token, or API key. Account ids are shown truncated to their last four characters.

OpenCode TUI integration

Install it with step 2 of Install.

integrations/opencode-tui-plugin uses OpenCode's supported TUI-plugin API to render active account and active-only usage at right side of session prompt metadata:

Plan · GPT-5.6 Sol OpenAI · medium                         work · 17%

It only appears after session has sent a request through provider managed by opencode-swap; it stays hidden for unrelated providers. /swap opens a safe account picker, /swap-next rotates current provider, and /swap-refresh refreshes visible status. See the plugin README for install and concurrency limits.

Core CLI does not require Bun. TUI plugin development and root make verify require Bun 1.3.14; make check remains Python-only and offline.

Moving accounts to another computer

# Source computer
opencode-swap export ~/opencode-accounts.ocs

# Transfer the archive, then on the destination computer
opencode-swap import ~/opencode-accounts.ocs
opencode-swap use openai personal

export asks for a password twice; import asks for it once. Password input requires an interactive terminal and is never placed in command arguments or printed. The archive is AES-256 encrypted and created with 0600 permissions. Delete the transfer archive after a successful import. See docs/architecture.md for how import handles naming conflicts and validates accounts before writing anything.

How it works

The short version: OpenCode keeps all of its provider credentials in a single JSON file, ~/.local/share/opencode/auth.json, and re-reads it fresh on every request; no restart is required to pick up a change. The entire unit of "which account is active" is one top-level provider key in that file. opencode-swap keeps a copy of each account's record in private storage, and use <provider> <name> atomically replaces that one key.

The interesting part is what happens between switches: OpenCode rotates the access and refresh token in place whenever it refreshes, so a naively cached copy would go stale. opencode-swap captures that rotation back into its own storage every time you switch away from an account, before overwriting it with another. Providers using static API keys do not rotate credentials, but use the same atomic switching path.

Provider support

Same account name may exist under different providers. openai:work and anthropic:work are separate accounts. Provider IDs must match keys in OpenCode's auth.json exactly.

Full details, including the exact OpenCode internals this was reverse engineered from and the switch algorithm's failure-recovery guarantees, are in docs/opencode-auth.md and docs/architecture.md.

Security

Credentials are stored via:

• macOS: the system Keychain, through the pinned /usr/bin/security CLI.
• Linux: atomic chmod 0600 files under a 0700 directory, obfuscated (base64) but not encrypted. This matches OpenCode's filesystem trust boundary without interactive Secret Service unlock prompts. The optional TUI status widget polls account usage, so every secret read must be non-interactive and complete in bounded time. Linux Secret Service cannot guarantee this: an unlocked keyring may prompt again, while a locked or unhealthy D-Bus service can block the CLI indefinitely.
• macOS fallback: the same private-file backend when Keychain is unavailable.

No custom cryptographic protocol. Portable exports use standard WinZip AES-256 implemented by pyzipper; plaintext credentials never touch a temporary file. No plaintext database. Full threat model in docs/security.md. See SECURITY.md to report a vulnerability.

Scope

In scope: standalone CLI, Linux + macOS, OpenCode provider accounts with known safe identity semantics, secure multi-account storage, transactional switching with rollback, backup/recovery, an architecture that doesn't need a rewrite to add provider-specific behavior without changing safe I/O machinery.

Out of scope: load balancing / round-robin, runtime request interception, a local proxy, Windows, unsupported/ambiguous OAuth providers, reimplementing or modifying OpenCode, cloud sync. The core CLI stays standalone and owns credentials and swaps; the optional TUI plugin is a read-only companion that shells out to it rather than a separate GUI.

Documentation

• docs/architecture.md: module map, data flow, the switch algorithm, transaction/rollback design.
• docs/opencode-auth.md: how OpenCode stores provider credentials and refreshes OpenAI credentials.
• docs/provider-support.md: provider matrix, source evidence, live-testing status, and deferred OAuth cases.
• docs/provider-research-prompt.md: safe copy-paste prompt for provider-research issues.
• docs/security.md: threat model, storage mechanism comparison, what's explicitly out of scope.
• docs/testing.md: testing strategy and how to run the suite.
• docs/roadmap.md: what v1 ships and the known gaps.
• docs/releasing.md: how to cut a CLI (PyPI) or TUI plugin (npm) release.
• AGENTS.md: project guide for AI coding agents working in this repo.
• CONTRIBUTING.md: how to set up, test, and submit changes.
• SECURITY.md: how to report a vulnerability.

Development

make python-sync
make python-test          # No network/keychain access required
make doctor

Run make help for all development targets. Direct uv commands remain available when Make is not installed.

See docs/testing.md for what the suite covers and how it keeps real macOS Keychain data and your real auth.json out of the loop, CONTRIBUTING.md for the PR workflow, and AGENTS.md for conventions to follow when changing code here.

License

MIT