claude-switch

Bypass Claude Max rate limits — auto-fallback to your API key, auto-revert when the window resets.

Drop-in for Claude Code: keep typing claude, but never wait 5 hours again. Multi-account aware. No new CLI to learn, no aliases, no shell hacks.

macOS · Linux · Windows

npm install -g @sirtheo/claude-switch && claude switch setup

🚀 Install · ✨ Features · 🪟 Profiles · ❓ FAQ · ⭐ Star it

[!NOTE]
🟢 Anthropic issue #24963 — "[FEATURE] Support for multiple accounts / profiles" — is open and unshipped. claude-switch already solves it, today, without modifying the official claude binary. If you found this repo because that issue brought you here: you're in the right place.

In 10 seconds:

• 🪄 You keep typing claude. We install our binary as claude and forward everything to the real Claude Code, except claude switch — that's our dashboard.
• 🔋 Hit your Max 5h cap? claude-switch can fail over to your Anthropic API key automatically and flip back the moment your subscription window resets.
• 🪟 Two accounts at once? Open one terminal as @work, another as @personal, simultaneously. No interference.

⭐ If this resonates — a star helps other Max users find claude-switch before their next 5-hour wall.

😩 The pain

[!TIP]
You have a Claude Max account, a work Claude account, and an Anthropic API key.
Claude Code only knows one at a time.

The official answer is claude logout → browser → claude login → re-auth, every single time. The DIY answers (shell aliases per account, swapping ~/.claude.json by hand, juggling CLAUDE_CONFIG_DIR in .zshrc) all push you off the claude command itself. You stop using your muscle memory. That's the wrong direction.

✅ The fix

claude-switch installs itself as claude. Your muscle memory stays. The original binary is still there, untouched — claude-switch just adds one subcommand: claude switch.

claude                 # works exactly like before — uses your active account
claude switch          # interactive dashboard: pick account, hit ↵, you're in
claude switch work     # one-shot: flip to "work" and you're done

That's the whole API. Nothing else to memorize.

🎯 Project-aware routing — never claude switch again

[!TIP]
The README promised "keep typing claude". With routing, that's now literal: you stop running claude switch entirely. The right account is selected from the directory you're in.

The pain it kills:

"I cd'd into the work repo, typed claude, did half a session, and only then noticed the banner said 🔑 [email protected] — I'd been burning personal quota on a work task."

Two ways to set it up. Pick whichever fits.

A. Per-repo, committable: .claude-switch

Drop a file at the repo root:

{ "match": { "emailDomain": "acme.com" } }

Commit it. From now on, every teammate that cds into this repo and runs claude is auto-routed to whichever of their saved accounts has an @acme.com email. The committed file expresses a constraint (any acme account), not a specific identity — so it works regardless of how each teammate aliased their accounts locally.

The flow:

$ cd ~/work/payroll-service
$ claude "refactor the auth middleware"
🎯 routed to [email protected] via .claude-switch (repo requires @acme.com)
🔑 [email protected]

… session runs as @acme, not @gmail …

Don't have a matching account saved? You get a warning, not a crash — claude falls back to your active account so the session still runs, but the banner makes the misalignment obvious before you waste a turn:

⚠ this repo expects @acme.com — no saved account matches.
  Run: claude switch add. Falling back to active: [email protected]

B. Per-machine, gitignored: claude switch route

For routing rules that are yours, not the team's — global glob → account map:

claude switch route add  '~/work/**'      [email protected]
claude switch route add  '~/clients/foo/**'  foobar          # alias works too
claude switch route list
claude switch route test ~/work/payroll-service              # debug: dry-run
claude switch route remove '~/clients/foo/**'

Stored in ~/.claude/accounts/.routing.json, never committed.

Override knobs

Resolution order

