Kairos for Mac

Setting up on a Mac

Every step Kairos shows the first time it opens on a Mac, what each button does, and how to bring the steps back.

The first time Kairos opens, its window shows a few steps instead of the sidebar. Back returns a step; Skip Setup ends them at once ("Set Up… in Settings brings this back").

1. Welcome to Kairos

"Kairos starts each coding session on the account with room, and tells you before one runs out."

If Kairos was opened from somewhere other than Applications, it says "Kairos is not in Applications yet. There it keeps itself up to date." Move it there first, so it can update itself.

2. Set up

"Setting up adds two background items to this Mac and, if it has none, downloads Python for them. It needs the internet."

• Set Up Kairos installs the engine: Python for Kairos, Kairos's files, starting Kairos on this Mac, and a first check of your accounts. It shows "Setting up" ("A minute or two; Python may take longer on a slow connection.") while it works.
• If a step fails, the last line it printed is shown, with Copy Details (to send to support) and Try Again.
• If the engine was already running, the step says "Kairos is already running on this Mac." and offers Continue.

3. On this Mac

"Kairos adds the accounts your coding tools already use, as they are." It lists them as it finds them ("Looking…"). Nothing is signed out or copied: Claude Code's own login stays where it is.

4. Add another account

"With two or more, Kairos moves new sessions to the one with room." Add Account… opens the add-account sheet: pick the tool, then sign in (in the Mac's browser) or paste an API key. You can add more later from Accounts.

5. Use Kairos's accounts in Terminal

"Then claude in a new Terminal window starts on the account Kairos picks."

Kairos shows the one line it adds to your zsh or bash startup file. Allow adds it ("Added to … Undo it any time in Settings."); Not Now skips it. In another shell, Kairos says "Kairos writes this line for zsh and bash. In fish, start sessions with claude-rotation claude." The same switch is in Settings › General.

6. Keep Kairos at hand

"Each can be changed later in Settings." Three switches:

If notifications are off for Kairos in macOS, the step says so: "Notifications are off for Kairos in System Settings > Notifications."

7. Limit GitHub Actions spend

"Optional. At a repository's daily limit Kairos cancels its pull request and branch runs. Merges, releases and manual runs keep going." It offers to connect GitHub (through your GitHub CLI's sign-in) and a default of $10 a day for each repository: "Change it, or give a repository its own, in Settings." See GitHub Actions limits.

8. Kairos is set up

It says how many accounts it found ("Kairos checks them every few minutes.") or, with none, "Add an account from Today whenever you are ready." Continue opens Today.

Bringing the steps back

Settings › General › This Mac › Set Up… shows the steps again. Nothing you set up before is lost.