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

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

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

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 --no-share-history  # keep this account's chat history to itself

Sessions use your normal ~/.claude setup (settings, CLAUDE.md, skills, MCP servers, etc.) and share its chat history, so a conversation started under one account shows up in --resume under the others.

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

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.

If the refresh token itself has died (auto-switch quarantines and reports such an account), 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 (a stale export can carry an already-superseded token).

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                  # Remove an account
cswap disable 2                 # Hold an account out of auto-rotation (keeps its login)
cswap enable 2                  # Return a disabled account to rotation
cswap threshold 2 85            # Switch away from account 2 at 85%, not the global default
cswap threshold 2 --unset       # Return account 2 to the global default
cswap threshold                 # Show the global default and every per-account override
cswap priority 2 100            # Use account 2 before lower tiers (priority-consume-first strategy)
cswap priority 2 --unset        # Return account 2 to tier 0
cswap priority                  # Show every account's tier
cswap alias 2 dev               # Give an account a short alias (usable anywhere NUM|EMAIL is)
cswap alias 2 --unset           # Remove an account's alias
cswap alias                     # List all aliases
cswap move 2 1                  # Assign an account to a slot (relocates to an empty slot, swaps if taken)
cswap swap 2 3                  # Exchange two accounts' slot numbers
cswap unclaimed                 # List stashed credential entries (slot + why they were stashed)
cswap unclaimed --purge ID      # Drop one (deletes its bytes; recover with /login + `cswap add`)
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 only the account-specific Claude login when you switch accounts; live account-independent OAuth state (such as MCP server logins) is preserved instead of being overwritten by a slot's older snapshot
• 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 until you re-add them
• Usage numbers refresh every few minutes — faster for an account being used or close to switching, slower for idle ones — keeping cswap comfortably inside Anthropic's rate limits however many dashboards you keep open on a machine. An age note like · 6m ago just means the next scheduled check hasn't come yet, not that something is stuck.
• The plan shown after each slot (· Ultra, · Pro, · Team) comes from your account profile and refreshes every six hours, independently of usage; a subscription that has lapsed shows as a highlighted Free.

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)

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

cswap menubar --service-status      # running? pid? starts at login? auto-switch on?
cswap menubar --auto-switch         # turn auto-switch on (--no-auto-switch: off)
cswap menubar --uninstall-service   # stop it and remove the LaunchAgent
cswap menubar --foreground          # run attached to this terminal, for debugging

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 set autoswitch.weeklyThreshold 97  # own switch line for the 7-day/per-model windows
cswap config set autoswitch.model Fable   # per-model switching (see "auto"); Fable,Opus for several
cswap config set run.shareHistory false   # each account keeps its own chat history (see "run")
cswap config set updates.check false      # no daily PyPI lookup for the "newer version" hint
cswap config set usage.headerProbe true   # opt in: setup-token usage via a 1-token request (see "add-token")
cswap config set usage.fableProbe true    # opt in: also their Fable weekly limit, via a 1-token Fable request
cswap config unset autoswitch.threshold   # back to the default
cswap config path                         # where settings.json lives

Backup and migration

Move account data between machines or back it up:

cswap export backup.cswap                    # All accounts to a file
cswap export backup.cswap --account 2        # One account
cswap export backup.cswap --full             # Include full ~/.claude.json and credential object (same-PC backup)
cswap import backup.cswap                    # Skips accounts that already exist
cswap import backup.cswap --force            # Overwrite existing

The export file is plaintext JSON and, by default, carries only each account's own login — machine-shared MCP/plugin OAuth tokens and the device token stay on the source machine (--full keeps everything, for same-PC backups). If you need encryption, pipe through your tool of choice (e.g. cswap export - | gpg -c > backup.gpg).

If an imported account is the one you're currently logged in as, activate the imported credentials with cswap switch N --force (a plain switch to the current account is a safe no-op and won't touch the import).

Share usage readings between machines

Machines that hold the same accounts can end up sharing one usage-endpoint rate limit, so their polling adds up (this is the limit on how often usage can be read, not your subscription quota). import-usage lets one machine poll and hand its readings to the others:

cswap list --json | ssh laptop cswap import-usage - --hold 600

JSON output for scripting

Add --json to list, status, or switch to emit a single machine-readable JSON object on stdout (human-readable notices go to stderr). Useful for scripting auto-swap and quota tracking.

cswap list --json                   # all accounts with usage/quota
cswap status --json                 # current active account
cswap switch --strategy best --json # switch, then report the result
cswap switch 2 --json

{
  "schemaVersion": 1,
  "activeAccountNumber": 2,
  "accounts": [
    { "number": 2, "email": "you@example.com", "active": true, "usageStatus": "ok",
      "usage": { "fiveHour": { "pct": 25.0, "resetsAt": "2026-06-22T23:29:59Z" },
                 "sevenDay": { "pct": 16.0, "resetsAt": "2026-06-26T17:59:59Z" } } }
  ]
}

cswap auto --json emits an event stream instead — one JSON object per line ({"schemaVersion":1,"event":"switch","ts":…, …} with kinds like poll, switch, no-switch, account-quarantined, all-exhausted, error). The contract is additive: new kinds and fields may appear, so scripts should ignore unknown ones.

Every optional field (usage age, last-known usage, fetch errors, pace, login expiry, …) is listed in docs/json-output.md.

Add an account from a raw token or API key

Register a long-lived setup-token (from claude setup-token) or a Console API key (sk-ant-api03-... workspace key, sk-ant-usr-... personal key, or a service-account key) directly, without the browser login — useful on headless servers or when receiving a token from another machine. The token type is auto-detected:

cswap add-token sk-ant-oat01-...             # OAuth setup-token
cswap add-token sk-ant-api03-...             # API key (any Console key family)
cswap add-token sk-ant-oat01-... --slot 3
cswap add-token - --slot 3                   # read token from stdin
cswap add-token --email user@example.com     # optional label override

--email is optional; omitted values use setup-token-{slot}@token.local (or api-key-{slot}@token.local for API keys). No Anthropic API calls are made.

Note: Third-party providers configured through ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN are not managed or switched; those exported variables stay in effect after a switch, so unset them to use the swapped account.

Documentation

• docs/auto-switch.md — the exact auto-switch rules: hysteresis margins, landing rules, per-account thresholds and tiers, polling cadence. Read it to find out why it did or didn't switch.
• docs/json-output.md — every field in --json output, including the optional ones. Read it before writing a script against cswap list --json or cswap auto --json.
• docs/menubar.md — how the macOS menu bar runs under launchd: start at login, the wrapper app in /Applications, file locations, upgrades, the Login Items switch. Read it when the icon is missing or the service misbehaves.

cswap --help and cswap <command> --help document every flag.

Uninstall

Remove all data:

cswap purge

Then uninstall the tool:

uv tool uninstall claude-swap
# or
pipx uninstall claude-swap

Requirements

• Python 3.12+
• Claude Code installed and logged in

License

MIT