Rotate accounts

With several signed-in accounts, the balanced strategy spreads each run across the ones with capacity to spare and skips any that are rate-limited.

The default

Since CLI 1.20.43, balanced is the default run strategy. You get load-spreading with no flag: agents run distributes work across healthy accounts by remaining capacity and skips any account whose usage window is maxed out.

agents run claude "run the full test suite"   # balanced by default
agents run claude "..." --balanced             # or state it explicitly (-b)

An account is skipped when any usage window — including the 5-hour session window — is at 100%, matching the badge in agents view. A pinned @version, a profile, or --fallback disables balancing for that run.

The three strategies

Set the strategy per run with --strategy, or as a default via run.<agent>.strategy in agents.yaml:

• pinned — always use the workspace/global pinned version.
• available — use the pinned version if it can run right now; otherwise switch to another signed-in version.
• balanced — distribute load across healthy accounts by remaining capacity. The default. (Legacy rotate is accepted as an alias.)

# ~/.agents/agents.yaml
run:
  claude:
    strategy: balanced

Read the gauge

agents usage shows the rate-limit window for every account it knows about, so you can see who has headroom before dispatching.

agents usage           # every installed agent + account
agents usage claude    # just Claude

Claude
  you@example.com
  Usage

    Current session            ██░░░░░░░░ 18% used
    Resets 5 PM (America/Los_Angeles)

    Current week (all models)  █████░░░░░ 53% used
    Resets Jul 14, 7 AM (America/Los_Angeles)

The gauge feeds the balanced strategy: an account near a reset with fresh headroom gets picked first, one at 100% is skipped until its window resets. Query another machine's accounts with agents usage --host <name>.

Related: Run, Pin versions, Sessions.