How to Switch Between Multiple Claude Code Accounts Without Re-Logging In (claude-swap Guide)

If you use Claude Code seriously, you have hit the wall: a usage limit pops up mid-task, and the only “official” way to keep going is to /logout, open a browser, run the OAuth dance again, and pray your session state survives. Do that three times a day and it stops being a minor annoyance — it becomes a tax on your focus.

claude-swap is the open-source CLI that deletes that tax. The short answer is simple: it backs up the OAuth credentials for each of your Claude accounts and swaps them in and out of Claude Code’s credential store on demand. Switching accounts goes from a 60-second browser ritual to a single command — cswap switch.

If you searched for how to switch Claude Code accounts, how to change your Claude account in VS Code or Cursor, using multiple Claude accounts, or getting past Claude Code rate limits without logging out, this is the practical teardown: what it is, why it exists, how it actually works under the hood, how to use it, and — just as importantly — where it falls short.

Install it in one command:

uv tool install claude-swap

That’s the whole setup. Then, with Claude Code already logged into your first account, cswap add captures it; log in as the second account and run cswap add again. From then on, cswap switch rotates between them. Full details in How to use claude-swap, and every flag in the command reference.

TL;DR

• claude-swap (CLI: cswap) lets you keep multiple Claude accounts registered and switch the active one in seconds — no logout, no repeated browser OAuth.
• It works by backing up and restoring Claude Code’s OAuth tokens plus the account section of ~/.claude/.claude.json, using OS-native secure storage (the macOS Keychain) or protected files where a keychain isn’t available.
• The killer use case is dodging usage limits: when one account taps out, cswap switch rotates to the next so you keep working — and cswap auto can make that switch for you before you hit the wall.
• It covers the CLI and the VS Code extension (including VS Code forks like Cursor), because they all read the same on-disk credential store. It does not touch the Claude Desktop app or claude.ai.
• You usually don’t need to restart. On Linux and Windows the new account applies on your next message; on macOS the Keychain cache clears after roughly 30 seconds. Restart only if you want it instantly.
• It is unofficial — an MIT-licensed community project by realiti4, not an Anthropic product. Treat account-juggling as a personal-productivity tool and stay aware of your plan’s terms.

What Is claude-swap?

💡 Key insight: claude-swap doesn’t run multiple Claude sessions at once. It stores the credentials for several accounts and hot-swaps which one Claude Code sees as “logged in.”

claude-swap is a multi-account switcher for Claude Code, built and maintained by the open-source developer realiti4. You register each account once, and from then on you can rotate between them with a single command instead of logging out and back in through the browser. It works with both the Claude Code CLI and the official VS Code extension — and, by extension, VS Code forks like Cursor that install the same extension — because they all read from one credential store on your machine.

Under the surface it does exactly one clever thing well: it treats your OAuth tokens as a swappable asset. Claude Code keeps the active account’s credentials in one place; claude-swap keeps a backup of every account’s credentials in its own vault, and “switching” simply means copying the right backup back into the live store.

The tool installs as a Python package and exposes a cswap command. It’s MIT-licensed, actively developed, and built by the community — not Anthropic. This post is an independent teardown; I don’t maintain the project.

Why It Exists: The Problem It Solves

Claude Code’s value is its flow. You get into a loop with the agent, it’s editing files and running tests, and then — limit reached. On Pro and Max plans there are rolling session and weekly caps, and the moment you hit one, the native fix is brutal to your momentum:

1. /logout out of the current account.
2. Re-authenticate the second account through a browser OAuth redirect.
3. Re-establish your working context and hope nothing got lost.

People run into this constantly because having more than one Claude account is normal now, not exotic:

• A personal account and a separate work or client-billed account.
• Multiple Max subscriptions specifically to extend daily working hours.
• A team setup where different accounts map to different billing buckets.

claude-swap exists because the credentials for all those accounts are just files and keychain entries. There’s no technical reason switching should require a browser round-trip — so the tool removes it. You pay the OAuth cost once per account, and every switch after that is instant.

The other escape hatch when you’re genuinely out of cloud capacity is to stop depending on the cloud at all and run a capable coding model locally. But if you’re committed to Claude — and most of us are, for good reason — claude-swap is the pragmatic fix that keeps you in the tool you already like.

