Reference

Settings and config

The rotation settings claude-rotation config asks for, what each does, its default and its range, and where they are kept.

Most of Kairos is set in the app: see Settings. How rotation itself decides (when to switch, what to spend first, where to stop) is set once, from a terminal:

claude-rotation config

It asks for each setting in turn and shows the current value in brackets. Press Return to keep it. When you are done, Kairos checks every value, saves them, tells the week plan to plan again, and restarts its background agents so the new values take effect.

The settings

Prompt	Default	Range	What it does
Strategy	best	best, consume-first	Where rotation goes once the active account passes the threshold. best: the account with the most room. consume-first: of the accounts under the threshold, the one whose week resets soonest.
Threshold percentage	80	50–99.9	How much of an account's limit is used before rotation looks for another.
Model scope	none	none, all, or names such as Fable,Opus	Which per-model weekly limits count, as well as the 5-hour window and the week. None counts only those two; all counts every model's.
Interval seconds	1800	30–86400	How often the scheduler runs a check.
Dashboard port	47615	1024–65535	The web dashboard's port on this Mac.
Desktop notifications	on	on, off	A macOS notification when a session needs attention: blocked on a sign-in, or idle after its usage limit lifted.
Weekly-first	on	on, off	Weeks that would expire unused first, then accounts without a weekly limit, then the weeks that can wait. See Rotation.
Weekly-first: % of the weekly limit	95	50–99.9	Weekly-first leaves an account when its week reaches this.
Weekly-first: % of the 5-hour window	90	50–99.9	Weekly-first leaves an account when its 5-hour window reaches this.
Limit ceiling	95	50–99.9	An account that would pass this percentage of any window by the next check is left for the one with the most room. Caps never go above it.
API keys	off	off, last-resort	off: rotation never moves onto an API-key account. last-resort: only when no subscription account has room under the limit ceiling, and back once one is under the threshold. See API keys.
Pause guard	on	on, off	Asks a working session to stop at a safe point before its account reaches a limit, and to continue after the reset. See The capacity guard.
Pause guard: minutes before the limit	10	2–60	How much notice a session gets.
Pairing port	47616	1024–65535, not the dashboard's	The port iPhone and iPad use on your Wi-Fi. It is open only while a device is paired or a pairing window is open. See Pairing.
API errors	on	on, off	Asks a session an API error stopped (the response cut off, the service overloaded) to carry on, and again for a while. See The capacity guard.

A value out of range is refused when you type it. In the file, an out-of-range ceiling, guard or on/off value is ignored with a warning and its default used; a bad strategy, threshold, interval or port stops each command with a message until it is fixed.

The file

The settings are kept in ~/Library/Application Support/ClaudeRotation/state/config, one KEY=value line each:

Key	Setting
`STRATEGY`	Strategy
`THRESHOLD`	Threshold percentage
`MODEL_SCOPE`	Model scope
`INTERVAL_SECONDS`	Interval seconds
`DASHBOARD_PORT`	Dashboard port
`NOTIFY`	Desktop notifications
`WEEKLY_FIRST`	Weekly-first
`WEEKLY_CEILING`	Weekly-first: % of the weekly limit
`SESSION_CEILING`	Weekly-first: % of the 5-hour window
`LIMIT_CEILING`	Limit ceiling
`API_KEYS`	API keys
`PAUSE_GUARD`	Pause guard
`PAUSE_LEAD_MINUTES`	Pause guard: minutes before the limit
`CARRY_ON_ERRORS`	API errors
`PAIR_PORT`	Pairing port
`ACCOUNT_STORE`	Where accounts live: `folders` (a Claude Code folder each) or `cswap` on an older install. Changed only by move-accounts.
`CSWAP`, `CLAUDE_DIR`	Paths Kairos found for an older install.

Kairos rewrites the file whole, so a comment you add is lost. Prefer claude-rotation config.

Fixed values

Value	Default	What it is
Check timeout	120 seconds	A check that runs longer is stopped and logged as `timeout` (exit 124).
Key reserve	5% of the recorded balance, at least $2	An API key is left when its money left reaches this, unless you set your own with `key-budget --reserve`.

A command you run yourself reads three waits from its environment: CLAUDE_ROTATION_CHECK_TIMEOUT (seconds a check may run, 120), CLAUDE_ROTATION_CHECK_LOCK_WAIT (seconds a check or a switch waits for one already running, 60) and CLAUDE_ROTATION_DASHBOARD_WAIT (seconds Kairos waits for the dashboard to answer when it starts it, 30).