What Kairos does by itself
API keys
Anthropic API keys as accounts of last resort — adding one, when rotation may use it, recording what its Console balance holds, what each key has left, and Admin keys for what an organization's API use costs.
An Anthropic API key can be an account too: billed per token, from your Console organization's money. Kairos treats keys as the last resort, after every subscription account.
Adding a key
- Add Account › Claude Code › API key ("Billed per token."), then paste it into Key. See Accounts › Adding an account.
- From Terminal:
claude-rotation add-key --label build. The key (it starts sk-ant-api) is read hidden, or from a pipe, and is never put on a command line. At a terminal, without--label, it asks for a name.
--rotation off adds the key without letting rotation use it; --rotation last-resort lets it.
When rotation uses a key
The API keys setting is off by default: rotation never moves onto a key. Set to last-resort, rotation moves onto the key with the most money left only when no subscription account has room under the limit ceiling, and back as soon as one is under the threshold again. Only sessions started on the key use it; running sessions keep their account. See Configuration.
What a key has left
Anthropic offers no way for a key to read its own balance, so Kairos keeps one itself: the balance you last recorded from the Console's Billing page, less the exact cost of every request billed to the key since. Request costs are counted from each response's billed usage within seconds of it.
Record the balance when it changes (after a top-up, or a new month):
| Command | What it records |
|---|---|
claude-rotation key-budget build --balance 120 |
The credit the Billing page shows, in dollars. |
… --expires 2026-12-31 --expiring 40 |
Promotional credit and when it expires. |
… --monthly-limit 200 (or none) |
The organization's monthly spend limit. |
… --month-spent 35 |
What the month has spent so far. |
… --reserve 5 |
The money kept back (5% of the balance, at least $2, unless set). |
… --auto-reload on |
Whether the Console tops up by itself. |
A Max or Team plan's monthly API credit does not pay for Claude Code, and nothing reads it from Anthropic.
claude-rotation keys shows, for each key: what is left, the burn per hour, and when credit expires.
A key is spent, and rotation leaves it at once, when what is left (less the next check's burn) reaches its reserve, when its credit has expired, when its monthly limit is reached, or when Anthropic refused a request on it for billing. It is held out until it has money again.
link-billing, from older versions, was removed in 1.9.3: it now points to key-budget.
Admin keys
An organization's Admin key (it starts sk-ant-admin) shows what that organization's API use costs. An organization admin makes one at platform.claude.com › Settings › Admin keys.
- On a Mac: Settings › Accounts › API costs › Admin keys. See Settings.
- From Terminal:
claude-rotation admin-key add finance(read hidden, or from a pipe),admin-key list,admin-key remove finance.
Kairos keeps it in the Mac's login Keychain once Anthropic accepts it.