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 user@example.com
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 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 --model Fable       # also switch when the Fable weekly limit is hit
cswap auto --once              # single check-and-switch, for cron/scripts
cswap auto --dry-run           # log what it would do, never switch
cswap auto --strategy consume-first   # burn the soonest-resetting account first

• Runs safely alongside Claude Code: switches take the same credential locks Claude Code uses, so a swap never collides with a token refresh.
• A cooldown (default 5 min) and a hysteresis margin stop it flip-flopping near the threshold: a proactive switch only lands on an account that's below the threshold and better than the current one by the margin — a candidate that clears the margin is always taken, but two accounts hovering at the line never ping-pong. When every account is exhausted it keeps checking on a bounded slow cadence, waking sooner for an imminent reset.
• Strategies (--strategy, or cswap config set autoswitch.strategy): best (default) stays put until the active account nears its limit, then moves to the account with the most quota left. consume-first proactively keeps you on the account whose weekly window resets soonest — use-it-or-lose-it — switching to a sooner-resetting account (with room to spare) even below the threshold, so perishable weekly quota isn't wasted.
• Usage polling is adaptive — a couple of accounts per check, busy alternates watched more closely, and exhausted ones checked about every ten minutes (or slower after 429s) — so API traffic stays flat no matter how many accounts you manage.
• It fails safe: if a usage check errors it keeps trusting the last-known numbers while retries back off, and an expired token on an idle machine makes it hold rather than fail over (Claude Code refreshes the token on your next message).
• An account whose refresh token has died is quarantined and reported until you either log in with it and re-run cswap add --slot N, or replace its stored credentials from a known-good export — a plain cswap import backup.cswap replaces dead-token slots on its own (--force is still required to replace other existing accounts; note a stale export can carry an already-superseded token). API-key accounts are never rotated onto unless you pass --include-api-key-accounts.
• To hold an account out of rotation yourself — a work account you don't want touched, one you're resting — run cswap disable <num|email>; cswap enable <num|email> puts it back. Disabled accounts are skipped by auto-switch, bare cswap switch, and the best / next-available strategies, but stay fully managed and remain a valid explicit cswap switch <num|email> target. They show a (disabled) marker in cswap list, in the TUI, and in the menu bar — both of which also let you toggle the state in place (TUI: menu → Disable / enable account…; menu bar: Disable / enable account).
• By default only the account-wide 5h/7d windows drive switching. If you work on one model and hit its weekly per-model limit first (e.g. Fable), add --model Fable (or cswap config set autoswitch.model Fable) to fold that model's window into the decision, so it switches off an account whose model quota is spent even while its 5h/7d windows still have room.
  • Model names are Anthropic's own per-model display_names, matched case-insensitively. The exact strings for your accounts are the per-model rows in cswap list (e.g. a line reading Fable: 100%).

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).

Run multiple accounts at the same time (session mode)

Launch Claude Code as a specific account in the current terminal only — every other terminal and the VS Code extension stay on your default account, so two accounts can work in parallel.

cswap run 2                     # launch Claude Code as account 2, here only
cswap run user@example.com      # by email
cswap run 2 -- --resume         # everything after '--' is forwarded to claude
cswap run 2 --share-history     # share your chat history with this account too

Sessions use your normal ~/.claude setup (settings, CLAUDE.md, skills, MCP servers, etc.), but each account keeps its own chat history — pass --share-history if you want your accounts to continue the same conversations.

• With --share-history, a session started under one account shows up in --resume under the others, and nothing already saved is lost.
• User-scope MCP servers (claude mcp add -s user) are mirrored from your default profile on every launch — manage them there; changes made inside a session don't persist. Definitions are copied as-is (including inline env/headers values), but MCP OAuth logins are not — HTTP servers may ask you to authenticate once per profile via /mcp.
• --no-share turns sharing off and removes the mirrored MCP config (profiles that never mirrored are left alone).

Bind a directory to an account, and a bare cswap run there launches that account in session mode — e.g. work account in work repos, personal elsewhere:

cswap map 2 ~/work/client-app   # map a directory to account 2
cswap map user@example.com      # map the current directory
cswap map                       # list mappings
cswap unmap ~/work/client-app   # remove one (defaults to current directory)

cd ~/work/client-app/src
cswap run                       # → account 2, session mode

Subfolders inherit the nearest mapped ancestor. In an unmapped directory, cswap run just launches plain claude with your default login. Mappings are per-machine (not part of cswap export) and are cleaned up when their account is removed.

Interactive dashboard (TUI)

Run cswap on its own (or cswap tui) for the full-screen dashboard: live usage for every account, switching, and the auto-switcher, all keyboard-driven. cswap watch opens it straight to the live monitor. Works on macOS, Linux, and Windows.

Refresh expired tokens

If an account's token expires, log back into Claude Code with that account and re-run:

cswap add

This will update the stored credentials without creating a duplicate.

Other commands

cswap run 2                     # Run an account in this terminal only (session mode)
cswap auto                      # Auto-switch when nearing rate limits (see above)
cswap config                    # Show or edit settings (see Configuration below)
cswap list                      # Show all accounts with 5h/7d usage and reset times
cswap list --token-status       # Add source-labelled OAuth token diagnostics
cswap status                    # Show current account
cswap add --slot 3              # Add account to a specific slot (prompts before overwrite)
cswap add --alias dev           # Add account and give it a short alias
cswap remove 2                  # R