realiti4 /claude-swap

Switch between multiple Claude Code accounts, with automatic rate-limit rotation, usage dashboard, and parallel sessions

★ 4,728⑂ 514👁 11⑃ 403● 182▤ 64
PythonMITCreated 2026-01-11
Download: v1.1.0v1.1.0 ↓1.1.02026-11-12
+17
Daily
4,728
stars
514
forks
11
watchers
403
prs
182
issues
64
releases

README

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)

bash
uv tool install claude-swap


 Using pipx

bash
pipx install claude-swap


 From source

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


 Updating

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

bash
cswap add


 Add more accounts

Log in with another account, then:

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

bash
cswap switch


Or switch to a specific account:

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

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

bash
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, per-account controls & behavior

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 res

Top issues

Latest release

v1.1.0 v1.1.0 2026-11-12
Highlights

A fixes release — stored logins that survive more switches, custom profiles on macOS, and consume-first landings with room.

- Stored logins are harder to lose. A switch could save unrelated live credentials over a slot's login or API key (384, fixes 383), and a login that was refreshed while ~/.claude.json named another account left its slot with a dead token (523). Both are kept now.
- Custom profiles on macOS. With CLAUDE_CONFIG_DIR set, a switch could report success and change nothing (357, fixes 206), or, when it pointed at ~/.claude itself, delete the login made without the v

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON