claude-swap

Multi-account switcher for Claude Code. Easily switch between multiple Claude accounts without logging out, or let it switch for you before you hit a rate limit. Track usage for every account in a live dashboard, and run accounts in parallel. Works with both the Claude Code CLI and the VS Code extension.

Installation

Using uv (recommended)

uv tool install claude-swap

Using pipx

pipx install claude-swap

From source

git clone https://github.com/realiti4/claude-swap.git
cd claude-swap
uv sync
uv run cswap help

Updating

cswap upgrade          # uv/pipx installs on macOS/Linux: auto-detects and upgrades
# or run your installer directly:
uv tool upgrade claude-swap
pipx upgrade claude-swap

Usage

Add your first account

Log into Claude Code with your first account, then:

cswap add

Add more accounts

Log in with another account, then:

cswap add

Do not run /logout first: current Claude Code may revoke the refresh token stored for the account you are leaving.

Switch accounts

Rotate to the next account:

cswap switch

Or switch to a specific account:

cswap switch 2
cswap switch [email protected]
cswap switch dev                # or by alias, once set with `cswap alias 2 dev`

Not sure which one? cswap list is the dashboard — every account's plan, 5-hour and 7-day usage and reset times at a glance:

cswap list

Or let claude-swap auto-pick by remaining quota — cswap switch --strategy best (most quota left) or --strategy next-available (skip rate-limited accounts).

Note: You usually don't need to restart — on Linux/Windows the new account is picked up automatically, and on macOS after the Keychain cache expires. To apply it instantly, restart Claude Code or reopen the VS Code extension tab. See Tips for the per-platform details.

Automatic switching

Let claude-swap watch your usage and switch for you. When the active account's 5-hour or 7-day window reaches the threshold (default 90%), it switches to the account with the most quota left — before you hit the limit, and safe to run while Claude Code is working:

cswap auto                           # foreground loop, polls every 60s
cswap auto --threshold 80            # switch earlier
cswap auto --weekly-threshold 97     # let the weekly window run higher before switching
cswap auto --model Fable             # also switch when the Fable weekly limit is hit
cswap auto --strategy weekly-first   # spend the soonest-expiring weekly quota first
cswap auto --once                    # single check-and-switch, for cron/scripts
cswap auto --dry-run                 # log what it would do, never switch

Strategies (--strategy, or cswap config set autoswitch.strategy):

Strategy	Switches	Lands on
best (default)	when the active account reaches its threshold	the account with the most quota left
weekly-first	same as best	the account whose weekly window resets soonest
consume-first	at the threshold, and earlier whenever an account that resets sooner has room	the account whose weekly window resets soonest
priority-consume-first	whenever a higher-tier account is usable	your highest tier (cswap priority), then the soonest weekly reset

The weekly ones exist because weekly quota left unused at its reset is lost.

Per-account controls

• cswap disable <num|email> holds an account out of rotation: auto-switch, bare cswap switch, and the best / next-available strategies skip it until cswap enable puts it back. It keeps its login and is still a valid explicit cswap switch <num|email> target.
• cswap threshold <num|email> <pct> gives one account its own switch-away line (50–99.9) in place of the global one.
• cswap priority <num|email> <tier> ranks accounts for priority-consume-first: higher tiers (0–1000, default 0) are used first. The other strategies ignore tiers.

Good to know

• Thresholds are switch-away lines, not hard caps. With nothing under its line, or the active account at its limit, auto-switch still lands somewhere rather than stall. priority-consume-first is the exception: it never lands on an account at or over its line, so it holds and keeps polling.
• A cooldown (default 5 min) and a hysteresis margin stop it flip-flopping between accounts near the threshold.
• --weekly-threshold 97 gives the 7-day and per-model windows their own line, so the weekly budget can run higher than the 5-hour window. --threshold, and any per-account threshold, then governs the 5-hour window only.
• --model Fable folds that model's weekly limit into the decision, for when you hit a per-model limit before the account-wide ones. Names are the per-model rows in cswap list (e.g. Fable: 100%), matched case-insensitively.
• Accounts with no 5-hour window (Ultra) are judged on their 7-day and --model windows alone.
• If a usage check fails it keeps using the last-known numbers for a limited time while it retries, and an expired token on an idle machine makes it hold rather than fail over.
• An account whose refresh token has died is quarantined and reported until you re-add it.
• API-key accounts are never rotated onto unless you pass --include-api-key-accounts.

For cron/systemd timers, --once reports the outcome in its exit code (0 switched, 1 error, 2 nothing to do, 3 blocked — no viable target), and --json emits one JSON event per line:

*/5 * * * * cswap auto --once --json >> ~/.cswap-auto.log 2>&1

Defaults like the threshold and cooldown are configurable with cswap config set autoswitch.threshold 80 — flags override them (see Configuration).

The exact rules (margins, landing, polling cadence, tier handling) are in docs/auto-switch.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