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