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

Switch accounts

Rotate to the next account:

cswap switch

Or switch to a specific account:

cswap switch 2
cswap switch user@example.com

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 --once              # single check-and-switch, for cron/scripts
cswap auto --dry-run           # log what it would do, never switch

• 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; when every account is exhausted it sleeps until the earliest reset.
• Usage polling is adaptive — a couple of accounts per check, busy alternates watched more closely, exhausted ones left alone until they reset — 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 log in with it and re-run cswap add --slot N. 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).

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, etc.), but each account keeps its own chat history. Pass --share-history if you want your accounts to continue the same conversations — a session started under one account shows up in --resume under the others, and nothing already saved is lost. Not supported on Windows yet.

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 status                    # Show current account
cswap add --slot 3              # Add account to a specific slot (prompts before overwrite)
cswap remove 2                  # Remove an account
cswap tui                       # Interactive dashboard (also: bare `cswap`)
cswap watch                     # Dashboard, opened on the live watch page
cswap upgrade                   # Upgrade claude-swap to the latest version
cswap purge                     # Remove all claude-swap data

The original flag spellings (cswap --switch, cswap --list, ...) keep working.

Tips

• Do you need to restart after switching? Usually not. On Linux and Windows, credentials are stored in a file and Claude Code re-reads them whenever that file changes, so the new account takes effect on your next message — no restart needed. On macOS, credentials live in the Keychain, which Claude Code caches for about 30 seconds; a running session picks up the switch once that cache expires. Restart Claude Code (or close and reopen the VS Code extension tab) only if you want the change to apply instantly.
• Continuing sessions after switching: You can keep using the same Claude Code session after switching — run cswap switch in any terminal and carry on. If you'd prefer a clean start, close and reopen Claude Code (or the VS Code extension tab) and use --resume to pick your previous session. Either way, the first message on the new account may use extra usage as its conversation cache rebuilds.

How it works

• Backs up OAuth tokens and config when you add an account
• Swaps credentials when you switch accounts
• Account credentials stored securely using platform-appropriate methods
• Switches (manual and automatic) hold Claude Code's own credential locks while writing, so a swap never interleaves with a token refresh
• Auto-switch freshens a target's token before activating it, and quarantines accounts whose refresh token has died (recover with cswap add --slot N)

Data locations

Session-mode profiles (cswap run) live under the backup directory in sessions/. Tool preferences (settings.json) and auto-switch state (autoswitch_state.json — cooldown and quarantined accounts; delete it to reset) live in the backup directory root.

On Linux/WSL, set XDG_DATA_HOME to override the default location.

Menu bar (macOS)

Needs the menubar extra (macOS only):

uv tool install 'claude-swap[menubar]'   # or: pipx install 'claude-swap[menubar]'
cswap menubar

Shows every account's 5h / 7d / spend usage and switches with a click (specific / rotate / best / next-available), plus the TUI's add / remove / refresh actions. Enable Settings → Auto-switch accounts to run the same engine as cswap auto in the background; it shares the autoswitch.* settings, so the menu bar and CLI stay in sync. Off until you turn it on.

Advanced

Configuration

Tool preferences live in settings.json in the backup root; cswap config reads and edits it with validation, so you never have to find the file or guess valid ranges.

cswap config                              # list effective settings ("(default)" = not set)
cswap config get autoswitch.threshold
cswap config set autoswitch.threshold 80  # validated: rejects out-of-range values loudly
cswap config unset autoswitch.threshold   # back to the default
cswap config path                         # where settings.json lives

cswap config --help lists every key with its valid range and default. Hand-editing the file still works — cswap config is just a safer front door. list and get take --json for scripting.

Backup and migration

Move account data between machines or back it up:

cswap export b