Start here
How Kairos thinks
The few ideas every screen uses — accounts, tools, limits and windows, the threshold and the ceiling, rotation, the week plan and moments.
Accounts and tools
An account is one sign-in to one coding tool: a Claude subscription, a Claude Team or Enterprise seat, an Anthropic API key, a Codex sign-in, a Cursor account. Kairos keeps every tool's accounts in one list; Claude Code is one tool among them, with the most Kairos can do for it.
Each Claude Code account lives in a folder of its own, signed in by Claude Code itself. Kairos never copies or handles a login: it chooses which folder a new session starts in. Codex, Grok, Copilot and Kiro work the same way, with one home folder per account. Cursor, Antigravity and Devin sign in inside their own apps, and Kairos reads what they report. See other tools.
Examples in this book use made-up accounts such as work (account1@example.com) and side (account2@example.com).
Limits and windows
A subscription has limits, each measured as a share used, 0 to 100%:
- the 5-hour window, which starts with the first request after it resets and lasts five hours;
- the weekly limit, which resets once a week (some plans have none, and some have a separate weekly limit for one model);
- for an API key, money: the balance you recorded, less what each request cost since.
Room is what is left before the account's ceiling. An account is ready when it has room in every window.
Threshold and ceiling
- The threshold (80% unless you change it) is when rotation starts looking for another account.
- The limit ceiling (95%) is the most Kairos will let an account reach in any window. An account whose estimated usage (the last reading plus its burn since) would pass the ceiling by the next check is left for the one with the most headroom.
- A cap is your own, lower ceiling for one account. See caps.
Rotation
Every check (every 30 minutes, and sooner when something changes), Kairos decides which account new sessions start on. Running sessions keep their account; only new ones move. The rules, in order, are in Rotation.
The week plan
Kairos forecasts how much you will use this week, hour by hour, from how you used your accounts before, and lays the forecast over every account's limits and resets. The plan says which weeks would expire unspent and spends those first, so the capacity you pay for is used before it resets. See the week plan and Week ahead.
Sessions
A session is one running conversation with a coding tool: a Claude Code session in a terminal or an editor, a Codex session, a background task. Kairos sees each session's account, what it is doing, whether it is waiting on you (a question or a permission), and what it uses of the Mac. See Sessions.
Moments
Kairos stays quiet while things work. A moment is one of the few times it is worth opening: capacity about to go unused, accounts running out, a session using far more than usual. Some are alerts, which may notify you; the rest are glances in the menu bar and on Today. See Moments and notifications.
The engine and the apps
On the Mac, Kairos is two parts: a small engine that runs in the background (the scheduler and a local server on 127.0.0.1:47615), and the app, which shows what the engine knows. The iPhone and iPad app and the web dashboard read the same engine. Everything is kept on your Mac.