CLAUDE_SWITCH_ACCOUNT env > .claude-switch in the repo (walk-up bounded by .git/) > .routing.json global rules > active account (today's behavior).

When routing has no opinion, behavior is identical to without routing. Don't create either file → nothing changes.

🚀 Install

[!IMPORTANT]
Requires Node.js 20.12+ and Claude Code already installed.

npm install -g @sirtheo/claude-switch
claude switch setup

Then open a new terminal window (the old one has a stale PATH) and verify:

claude switch --version

[!TIP]
Already installed? Since v2.8 claude-switch checks for new versions in the background once a day and offers a one-keypress install on your next interactive claude switch invocation. Or run claude switch update whenever you want — nothing is ever installed without your y.

✨ Features

🪄 Drop-in wrapper — claude is still claude

claude-switch ships its bin as claude. After install, your existing scripts, IDE integrations, shell history, and aliases keep working untouched. We delegate every unknown subcommand straight to the real Claude Code binary. The only new word in your vocabulary is switch.

claude --version       # → real Claude Code, just as before
claude switch          # → our dashboard
claude --as work "…"   # → run a one-shot as a different account

🔁 Sub-second account switching

Type claude switch. Highlight a row. Hit Enter. Done.

• ⚡ Atomic swap of OAuth token + active account in ~/.claude.json
• 🌐 No browser — tokens encrypted at rest in the macOS Keychain (or 0600-permissioned on Linux/Windows)
• 🔄 No logout/login loop — the next session simply starts as the new account

🔋 Rate-limit bypass with auto-revert

Stop losing 5 hours of momentum to the Max cap.

• 🎚 Per-account fallback — each account has its own Anthropic API key
• 🚦 Auto-engage thresholds — e.g. switch to API key at 95% usage
• ↩️ Auto-revert when both 5h and 7d windows clear — no manual flip

📈 Subscription back online (5h:30%, 7d:15%) — switched back to OAuth

🪟 Parallel sessions via isolated profiles

Two accounts. Two terminals. Same machine. Zero interference. Each profile gets its own CLAUDE_CONFIG_DIR, Keychain entry, and session history.

claude switch profile use work       # one terminal
claude switch profile use personal   # another, simultaneously

Or one-step from the menu: Profiles → Open account isolated.

📊 Live usage in the Claude Code statusline

claude switch statusline install

A discreet badge that turns yellow at 75% and red at 90%. You'll never be ambushed by a rate limit again.

⚙️ Configurable smart defaults

Open Settings (g) and tune:

🔐 Security-first by design

[!IMPORTANT]
No telemetry. No analytics. No phone-home.
Only network calls: Anthropic's usage endpoint and the npm registry.

• 📁 Credentials in ~/.claude/accounts/ with 0600 permissions
• 🔑 macOS: OAuth tokens in the login Keychain (same as Claude Code itself)
• 💾 All credential writes are atomic (tmp + rename) — a crash mid-write cannot corrupt your tokens
• 🚫 No postinstall scripts. The real claude binary is never modified.

🎛 Built on Ink — a real TUI

Full React-for-the-terminal UI: focus rings, live updates, hotkeys, in-place re-renders. Tab cycles sections, ↑↓ navigates, single-letter keys (a k f c g p…) are accelerators, ? for inline help.

Plus: tab completion (bash · zsh · fish · powershell), one-shot claude --as <alias> "task", and cross-platform CI on Linux + macOS + Windows × Node 20/22/24.

🪟 Run two Claude accounts in parallel

claude switch work flips the active account on the whole machine — what you want 90% of the time.

The other 10% — Terminal A on @work and Terminal B on @personal at the same time — that's what profiles are for.

⚖️ How it compares

The differentiator isn't "we switch accounts" — CLAUDE_CONFIG_DIR + shell aliases can do that too. It's that claude-switch disappears into claude itself, with safe writes, fallback, profiles and live usage on top, so you're not maintaining your own homemade tool.

❓ FAQ

No. Only network calls are Anthropic's usage endpoint (your subscription quota) and the npm registry (update checks). No telemetry. The source is open — verify it.

Yes. Credentials live exactly where Claude Code already puts them. All writes are atomic. No postinstall scripts. ~40 KB of compiled JS, MIT-licensed. The real claude binary is never modified.

claude switch → press a. Browser opens once. Sign in. Done.

Fallback injects ANTHROPIC_API_KEY into the env of the claude process it spawns. A REPL that's already running can't be hot-swapped. Exit it, turn fallback on, re-run claude.

🛠 Troubleshooting

📦 What's new

• v3.5.x (upcoming) — 🎯 Project-aware routing. .claude-switch per-repo + claude switch route global rules pick the right account from cwd.
• v3.4.x — 🔐 API keys in macOS Keychain. Plus unified ephemeral state with on-read migration.
• v3.3.x — 🔁 Live OAuth ↔ API transitions. Per-account authMode, swap modes without re-launching.
• v3.2.x — 🪶 auto-revert renamed from fallback auto (legacy alias preserved).
• v3.1.x — 🎨 Ink TUI rebuild. Three-section dashboard, configurable smart defaults.
• v2.8.x — 🔔 Update notifier — daily npm version check + opt-in 1-keypress install on claude switch.
• v2.7.x — 🪟 Profiles — parallel sessions on one machine.

📄 Full changelog: CHANGELOG.md

🤝 Contributing & license

PRs welcome — see CONTRIBUTING.md. Licensed under MIT.

⚖️ Trademark notice

claude-switch is an independent, community-built tool. It is not affiliated with, endorsed by, sponsored by, or in any way officially connected to Anthropic, PBC.

"Claude" and "Claude Code" are trademarks of Anthropic, PBC. The names are used here in a strictly nominative/descriptive sense to indicate compatibility with the Claude Code CLI — this project does not redistribute, modify, or proxy Anthropic software or services. All credentials and API traffic stay between the user and Anthropic.

For Anthropic's official products visit anthropic.com and claude.com/claude-code.

npm install -g @sirtheo/claude-switch