How claude-swap Works (Under the Hood)

This is where it gets interesting, because the design is refreshingly simple. Claude Code reads its credentials from one location at startup. claude-swap intercepts the backup and restore of that location.

Where the credentials live

The live store is platform-specific, and claude-swap respects each platform’s conventions:

• macOS — the system Keychain, under the service name Claude Code-credentials.
• Linux / WSL — a plaintext file at ~/.claude/.credentials.json.
• Windows — a protected credential store, plus the account section of ~/.claude/.claude.json.

That platform split is also why the switch feels different per OS: a file change is picked up immediately, a Keychain read is cached for a while.

claude-swap keeps its own backups in a vault directory — ~/.local/share/claude-swap/ on Linux and WSL (overridable with the XDG_DATA_HOME environment variable), ~/.claude-swap-backup/ on macOS and Windows — with one slot per account.

claude-swap/
├── credentials/           # per-account credential backups
├── sessions/              # profiles for session mode (cswap run)
├── settings.json          # tool preferences (cswap config)
└── autoswitch_state.json  # cooldown + quarantined accounts

The switch lifecycle

That locking is the part most “swap a config file” hacks get wrong. Because the swap holds Claude Code’s own credential locks, it can never interleave with a token refresh happening at the same moment — so a switch is safe to run while Claude Code is mid-task.

The one platform wrinkle: on macOS, Claude Code caches the Keychain read for about 30 seconds. A running session picks up the new account once that cache expires. On Linux and Windows the credentials live in a file that Claude Code re-reads on change, so the switch applies on your next message. Either way, restarting the CLI or reopening the VS Code extension tab makes it instant.

How To Use claude-swap

Installation

The recommended path is uv, but pipx works just as well:

# Recommended
uv tool install claude-swap

# Or with pipx
pipx install claude-swap

# From source
git clone https://github.com/realiti4/claude-swap
cd claude-swap
uv sync

Upgrades are equally boring (the good kind):

uv tool upgrade claude-swap      # or: pipx upgrade claude-swap
cswap upgrade                    # self-update, auto-detecting your installer

Register your accounts

You add accounts one at a time. Log into the account you want to capture first (via normal Claude Code login), then register it:

# Log into account A in Claude Code, then:
cswap add

# Switch the Claude Code login to account B, then:
cswap add

Each cswap add captures whoever is currently logged in. When a token later expires, log back in with that account and re-run cswap add — it updates the existing slot rather than creating a duplicate.

Switch, list, and check status

cswap switch                # rotate to the next account in sequence
cswap switch 2              # switch to a specific slot number...
cswap switch you@work.com   # ...by email...
cswap switch dev            # ...or by an alias set with: cswap alias 2 dev
cswap list                  # show accounts, 5h/7d usage, and reset times
cswap status                # show which account is active right now
cswap tui                   # interactive dashboard (or just: cswap)

Not sure which account to jump to? cswap switch --strategy best picks the one with the most quota left, and --strategy next-available skips anything currently rate-limited.

Let it switch for you before you hit a limit

cswap auto is the piece that closes the loop. It polls your usage and rotates to a fresher account when the active one nears its 5-hour or 7-day limit — so you find out you were near a wall rather than hitting one:

cswap auto                     # foreground loop, polls every 60s
cswap auto --threshold 80      # switch earlier than the default 90%
cswap auto --once              # single check-and-switch, for cron
cswap auto --dry-run           # log what it would do, never switch

A cooldown plus a hysteresis margin stops it flip-flopping between two accounts hovering at the threshold, and switches take Claude Code’s credential locks, so running it alongside an active session is safe.

Run two accounts at the same time

Session mode launches Claude Code as a specific account in the current terminal only — every other terminal and the VS Code extension stay on your default login:

cswap run 2                  # launch Claude Code as account 2, here only
cswap run 2 -- --resume      # anything after -- is forwarded to claude
cswap run 2 --share-history  # share chat history with this account too
cswap map 2 ~/work/client-app  # bind a directory: bare `cswap run` picks account 2 there

