claude-swap keeps a local set of accounts and rotates them before a cap

The purpose is to use several accounts past one account's cap

Read plainly, this is a quota tool. It holds credentials for several Claude Code logins that belong to the same person, tracks the usage window of each, and moves between them so that work continues when the active account's window fills. The threshold is a fraction of the window rather than the limit itself, ninety percent by default, so the switch happens before you are cut off rather than after. It works with both the command line client and the editor extension, and it can run in the foreground, once from a scheduled job, or as a dry run that logs what it would do. Nothing here is hidden in the documentation: the description says automatic rate-limit rotation in as many words, and the modes are named for the strategies they implement.

Credentials are files on macOS and Linux

The dependency list is where the storage decision is recorded. The keyring library carries a Windows-only marker, and the comment attached to it explains why in unusual detail: it is needed solely by a one-time migration that moves credentials out of the keyring and into files, for people upgrading from version 0.10.x or earlier, and macOS and Linux never import it on the normal path. The macOS side has a fallback that shells out to a system security command, and a cleanup sweep that does nothing when the library is absent. Read together, that means on macOS and Linux your session tokens sit in files on disk. The same section also documents that a dead refresh token quarantines an account until you log in with it again, or replace its credentials from an export.

One strategy exists specifically to stop weekly quota expiring

Three strategies are offered, and the third is the one that says the most about the intent. The default stays put until the active account approaches its limit and then moves to whichever account has the most quota left. The alternative, described in the documentation as use-it-or-lose-it, keeps you on whichever account's weekly window resets soonest, moving to it even while it is below the threshold, so that quota which is about to expire does not go to waste. The third is a manual mode that skips accounts already limited. The strategy can be set as a flag or persisted through a configuration command, and the documentation recommends the second for people whose weekly allowance is the binding constraint. That is a considered design, and it is also an explicit optimisation of perishable quota.

A cooldown and a hysteresis margin stop the switching churning

The part of this tool most likely to interest an engineer is the state machine around the decision. There is a cooldown, five minutes by default, so two switches cannot happen back to back. There is also a hysteresis margin, and the rule is precise: a proactive switch only lands on an account that is below the threshold and better than the current one by more than the margin, while a candidate that clears the margin is taken regardless. Two accounts sitting near the line therefore never trade places with each other. When every account is exhausted the loop does not spin at full speed, it falls back to a bounded slow cadence and wakes sooner when a reset is imminent. A test run reports the outcome through its exit code, so a scheduled job can tell switched from nothing to do from blocked, and the documented cron form writes one JSON event per line into a log.

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

Polling adapts per account and slows down after a rate-limit response

Usage checks are not uniform. A couple of accounts are checked per pass, whichever accounts are busy get watched more closely, and exhausted ones are checked roughly every ten minutes, or slower still after a rate-limit response. The stated purpose is that request volume stays flat however many accounts you manage, which is the correct property for a background job that must not itself become a load problem. The same adaptive behaviour is what keeps the tool usable at a dozen accounts instead of a dozen times the traffic. Read the other way, a client that deliberately flattens its request rate and backs off when told to slow down is a client whose behaviour is tuned to avoid looking like a quota loop, and that is a fair thing for a reviewer of either the code or the terms to notice.

Three quota axes exist and only two are used by default

Each account has more than one limit and the tool models three of them. Two are account-wide, a five hour window and a seven day window, and those are the ones that drive switching out of the box. The third is a per-model weekly allowance, and it is ignored unless you name the model, which switches that model's window into the decision so an account is left when one model is exhausted even though its wider windows still have room. Model names are matched against the per-model display names the service itself reports, case-insensitively, and the documentation tells you to read the exact strings out of the account listing rather than guess them. A per-account override also exists for holding an account out of rotation, for instance a work login you do not want automated, while still allowing an explicit switch to it on request.

Session mode hands one terminal to another account and can share history

There is a mode that does not change your default at all. It launches the client as a chosen account for the current terminal only, leaving every other terminal and the editor extension on your normal login, so two accounts can work at once. Anything after a double dash is forwarded to the underlying client, which is how you resume a conversation under the second identity. Two flags on that command deserve attention. One shares your chat history with the account as well, so the same conversation becomes visible to both identities. The other refuses to run at all, rather than quietly starting a plain session, if the account you asked for happens to be your default login. That is a small piece of defensive design, and it is the kind of check that only exists because somebody thought about the failure mode.

The recommended install is a release behind the source

Three installation routes are offered, two of them single commands through uv or pipx, and a third that clones the repository and syncs it.

uv tool install claude-swap

The first is recommended. What you get from either package installer is the newest published release, which is version 0.26.0 from early September. The source tree is further ahead: the project manifest declares a beta of the next minor, 0.27.0b1, and the package metadata classifies the project as beta. So the artifact most people install is behind the working tree by a minor version, and the gap is invisible unless you read the manifest. The release history itself is quick, three releases across two months moving through three minors. The same command carries a self-upgrade path on macOS and Linux that detects which installer was used.

Editorial conclusion

Settle the terms question before anything else. This tool exists so that several accounts you personally pay for can be used past the point where one account's window fills, and whether that is permitted is a question for the service terms and for the account owner, not for this project. If you have decided it is acceptable for your own accounts, three things are worth knowing. Credentials are stored in files on macOS and Linux rather than in the OS keychain, and the tool can export and import them, so treat the machine as holding live session tokens. The switching logic is designed to keep request volume flat and to back off after rate-limit responses, which is good engineering for a background job and also exactly the shape of behaviour a reviewer will look at. And installing the package gets you the newest release, which is behind the version in the source tree.

Frequently asked questions

Official sources

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