realiti4/claude-swap

• Runs safely alongside Claude Code: switches take the same credential locks Claude Code uses, so a swap never collides with a token refresh.
• A cooldown (default 5 min) and a hysteresis margin stop it flip-flopping near the threshold: a proactive switch only lands on an account that's below the threshold and better than the current one by the margin — a candidate that clears the margin is always taken, but two accounts hovering at the line never ping-pong. When every account is exhausted it keeps checking on a bounded slow cadence, waking sooner for an imminent reset.
• Strategies (--strategy, or cswap config set autoswitch.strategy): best (default) stays put until the active account nears its limit, then moves to the account with the most quota left. consume-first proactively keeps you on the account whose weekly window resets soonest — use-it-or-lose-it — switching to a sooner-resetting account (with room to spare) even below the threshold, so perishable weekly quota isn't wasted.
• Usage polling is adaptive — a couple of accounts per check, busy alternates watched more closely, and exhausted ones checked about every ten minutes (or slower after 429s) — so API traffic stays flat no matter how many accounts you manage.
• It fails safe: if a usage check errors it keeps trusting the last-known numbers while retries back off, and an expired token on an idle machine makes it hold rather than fail over (Claude Code refreshes the token on your next message).
• An account whose refresh token has died is quarantined and reported until you either 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 (--force is still required to replace other existing accounts; note a stale export can carry an already-superseded token). API-key accounts are never rotated onto unless you pass --include-api-key-accounts.
• To hold an account out of rotation yourself — a work account you don't want touched, one you're resting — run cswap disable <num|email>; cswap enable <num|email> puts it back. Disabled accounts are skipped by auto-switch, bare cswap switch, and the best / next-available strategies, but stay fully managed and remain a valid explicit cswap switch <num|email> target. They show a (disabled) marker in cswap list, in the TUI, and in the menu bar — both of which also let you toggle the state in place (TUI: menu → Disable / enable account…; menu bar: Disable / enable account).
• By default only the account-wide 5h/7d windows drive switching. If you work on one model and hit its weekly per-model limit first (e.g. Fable), add --model Fable (or cswap config set autoswitch.model Fable) to fold that model's window into the decision, so it switches off an account whose model quota is spent even while its 5h/7d windows still have room.
  • Model names are Anthropic's own per-model display_names, matched case-insensitively. The exact strings for your accounts are the per-model rows in cswap list (e.g. a line reading Fable: 100%).

For cron/systemd timers, --once reports the outcome in its exit code (0 switched, 1 error, 2 nothing to do, 3 blocked — no viable target), and --json emits one JSON event per line:

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

Defaults like the threshold and cooldown are configurable with cswap config set autoswitch.threshold 80 — flags override them (see Configuration).

• With --share-history, a session started under one account shows up in --resume under the others, and nothing already saved is lost.
• User-scope MCP servers (claude mcp add -s user) are mirrored from your default profile on every launch — manage them there; changes made inside a session don't persist. Definitions are copied as-is (including inline env/headers values), but MCP OAuth logins are not — HTTP servers may ask you to authenticate once per profile via /mcp.
• --no-share turns sharing off and removes the mirrored MCP config (profiles that never mirrored are left alone).

Bind a directory to an account, and a bare cswap run there launches that account in session mode — e.g. work account in work repos, personal elsewhere:

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

Subfolders inherit the nearest mapped ancestor. In an unmapped directory, cswap run just launches plain claude with your default login. Mappings are per-machine (not part of cswap export) and are cleaned up when their account is removed.

Needs the menubar extra (macOS only):

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

Shows every account's 5h / 7d / spend usage and switches with a click (specific / rotate / best / next-available), plus the TUI's add / disable-enable / remove / refresh actions. Enable Settings → Auto-switch accounts to run the same engine as cswap auto in the background; it shares the autoswitch.* settings, so the menu bar and CLI stay in sync. Off until you turn it on.

Keep it running without a terminal. cswap menubar runs in the foreground, so the status item dies with the terminal that started it and does not come back after a reboot. --install-service hands it to launchd instead — starts at login, restarts on crash, no .app bundle:

cswap menubar --install-service     # start now, and at every login
cswap menubar --service-status      # installed? loaded? pid?
cswap menubar --uninstall-service   # stop it and remove the plist

The agent lives at ~/Library/LaunchAgents/com.cswap.menubar.plist and logs to ~/Library/Logs/com.cswap.menubar.{log,err}. It pins the cswap console script, whose path survives an upgrade — but the running process keeps the old build until it restarts, so after cswap upgrade either re-run --install-service or launchctl kickstart -k gui/$(id -u)/com.cswap.menubar.

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.model Fable   # per-model switching (see "auto"); Fable,Opus for several
cswap config unset autoswitch.threshold   # back to the default
cswap config path                         # where settings.json lives

cswap config --help lists every key with its valid range and default. Hand-editing the file still works — cswap config is just a safer front door. list and get take --json for scripting.

The input is cswap list --json output. Each row with usageStatus: "ok" is matched to a local account by email and organization, and adopted when it is newer than the reading already stored. Its age comes from usageAgeSeconds, so the two machines' clocks never have to agree; a script that delays the hand-over should add the delay to that field. --hold SECONDS keeps every collector on the receiving machine (list, status, auto, the dashboard, the menu bar) from fetching those accounts for that long, and the held reading stays trusted for switch decisions meanwhile. A hold never runs past the reading's earliest window reset (per-model windows included), nor past an hour after the reading was taken. Renew it with each hand-over, or lift it early with --hold 0; when it lapses, the machine goes back to fetching for itself.

{
  "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" } } }
  ]
}

Every payload carries a schemaVersion (currently 1); on a handled error stdout is {"schemaVersion":1,"error":{...}} with a non-zero exit code. --switch/--switch-to report {"switched": true|false, "from": …, "to": …, "reason": …}.

Usage is served from a per-account cache: when the usage API is briefly unreachable, the last-known numbers are shown instead of nothing (the human view marks them with their age, e.g. · 2m ago). Rows with decision-trusted usage carry additive usageFetchedAt/usageAgeSeconds fields telling you how old the measurement is. Whenever usage is null but a last-known measurement exists — data too old to drive a decision (usageStatus stays unavailable), or a row in a non-ok state such as token_expired — additive lastGoodUsage/lastGoodFetchedAt/lastGoodAgeSeconds fields preserve the human display without making the account actionable. When usage is null and nothing else explains it (usageStatus is unavailable), an additive usageError names the last fetch failure by kind (e.g. http-429, timeout) and, while the cache is backing off from it, usageRetryAt gives the time of the next attempt. These fields apply to list rows and the managed active row from status --json. An account held out of rotation with cswap disable carries an additive "disabled": true on its row (absent otherwise).

A row carries an additive loginExpiresAt (ISO-8601 UTC) when the stored login records when its refresh token expires, which is the moment the slot will need a fresh /login and cswap add --slot N; a script can warn a few days ahead instead of discovering relogin_required. Absent when Claude Code recorded no such date for that login.

An account row also carries an additive alias field once one is set with cswap alias (e.g. "alias": "dev"); accounts without one simply omit the key.

Weekly windows (sevenDay and per-model scoped entries — never fiveHour) additively carry pace fields once the week is ~a day old: expectedPct (where usage would sit if spread evenly across the week) and aheadOfPace (true when meaningfully above that — the same signal the human views show as an (ahead)/(ahead of pace) marker). projectedExhaustionAt/willLastToReset extrapolate the current rate into an ETA to 100% and a yes/no "will it last to the reset"; they stay --json-only since a linear projection is too rough to present as fact in the UI.