Everyday workflow

Once your accounts are added, you mostly just type claude or codex as before. Agent Switch picks the account each new session starts on, and every other account stays signed in for the next one.

This page walks through a normal day: starting sessions, steering which account they use, checking what is left, and keeping your list of accounts tidy.

Start a session

With the shell integration installed (agent-switch shellenv install), the commands you already use are wrapped:

cd ~/code/client-a
claude          # or: codex, agy

Before the real binary starts, the wrapper asks Agent Switch which account fits this folder and points the tool at that account’s own folder. The order is:

A pinned folder. If this folder or one of its parents is pinned to an account or a pool, that rule decides. See Projects and pools.
A balanced start. With no pin, the session goes to the account that would lose the most of its remaining quota at its next reset. This needs usage numbers that are at most 10 minutes old.
Your preferred account. On a tie, or when no account has fresh usage, the start uses the account you chose with asw (below).
The tool’s own login. With no preferred account set, the tool starts with its default login, exactly as without Agent Switch.

Running sessions are never moved by any of this. The choice happens only when a session starts. See Which account a session uses for the full rules.

Set your preferred account with `asw`

The shell integration also defines asw, a short form of agent-switch use:

asw                 # list every account, grouped by tool
asw work            # make "work" your preferred Claude account
asw codex personal  # make "personal" your preferred Codex account

asw <name> does not pin anything. It sets the account a plain start falls back to: on a tie, without fresh usage, or for tools that report no usage. New sessions pick it up; running sessions are unaffected. A disabled account cannot be made preferred until you enable it again.

To clear the preference for a tool:

agent-switch deactivate                     # Claude
agent-switch deactivate --provider codex    # Codex

Run one session on a specific account

When you want exactly one session on a given account, without changing your preference or any folder pin, use run:

agent-switch run personal
agent-switch run work --provider codex
agent-switch run work --cwd ~/code/client-a
agent-switch run work -- --resume          # everything after -- goes to claude

run starts the tool on that account directly. It skips folder pins and balancing. Options:

Option	What it does
`--provider codex\|antigravity`	Run another tool (default: Claude)
`--cwd <dir>`	Start in that folder
`--tmux`	Run inside a tmux session that Agent Switch manages (macOS and Linux)
`--force`	Start even if the account already has a live session and the guard is set to `block`
`--`	Pass everything after it to the tool unchanged

run is also the way to start an account from cmd.exe on Windows, which has no shell integration.

Check what each account has left

agent-switch status                 # every account, with usage where available
agent-switch status work            # one account
agent-switch status --provider codex

For Claude and Codex accounts, status shows the 5-hour and weekly limits with their reset times, plus the context fill of any live session. Antigravity has no usage readout, so its accounts show identity only.

Two related views:

agent-switch list           # accounts per tool; * marks the preferred one
agent-switch auth-status    # sign-in state per account (no tokens printed)

Ask why a start went where it did

Every start through the shell wrapper is recorded:

agent-switch picks
agent-switch picks --limit 5 --json

Each entry shows the account chosen (or the refusal) and the reasons, for example which accounts were skipped as signed out or at their limit, and how old the usage numbers were.

To preview the decision for the current folder without starting anything:

agent-switch dir --json

Check your setup

agent-switch doctor

doctor runs a self-check for your OS and each tool: whether agent-switch and the tools are on your PATH, whether the shell integration is loaded, and whether no two accounts of one tool are signed in to the same login. It exits non-zero when something blocks normal use, so it also works in scripts.

One account, one session

By default, starting a second session on an account that already has one prints a warning and continues. You can change that:

agent-switch guard          # show the policy and which accounts are busy
agent-switch guard block    # move a second session to a free account
agent-switch guard off      # no check

With block, a start that would land on a busy account moves to a free one. When every usable account is busy, it shares the best one and says so. A busy account never makes a start fail. To allow one duplicate start under block, prefix it with AGENT_SWITCH_ALLOW_DUPLICATE=1.

This works for Claude only. Codex and Antigravity do not register a running session on disk, so Agent Switch cannot tell whether an account is busy.

Keep your account list tidy

Pause an account without deleting it. A disabled account is skipped by balanced starts and pools, and a folder pinned to it refuses to start until you change the pin.
Terminal window
```
agent-switch disable personal
agent-switch enable personal
```
Tag and colour accounts. Tags (Work, Personal, Other) group accounts and can seed pools. Colours show up in the desktop app.
Terminal window
```
agent-switch label work Work
agent-switch color work teal
agent-switch label work none     # clear the tag
```
Rename an account. Folder pins, pool memberships, limit settings and launchers follow the new name. Names may contain letters, numbers, dots, dashes and underscores. A Claude account with a live session cannot be renamed until the session ends.
Terminal window
```
agent-switch rename side client-a
```
Remove an account. This deletes the account’s folder and its login, and drops its folder pins. It asks first on a terminal; --yes skips the question.
Terminal window
```
agent-switch remove client-a
```

Next steps

Projects and pools Pin a folder to an account, or let it choose within a group.

Move a session Continue a session on another account when one runs low.

The desktop app The same day, in one window and the menu bar.