Installation

Install Kairos and walk through the first-run setup wizard.

Quick install

From inside the repo you want Kairos to work on:

cd /path/to/your/repo
npx backant-kairos

The first run walks you through four steps automatically: login, project setup, memory initialization, and daemon start.

Kairos works at the workspace level. Each repo gets its own .backant.toml policy file and its own daemon. Memory itself lives at the user level (under ~/.claude/kairos/) and is shared across all workspaces.

Requirements

Requirement	Why
macOS or Linux	Tested platforms. Windows via WSL is best-effort.
Claude Code installed and signed in	Kairos uses your Claude Code installation for reasoning calls.
GitHub CLI (gh) authenticated	For PR operations and CI introspection.
Docker running	Hosts the local embedding service.
Active BackAnt subscription	Validated on daemon start.

The first-run wizard

npx backant-kairos runs these steps in order. Each step is also runnable individually as a subcommand.

1. Login

   Opens a browser auth flow against backant.io to issue credentials. Credentials persist across reboots under ~/.claude/kairos/.

   backant login
   
2. Project setup

   Scans the workspace, detects language/framework/CI conventions, and generates .backant.toml (the per-project policy file). Also installs recommended skills and plugins, and adds .backant.toml to CODEOWNERS so policy changes route to you.

   backant setup
   

   Idempotent — existing .backant.toml is preserved.

3. Memory init

   One-time installation of the local embedding stack. Pulls the Docker image plus a Qwen3-Embedding model sized to your hardware, and writes ~/.claude/kairos/config.json.

   backant memory init
   

   Takes 3–5 minutes depending on the tier and your network. See the memory page for tier sizing.

4. Start Kairos

   Attaches Kairos to the current workspace and begins working.

   backant start
   

Subsequent installs

Once the wizard has run once per workspace, you only need backant start to resume. Running backant alone detects whether to resume or run setup.

cd /path/to/your/repo
backant

Re-running setup

If you change .backant.toml, add a new repo, or want to refresh installed skills:

backant setup

Existing config is preserved; new conventions are merged where safe.

Switching embedding models

After the initial install, you can re-run memory init to pick a different Qwen3 tier. If you do, run memory reindex afterwards to re-embed everything against the new model — otherwise recall will produce dimension mismatches.

backant memory init       # pick new tier
backant memory reindex    # re-embed all entries

Uninstall

To stop the daemon and remove all Kairos state from your machine:

backant stop
rm -rf ~/.claude/kairos/

The npm package itself can be removed with npm uninstall -g backant-kairos if installed globally, or just deleted if you used npx.