Each account keeps its own chat history by default, and sessions reuse your normal ~/.claude setup — settings, CLAUDE.md, skills, MCP servers.

Headless and CI: register by token

On a server with no browser, you can’t do interactive OAuth. claude-swap lets you register an account directly from a setup token or a managed API key:

cswap add-token sk-ant-oat01-...   # OAuth setup token from: claude setup-token
cswap add-token sk-ant-api03-...   # managed API key
cswap add-token - --slot 3         # read the token from stdin

Move accounts between machines

Export creates a portable .cswap file; import restores it on another machine. This is the answer to “I set all this up on my laptop, now I need it on the work desktop” — you move the registered logins instead of doing the browser OAuth dance once per account per machine:

cswap export backup.cswap             # all accounts
cswap export backup.cswap --account 2 # just one
cswap export backup.cswap --full      # include full config, for same-PC backups
cswap import backup.cswap             # skips accounts that already exist
cswap import backup.cswap --force     # overwrite existing accounts

Two things worth knowing. By default the export carries only each account’s own login — machine-shared MCP and plugin OAuth tokens stay on the source machine, which is usually what you want. And if the imported account is the one you’re already logged in as, activate the imported credentials explicitly with cswap switch N --force; a plain switch to the already-active account is a safe no-op and won’t touch the import.

Command Reference

Every claude-swap command is a subcommand of cswap, and the ten you actually need day to day are add, switch, list, status, auto, run, remove, export, import, and tui. The rest are conveniences you’ll reach for once and then forget about.

Add --json to list, status, or switch when you’re scripting: each emits one machine-readable object on stdout, with human-readable notices kept on stderr.

How Do You Change Your Claude Account in VS Code or Cursor?

You change your Claude account in VS Code or Cursor from a terminal, not from the editor UI: run cswap switch (or cswap switch you@work.com), then close and reopen the Claude Code tab. There is no account picker inside the extension, and there doesn’t need to be — the extension and the CLI read the same credential store, so a switch made anywhere on the machine applies everywhere on it.

The reason this trips people up is that the extension looks like a self-contained app. It isn’t. Anthropic’s own docs are explicit that Claude Code settings in ~/.claude/settings.json are shared between the extension and the CLI, and the login sits in the same place. Change the login underneath and the extension follows.

The exact sequence:

Cursor, Windsurf, and other VS Code forks work the same way. Anthropic ships the Claude Code extension for Cursor directly and notes it installs in other forks via the Open VSX registry; because every one of them uses the same on-disk login, cswap switch covers all of them at once. If your fork can’t install the extension at all, install the standalone CLI and run claude in its integrated terminal — that path is unaffected.

The one thing that does not work: expecting the extension’s own Logout command (in the Command Palette) to give you a switcher. It signs you out, and then you’re back to browser OAuth — which is the exact cost claude-swap exists to remove.

How Do You Log Out of Claude Code and Change Users?

To change users the built-in way, type /logout in Claude Code, then /login and authenticate as the other account in the browser — and that is the whole official story, because Claude Code has no concept of a second registered user. In the VS Code extension the equivalent is the Logout command in the Command Palette; the sign-in screen reappears afterwards.

That flow is fine once a week and miserable three times a day, which is the entire reason tools like claude-swap exist. The comparison is stark:

Worth being precise about what claude-swap does and doesn’t replace: it does not log you out. Your registered accounts all stay authenticated in its vault, and it changes which one Claude Code currently sees. If you genuinely want to end a session — a shared machine, an offboarding, a client handover — use /logout, and use cswap remove to unregister the account from claude-swap as well.

Can You Use Multiple Claude Accounts on One Machine?

Yes — nothing in Claude Code stops you having several Claude accounts on one machine; the limitation is that only one of them can be the active login at a time, which is precisely the gap claude-swap fills. With cswap run you can go a step further and have two accounts working in parallel in different terminals.

The part people are actually asking about is usually permission, not mechanics, so here is the honest read. Anthropic’s Consumer Terms are explicit about sharing: “You may not share your Account login information, Anthropic API key, or Account credentials with anyone else. You also may not make your Account available to anyone else.” They do not set out a cap on how many accounts one person may hold. So:

