Quick start

Three steps, about a minute: install, add your accounts, turn it on. You need Node.js 20 or newer. It works on macOS, Linux and Windows.

1. Install Agent Switch.

   npm install -g @event4u/agent-switch

2. Add each account once. Each command opens the provider’s own sign-in in your browser. Pick any names you like.

   Claude Code

   agent-switch add work
   agent-switch add personal

   Codex

   agent-switch add work --provider codex
   agent-switch add personal --provider codex

   Already signed in to Claude Code or Codex? See Keep the login you already have.

3. Turn it on. The shell wrapper makes claude and codex start on the right account. The background service keeps every account’s usage fresh, which is what lets Agent Switch balance your sessions.

   agent-switch shellenv install
   agent-switch service install

   Open a new terminal afterwards.

That’s it. Run claude or codex as always. Each start goes to the account with the most to give, and you can ask why at any time:

agent-switch dir --json

Prefer a window? Run agent-switch. The desktop app downloads on first use, with no installer, and starts. See The desktop app.

Check that it worked

agent-switch status           # every account, who it is signed in as, and its limits
agent-switch doctor           # the CLI, the shell wrapper, every login, API keys that override one
agent-switch service status   # the background service and when it last checked usage

doctor names anything that is wrong and the command that fixes it.

Keep the login you already have

import turns the login of your existing install into an account, with no new sign-in:

agent-switch import personal

That account still shares its login with your default install. If both used it, whichever refreshed first would sign the other one out, so Agent Switch never picks a shared account for a balanced start and never refreshes it. Give it its own login once, and it takes part like every other account:

agent-switch login personal

Caution

Never use claude auth logout to switch accounts. It revokes the login on the provider’s side. Switching with Agent Switch never touches the other accounts.

Your shell, by hand

shellenv install detects your shell and adds one line to its startup file. To add it yourself:

zsh

Add to ~/.zshrc:

eval "$(agent-switch shellenv)"

bash

Add to ~/.bashrc (on macOS: ~/.bash_profile):

eval "$(agent-switch shellenv)"

fish

Add to ~/.config/fish/config.fish:

agent-switch shellenv --shell fish | source

PowerShell

Add to $PROFILE:

agent-switch shellenv --shell powershell | Out-String | Invoke-Expression

cmd.exe

cmd.exe has no wrapper. Start a session on an account explicitly:

agent-switch run work

The line defines claude, codex and agy wrappers and the asw shortcut. If Agent Switch is ever missing or broken, the wrappers fall straight through to the real binary, so your tools keep working.

Next steps

Which account a session uses Balanced starts, folder rules and your preferred account.

Everyday workflow The handful of commands you use daily.

Pin a project to an account Client work always on the work account.