opencode-multi-account-core

multi-account-core

Shared core logic for multi-account OpenCode plugins. This package contains ~70% of the logic used by both anthropic-multi-account and codex-multi-account.

What's inside

Module	What it does
AccountStore	Single write path. Serializes all disk mutations through file locking.
AccountManager	In-memory account cache and selection strategies (sticky, round-robin, hybrid). Created via createAccountManagerForProvider.
Executor	Retry loop with account rotation on auth and rate-limit failures. Created via createExecutorForProvider.
Claims	Cross-process coordination via claim files with zombie detection.
Storage	Atomic file read/write with proper-lockfile.
RateLimit	Per-account rate-limit tracking with configurable backoff. Created via createRateLimitTrackerForProvider.
ProactiveRefreshQueue	Background token refresh before expiry. Created via createProactiveRefreshForProvider.
Config	Plugin configuration loading and validation with valibot. Created via createConfigLoaderForProvider.
AuthMigration	One-time import of existing single-account OAuth creds from OpenCode's auth.json.
Adapters	Provider-specific OAuth adapter definitions (endpoints, client IDs, plan labels).
UI	Terminal UI primitives (ANSI formatting, confirm dialogs, select menus).
Utils	Config directory resolution, formatting helpers.

Usage

This package is not intended to be used directly. It is a dependency of the provider-specific plugin packages. Each module exposes a factory function that accepts provider-specific config (endpoints, client IDs, plan labels) and returns a ready-to-use instance.

import { createAccountManagerForProvider } from "opencode-multi-account-core";

export const AccountManager = createAccountManagerForProvider({
  refreshTokenFn: myRefreshToken,
  isTokenExpiredFn: myIsTokenExpired,
});

Architecture

┌─────────────────────────────────────────────────┐
│  anthropic-multi-account / codex-multi-account  │
│  (provider-specific: auth, usage, transforms)   │
├─────────────────────────────────────────────────┤
│          multi-account-core  ← you are here     │
│  AccountStore . AccountManager . Executor        │
│  Claims . Storage . RateLimit . ProactiveRefresh │
│  AuthMigration . Config . Utils . UI . Adapters  │
│  (endpoints, client IDs, plan labels)            │
└─────────────────────────────────────────────────┘

Safety guarantees

• All disk mutations go through AccountStore with file locking
• Atomic writes via temp-file-then-rename
• Concurrent token refresh requests for the same account are deduplicated
• Circuit breaker: an account is only auto-disabled when at least one other remains usable
• Dead process claims are automatically released