Daily use

Five top-level commands carry you through normal use.

Start

backant start                    # current workspace
backant start /path/to/repo      # explicit workspace

By default, Kairos paces itself between turns to keep costs in check. Three flags adjust:

Flag	Effect
`--turbo`	No pacing. High token usage; use for short focused bursts.
`--fresh`	Hard reset. Discards in-process judgment (`.session/`, `.state/`) so the next turn re-reads memory from disk. Memory itself, `.backant.toml`, and your lessons/learnings are preserved.
`--pace`	Auto-throttle. Stretches the pause between turns when Anthropic rate-limit utilization crosses 50% of any window; pauses outright above 95% until the window resets.

--pace is the recommended flag for long-lived deployments on a Max subscription. Keeps Kairos productive without burning your rate-limit headroom.

Stop

backant stop

Sends a graceful shutdown signal. The current turn finishes; nothing new starts. Memory and configuration are unaffected.

Watch

backant watch

Live event feed with a status bar. Each decision and action streams in real time. Exit with Ctrl+C — only detaches the viewer; does not stop Kairos. This is the right thing to keep open in a side terminal while you work alongside it.

Status

backant status

One-shot snapshot. Exits cleanly. Suitable for scripting (CI checks, dashboards). Shows:

Whether Kairos is active
Workspace, latest activity, last outcome
Account validity
Recent memory growth
Pending dream-bucket items

Authentication

backant login                    # browser auth flow
backant logout                   # clear stored credentials

Re-run login after an account switch, or when backant start reports that the account check failed. Credentials persist across reboots under ~/.claude/kairos/.

Per-workspace vs. user-level state

Level	What lives here
Workspace (the repo)	`.backant.toml` (policy), `.session/`, `.state/` (scratch). All committed or gitignored as appropriate.
User (`~/.claude/kairos/`)	Memory store, dream logs, eval reports, credentials, embedding-model cache. Shared across all workspaces you’ve connected.

Memory is intentionally user-level rather than per-workspace — observations about one codebase often inform decisions about another (e.g. “the team uses Zod everywhere”). If you want strict per-workspace isolation, override KAIROS_MEMORY_DB to a workspace-local path before starting.

Configuration reload

Changes to .backant.toml take effect on the next turn. The daemon rebuilds its permissions block from the file before every turn, so no restart is needed. --fresh is only for discarding in-process judgment; it does not affect policy. See Configuration for the full .backant.toml schema, and Let your agent run Kairos for changing keys through backant ctl config.

Steering, configuring, and tasking

backant ctl is the control plane. Every verb takes --json and answers with one envelope line, which is what host agents and scripts use.

backant ctl status --json                       # daemon state, open gates, pending directives
backant ctl task "Fix flaky CI" --json          # file a kairos-task issue and pin it
backant ctl steer focus "the billing module"    # focus | pin | ban | goal | pause | resume
backant ctl gate list --status open --json      # actions parked for your yes
backant ctl gate answer <id> --approve --json
backant ctl explain --json                      # why the last decision was taken
backant ctl config status --json                # is the policy interview complete
backant ctl config set permissions.merge true   # change one key, recorded with who and when

backant tui wraps the same verbs in an interactive view. Install the skill (backant skill install --all) and your coding agent drives these for you; see Let your agent run Kairos.

Quick reference

backant                          # first-run setup OR resume in this workspace
backant login                    # auth
backant logout                   # de-auth
backant setup                    # re-scan, refresh skills
backant start [--turbo|--fresh|--pace]   # start Kairos
backant stop                     # stop Kairos
backant watch                    # live event feed
backant status                   # one-shot snapshot

backant ctl <verb>               # status, task, steer, gate, explain, config, events, board
backant skill install --all      # teach Claude Code, Codex, pi, Hermes to drive Kairos
backant memory <sub>             # see /kairos/memory
backant dream <sub>              # see /kairos/dream
backant eval <sub>               # see /kairos/eval

Pass --help on any subcommand for flags and arguments.

Get started

Daily operation

Commands

Reference

Start

Stop

Watch

Status

Authentication

Per-workspace vs. user-level state

Configuration reload

Steering, configuring, and tasking

Quick reference

​Start

​Stop

​Watch

​Status

​Authentication

​Per-workspace vs. user-level state

​Configuration reload

​Steering, configuring, and tasking

​Quick reference

Start

Stop

Watch

Status

Authentication

Per-workspace vs. user-level state

Configuration reload

Steering, configuring, and tasking

Quick reference