What Kairos does by itself

Rotation

How Kairos chooses the account new sessions start on — the threshold, the limit ceiling, weekly-first and the weekly reserve, accounts without a weekly limit, unpaid bills, switching by hand, checks and their outcomes, and moving accounts to Kairos.

Rotation chooses the account each new session starts on, so your work keeps going when one account runs low. Each account is its own Claude Code folder, signed in by Claude Code itself; rotation chooses the folder new sessions start in and never handles a login.

Running sessions keep the account they started on. A switch reaches only sessions started after it.

Checks

Kairos checks every 30 minutes by default, and also when something happens (a window resets, an account is added). Each check reads every account's limits, plans the week, and decides.

claude-rotation check first repairs accounts that need signing in again, then runs one check now. claude-rotation repair only repairs. claude-rotation run runs a check as the scheduler does. claude-rotation logs shows what each check decided (outcome=… and reason=…).

The rules, in order

1. A bill not paid comes first. An account whose latest payment failed may stop at any time, and what it has left goes with it. While it has room it goes first. See Billing.
2. Use-up-by times. An account whose capacity ends soon is spent before it does. See Use up by.
3. The week plan's order. A week the plan would otherwise leave unspent at its reset goes first (weekly-first). Then accounts without a weekly limit (no weekly limit first): their 5-hour window is spent before weeks that can wait. Then the other weeks, the one that resets soonest, or with the least time to spare (weekly reserve). See The week plan.
4. The limit ceiling. An account that would reach 95% of any window by the next check moves to the account with the most room under the ceiling. Sessions never run into a hard limit if another account has room.
5. The threshold. With no rule above deciding, rotation moves when the active account's 5-hour window passes the threshold (80%), to the best account (strategy best), or uses each account up in turn (strategy consume-first).
6. API keys last. Keys are used only when no subscription account has room under the ceiling, and only if you allow it. See API keys.

A cap you set on an account stops rotation there before the ceiling. See Caps.

Switches cost something

Moving sessions to an account in another organization costs their prompt caches; within one organization the caches carry over. So rotation:

• moves only when the next check would not send the sessions straight back;
• does not move to an account whose room, less the cost of the switch, would not last a useful while ("a remnant");
• moves from one reserved week to another only when staying would lose more than the switch.

The plan sentence

Accounts and the web dashboard say, in one sentence, what rotation does now and why:

New in 2.0.69, it names the weeks rotation passes over now:

See Accounts › The plan for how to read it.

Switching by hand

• Switch to This Account… in an account's menu, or Switch now on Today: new sessions use it until it reaches the ceiling; rotation then takes over again.
• claude-rotation switch side holds it for an hour; --for 90 for 90 minutes; --until-ceiling until it would pass the ceiling.
• claude-rotation switch --end hands back to rotation.
• Pause in an account's menu leaves it alone until Use Again.

Moving accounts to Kairos

Older installs rotated by moving one login between accounts (cswap). From 12 November 2026 rotation no longer moves logins. claude-rotation move-accounts (or Move Accounts on the Accounts screen) gives each account its own Claude Code folder; then sign in to each once. No login is copied. claude-rotation prepare-folders does the same while the old rotation keeps running; see Priming.

Settings that shape rotation

See Configuration for every setting.