The mechanics are unremarkable: register each account once with cswap add, and from then on cswap list shows all of them side by side with their usage and reset times. Nothing is pooled or merged — you are just spared the browser round-trip when you move between logins you already pay for.

Does Claude Desktop Share Accounts With Claude Code?

No — the Claude Desktop app and Claude Code keep separate logins, and claude-swap does not touch Claude Desktop at all. claude-swap is scoped to Claude Code’s credential store: the CLI and the VS Code extension. The desktop app signs into claude.ai with its own session, so switching accounts in one has no effect on the other.

That means there is no claude-swap-shaped answer for “Claude Desktop account switcher.” What you actually have available:

If you use both surfaces heavily, the practical setup is to leave Claude Desktop signed into whichever account you treat as primary and let claude-swap rotate Claude Code underneath it. They will drift out of sync, and for most workflows that is harmless — the desktop app is for conversation, Claude Code is where the rate limits bite.

When To Use It (and When Not To)

What claude-swap Still Misses

No hype here — this is a small, focused tool, and its gaps are real. Two of them closed during 2026: auto-rotation now exists as cswap auto, and a restart after switching is usually no longer required. What’s left is worth weighing honestly before you adopt it.

💡 Key insight: The remaining gaps are all about scope, not capability. claude-swap now switches, monitors, and even auto-rotates competently — inside Claude Code. Everything it can’t do is a thing that lives somewhere else: the desktop app, the browser, another person’s machine.

Best Practices

How Does claude-swap Compare To ccswitch And The Other Account Switchers?

claude-swap is the most feature-complete of the community Claude Code account switchers — it’s the one with usage-aware auto-rotation, parallel session mode, and a live dashboard — but every tool in this space, including the alternatives, does the same core trick: back up each account’s OAuth credentials and swap the active set. Which one suits you comes down to how much you want beyond that swap.

First, the approaches themselves:

Other community account switchers

If you arrived here searching for a tool by a different name, you probably want one of these. They are separate projects by separate authors, all solving the same problem with different surface areas:

Their names collide badly in search — “cc switch”, “ccswitch”, “cc-account-switcher” and “cc-switch” are four different projects, and at least one cc-switch is a model and provider switcher rather than an account switcher. Check the repository before you install: if it talks about API endpoints and providers, it is not solving the multi-account subscription problem.

I’d pick claude-swap when you want usage visibility and automatic rotation, a keychain-only CLI when you want the smallest possible dependency, and the menu bar app when you never want to open a terminal to switch. None of them is an Anthropic product, and all of them depend on Claude Code’s internal credential layout staying put.

FAQ

Final Take

claude-swap is the kind of tool that shouldn’t need to exist — and that’s exactly why it’s good. Anthropic gives you a credential store and a login flow; claude-swap notices that “switching accounts” is really just “swap two files and a keychain entry,” and turns a 60-second browser ritual into one command.

It’s not magic. It only covers Claude Code, it centralizes real OAuth tokens on your machine, and it lives or dies by an internal credential layout Anthropic could change tomorrow — so it’s a personal-productivity tool, not an enterprise credential platform. Know those edges and they won’t surprise you. The two complaints in the original version of this post, that it wouldn’t rotate on its own and that every swap needed a restart, have both since been fixed upstream.

But if you live in Claude Code and bounce between accounts more than once a day, the math is obvious: pay the OAuth cost once per account, then never pay it again. For a free, MIT-licensed CLI, that’s a remarkably good trade.

If you found this useful, read how Anthropic Code Review fits into Claude Code next — it’s the clearest signal of where the rest of the Claude Code workflow is heading, beyond the account you happen to be logged into.

Sources

• claude-swap on GitHub — the project itself, by realiti4
• Anthropic: Claude Code
• Claude Code Docs
• Use Claude Code in VS Code — extension setup, Cursor and VS Code forks, the Logout command
• Anthropic Consumer Terms of Service — account sharing clause
• uv — Python package and project manager
• ccswitch, cc-account-switcher, CCSwitcher — alternative community switchers

Written for umesh-malik.com — no-fluff technical writing on AI, Web Dev, and Engineering.