claude-swap: rotate between multiple Claude Code accounts before you hit a rate limit

What claude-swap is and who needs it

claude-swap is a multi-account switcher for Claude Code. It lets you switch between several Claude accounts without logging out, or have it switch for you before you hit a rate limit, track usage for every account in a live dashboard, and run accounts in parallel. It works with both the Claude Code CLI and the VS Code extension.

The people who need this are developers with more than one Claude plan, or a team sharing several, who otherwise lose time when the active account hits its 5-hour or weekly window. Manually logging out and back in is slow and, as the README warns, risky, because current Claude Code may revoke the refresh token of the account you leave. claude-swap exists to make switching a single command and, better, to switch automatically before you notice the limit at all. It is a Python tool distributed on PyPI, so if you only ever use one account it adds nothing you need.

Installing and adding accounts

The recommended install is uv, with pipx as an alternative:

uv tool install claude-swap

pipx install claude-swap

Both expose the tool as cswap (and claude-swap). Adding accounts is deliberately simple: log into Claude Code with an account, then run the add command, and repeat for each account:

cswap add

The README is emphatic about one thing here, and it is the kind of warning worth heeding: do not run /logout first, because current Claude Code may revoke the refresh token stored for the account you are leaving. In other words, claude-swap captures the credentials of your logged-in account, so you add accounts by logging in normally and running cswap add, never by logging out.

Switching and the usage dashboard

Switching is one command, with several targeting options:

cswap switch
cswap switch 2
cswap switch user@example.com

The first rotates to the next account; you can also target a slot number, an email, or an alias set with cswap alias. The dashboard is cswap list, which shows every account's 5-hour and 7-day usage and reset times at a glance. When you would rather not choose, cswap switch --strategy best picks the account with the most quota left, and --strategy next-available skips rate-limited accounts.

The README notes a platform subtlety worth knowing: you usually do not need to restart, because on Linux and Windows the new account is picked up automatically and on macOS after the Keychain cache expires, but to apply a switch instantly you restart Claude Code or reopen the VS Code extension tab. That detail explains the occasional case where a switch seems not to take effect immediately.

Automatic switching before the limit

The feature that makes claude-swap more than a manual switcher is cswap auto, which watches your usage and switches for you when the active account's 5-hour or 7-day window reaches a threshold (90% by default), moving to the account with the most quota left before you hit the limit. It is safe to run while Claude Code is working:

cswap auto
cswap auto --threshold 80
cswap auto --once
cswap auto --dry-run

The design details show real care about not misbehaving. Switches take the same credential locks Claude Code uses, so a swap never collides with a token refresh. A cooldown and a hysteresis margin stop it flip-flopping between two accounts hovering at the threshold. Usage polling is adaptive, so API traffic stays flat no matter how many accounts you manage. And it fails safe: a failed usage check keeps trusting the last-known numbers, and an expired token on an idle machine makes it hold rather than fail over. For cron or systemd, cswap auto --once reports the outcome in its exit code and --json emits one event per line.

Strategies, quarantine and parallel sessions

Two switching strategies cover different goals. best (the default) stays on the current account until it nears its limit, then moves to the one with the most quota. consume-first proactively keeps you on the account whose weekly window resets soonest, on a use-it-or-lose-it logic, so perishable weekly quota is not wasted. You can also fold a per-model weekly limit into the decision with --model, using Anthropic's own display names as shown in cswap list.

claude-swap also handles the messy realities of many accounts. An account whose refresh token has died is quarantined and reported until you re-add or re-import it, and API-key accounts are never rotated onto unless you opt in. You can hold an account out of rotation with cswap disable and restore it with cswap enable. Finally, session mode runs accounts in parallel: cswap run 2 launches Claude Code as account 2 in the current terminal only, leaving every other terminal and the VS Code extension on your default account, so two accounts can work at once.

Safety, licence and maturity

Because the tool stores and swaps account credentials, the natural question is whether it is safe. The honest answer is that it is designed carefully around Claude Code's own mechanisms: it takes the same credential locks Claude Code uses so swaps do not collide with token refreshes, and its explicit warning not to run /logout exists precisely to avoid Claude Code revoking a token. It manages credentials locally; there is no cloud component described. As always, credentials are sensitive, so run it on a machine you trust.

claude-swap is MIT licensed and supports macOS, Windows and Linux with Python 3.12 or newer. pyproject.toml marks it Beta, with the released line at 0.26.0 and a 0.27.0 beta in progress, and the last push was on 2026-09-08. An optional menubar extra adds a macOS menu-bar app, and there is a TUI dashboard as well. The pre-1.0 version means behaviour may still change, so pin a version if you script cswap auto into cron, but for the core job, never losing time to a Claude rate limit again, it is already a focused, well-thought-out tool.

Editorial conclusion

Use claude-swap if you hold more than one Claude plan and keep losing time to rate limits in Claude Code. Install it with uv tool install claude-swap, add each account with cswap add (without running /logout first), watch usage with cswap list, and let cswap auto rotate for you before you hit a limit. It works with the Claude Code CLI and the VS Code extension.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. realiti4/claude-swap on GitHub
5. Releases