convez.ai
Plugin
x0c

subswap

x0c/subswap

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude, Codex and ChatGPT account switcher with quota-aware auto-swap

Instalação

$npx convez-ai x0c/subswap

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
6
Acompanhando
0
Saúde
57%
Último commit
há 3 dias
Versão
v1.17.1
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

subswap - Claude, Codex and ChatGPT account switcher

CI Release

Languages: English | 简体中文 | 日本語 | 한국어

subswap is a Rust CLI for managing multiple AI subscription accounts across Claude Code, Anthropic Claude, OpenAI Codex CLI, and ChatGPT. It imports local login state, stores credentials in the OS keyring, checks quota windows, and swaps the active account manually or automatically when usage crosses a configurable threshold.

Use it as a Claude account switcher, Codex account manager, ChatGPT quota tracker, or a unified multi-provider subscription swapper.

Platform support: tested and working on macOS and Linux. Windows is not tested.

Features

  • Multi-account swap for Claude Code and Codex CLI: flip the active account without re-logging-in.
  • Claude Code custom API endpoints: add DeepSeek or another Anthropic-compatible endpoint through an interactive terminal wizard, then swap to and from it like any Claude account.
  • Account-isolated parallel environments: run different accounts simultaneously in different terminals without touching the global active account — subswap run, shell, and env project credentials into a private directory and set the right env vars for the native CLI.
  • Quota-aware status: view provider quota windows such as Claude 5h / 7d usage and Codex / ChatGPT usage data when available.
  • Automatic account swap: a background daemon moves away from an account once usage crosses the configured threshold, and re-evaluates on every quota update to always pick the best available account.
  • Auto-swap toggle: subswap autoswap on/off enables or disables automatic switching without touching the config file.
  • Settle-grace after manual swap: after you manually pick an account, the daemon holds off for a grace period before auto-swapping away, so your intent isn't immediately overridden.
  • Network-independent manual swap: subswap swap still works when quota APIs fail, tokens expire, or the network is down.
  • Quota result cache with stale fallback: cached quota results are served while a fresh fetch is in flight, so the status screen is always responsive.
  • File-backed credential storage: tokens are kept in an owner-only (0600) file under the app data directory, so reading quota never triggers OS keychain prompts. Credentials from older keyring-based installs are migrated automatically on first run.
  • Provider-based architecture: Claude / Anthropic and Codex / ChatGPT are separate crates, so new AI providers can be added without changing core policy.

Supported clients

ProviderLocal clientWhat subswap manages
Claude / AnthropicClaude Code (~/.claude)OAuth credentials, custom API endpoints, active account files, 5h / 7d quota, token keepalive
Codex / ChatGPTCodex CLI (~/.codex)auth.json passthrough, active account files, ChatGPT usage lookup

Common use cases

  • Switch between multiple Claude Pro, Claude Max, ChatGPT Plus, or ChatGPT Team seats.
  • Keep a backup AI subscription ready when the current account reaches its usage limit.
  • Run two accounts in separate terminals at the same time without interfering with each other.
  • Check usage across accounts before starting a long coding session.
  • Consolidate Claude and ChatGPT account switching into one CLI.

Status

MilestoneScopeState
M1workspace + core trait/model + minimal CLIdone
M2Claude provider: keyring-backed swap, 5h/7d quota, best-effort token refreshdone
M3Codex provider: opaque auth.json passthrough, atomic write, tolerant wham/usage parsingdone
M4subswapd daemon: periodic poll + auto-swap + Claude token keepalive + zero-config auto-spawndone
M5account-isolated run environments, auto-swap toggle, quota cache, settle-gracedone

Why

If you pay for more than one AI subscription, you probably hit one of:

  • you ran out on Claude Pro and want to fall back to ChatGPT without re-logging-in;
  • you keep two ChatGPT seats and want a one-liner to flip the active one;
  • you want two accounts running in parallel in different terminals without conflict;
  • you want to see how much of each window (5h / 7d) is left across accounts.

subswap stores each account's credentials in an owner-only file under its data directory (migrating any existing OS-keyring entries on first run), swaps the active one atomically across all clients that read the same on-disk credential file, and never blocks swap on the network — quota lookups are advisory.

Install

With Homebrew:

brew install x0c/tap/subswap

Or tap first, then install by name:

brew tap x0c/tap
brew install subswap

From source, requires Rust 1.80+.

git clone https://github.com/x0c/subswap
cd subswap
cargo install --path crates/cli
subswap --help

You can also install directly from Git:

cargo install --git https://github.com/x0c/subswap --path crates/cli

Quick start

# default: sync local active accounts, fetch quotas, auto-swap if past threshold,
# then print a one-screen status. Run this whenever you want to know what's up.
subswap

# manually swap to a specific account (escape hatch — never depends on the network)
subswap swap alice@example.com
# disambiguate when the same id exists under multiple providers:
subswap swap claude/alice@example.com

# interactively add DeepSeek or another Claude Code compatible API endpoint
subswap add-api
# custom API endpoints are manual-only and never participate in auto-swap
subswap swap deepseek

# run an account in an isolated environment without touching the global active account
subswap run codex bob@example.com -- --version   # launch codex with bob's account
subswap shell alice@example.com                  # open an isolated sub-shell
eval "$(subswap env codex/bob@example.com)"      # export env vars into the current shell

# enable or disable automatic account switching
subswap autoswap on
subswap autoswap off

# remove an account from the registry and the keyring
subswap rm alice@example.com

# environment self-check (client files, keyring, config dirs)
subswap doctor

Accounts are picked up automatically from ~/.claude and ~/.codex the first time you run subswap, as long as you have logged into Claude Code / Codex CLI at least once.

The first subswap invocation also spawns a detached background daemon on Unix platforms except macOS. The daemon polls quotas, auto-swaps in the background, and keeps Claude OAuth tokens fresh so a long-idle account doesn't 401 the moment you swap to it. macOS requires explicit opt-in because detached Keychain access can trigger extra authorization prompts: export SUBSWAP_AUTO_DAEMON=1 to enable auto-start there. The daemon is single-instance (file-locked) and harmless to kill: pkill -f 'subswap __daemon' or pkill subswapd. To opt out entirely, export SUBSWAP_NO_DAEMON=1.

Account-isolated environments

subswap run / shell / env let you use different accounts in parallel across terminals without changing the global active account. Credentials are projected into a private directory and the native CLI is pointed there via environment variables (CODEX_HOME for Codex; CLAUDE_CONFIG_DIR and CLAUDE_SECURESTORAGE_CONFIG_DIR on macOS for Claude).

subswap run codex 6 -- --version       # run codex as account #6 in isolation
subswap run claude alice@x.com         # run claude as alice in isolation
subswap shell 3                         # open a sub-shell isolated to account #3
eval "$(subswap env codex/bob@x.com)"  # temporarily point current shell at a codex account
  • Exclusive lock: only one isolated session per account at a time — concurrent sessions would race on refresh token rotation.
  • Global active warning: starting an isolated session for the current global active account prints a warning, since a non-isolated client may be using it simultaneously and could invalidate the refresh token.

Design invariants

These are load-bearing and worth knowing before contributing:

  1. swap never depends on quota lookups. If the API is down, the keyring is unreachable, or the token is expired, manual swap must still flip the active account.
  2. Secrets stay out of registry metadata and snapshots are owner-only. OAuth/API secrets live in the owner-only credential store. While a custom API is active, Claude Code also requires its API key in ~/.claude/settings.json; subswap preserves and restores that file atomically.
  3. Swap is atomic and rollback-able. Each activate writes a snapshot under state_dir/snapshots/<ts>/ before touching anything; any failed write rolls back.
  4. Adding a provider = adding a crates/providers/<id> crate + one line in cli/src/main.rs::AppContext::build(). No provider-specific logic in core.
  5. Auto-swap threshold is centralized and configurable. The compiled default lives in crates/core/src/defaults.rs, and runtime config can override it.

More: docs/ (Chinese — internal collaboration docs).

Comparison

ToolFocusDifference
single-provider account switchersone upstream at a timesubswap supports Claude and Codex / ChatGPT behind one provider abstraction
quota dashboardsusage visibility onlysubswap can also activate another local account when a quota window is full
manual login/logoutone account at a timesubswap keeps registered accounts in the keyring and swaps active local files atomically

FAQ

Does subswap swap call quota APIs?

No. Manual swap is an escape hatch and never depends on quota lookup. If the upstream API is down or a token is expired, subswap swap claude/alice@example.com still tries to activate that local account.

Do custom API endpoints participate in auto-swap?

No. They are manual-only: subswap never automatically selects one, and auto-swap remains disabled while one is active. Manually swapping back to an OAuth account restores the Claude Code settings that existed before API mode.

Where are tokens stored?

Tokens and refresh tokens live in owner-only credential files under the app data directory. While a custom API is active, Claude Code also requires its API key in ~/.claude/settings.json; subswap keeps that file and switch snapshots owner-only.

Is this only for Claude?

No. The first supported providers are Claude / Anthropic and Codex / ChatGPT. The core crate exposes a Provider trait so future AI subscription providers can be added as separate crates.

Does it work on Windows?

It has not been tested on Windows. macOS and Linux are the primary supported platforms.

GitHub topics

Recommended repository topics after publishing:

claude-code, codex-cli, chatgpt, anthropic, openai, account-switcher, quota-tracker, ai-tools, rust-cli, keyring, automation

Layout

crates/
  core/                # data model, Provider trait, CredentialStore, paths
  cli/                 # `subswap` binary
  daemon/              # `subswapd` binary
  providers/
    claude/            # Claude / Anthropic provider
    codex/             # Codex / ChatGPT provider

Contributing

Issues and PRs welcome. Notes:

  • internal docs in docs/ and AGENTS.md are in Chinese; code comments are in Chinese; everything user-visible (CLI text, error messages, tracing logs, crate descriptions) is in English.
  • run cargo check --workspace and cargo test --workspace before opening a PR.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados