backant-kairos

Autonomous AI engineer — observes, judges, builds, ships.

Install & Run

npx backant-kairos

Commands

| Command | Description | |---------|-------------| | backant-kairos | First run: auth → analyze → setup → start | | backant-kairos login | Authenticate with backant.io | | backant-kairos logout | Clear stored credentials | | backant-kairos start | Start the Kairos daemon | | backant-kairos stop | Stop the daemon | | backant-kairos watch | Live feed with status bar | | backant-kairos status | Current state and stats | | backant-kairos setup | Re-run project analysis |

Requirements

• Claude Code installed
• GitHub CLI (gh) installed and authenticated
• Active Kairos subscription ($20/month) at backant.io

Context Hygiene

Long-running daemons accumulate stale judgment in their in-process context. Kairos has three complementary mechanisms to keep the agent's beliefs fresh.

--fresh flag (manual escape hatch)

backant start --fresh

Hard-resets .session/ and .state/ so the next cycle re-reads memory from disk. Memory files (awareness.md, priorities.md, lessons.md, learnings.md, epics/, logs/) and .backant.toml are preserved. A reinit notice is appended to today's daily log so the next cycle knows its prior beliefs were discarded.

Use this after editing .backant.toml, priorities, or lessons that the running daemon hasn't picked up.

Freshness Manager (per-N-cycles meta-agent)

Every N cycles (default 3) Kairos spawns a Sonnet-4.6 meta-agent that reads recent signals — cycle outcomes, repeated failures, lesson churn, decay patterns — and decides whether the next cycle should start fresh. If it decides yes, a .fresh-requested flag is written; the daemon honours it at the top of the next cycle (equivalent to --fresh without human action).

Decisions and patterns are persisted under .kairos/freshness/ so the manager has a feedback loop on its own past calls.

Configure in .backant.toml:

[freshness_manager]
enabled = true                     # default true
cadence_cycles = 3                 # default 3
model = "claude-sonnet-4-6"        # default claude-sonnet-4-6

Dream Tools (LLM-judgment MCP server)

During dream cycles (memory consolidation), Kairos starts an MCP server exposing five tools the dream agent can call to make semantic judgments that pure pattern-matching cannot:

| Tool | Purpose | |------|---------| | verify_assumption | Decide whether a stored claim is still true given current ground truth (git log, open PRs). | | find_stale_entries | Surface JSONL entries whose dates exceed a freshness threshold for human-confirmed pruning. | | check_consistency | Detect contradictions across memory files (lessons vs awareness vs priorities). | | consolidate_logs | Distill recent daily logs into durable lessons. | | prune_with_confirmation | Remove specific JSONL entries, archived to .kairos/archive/ first. |

Configure in .backant.toml:

[dream_tools]
enabled = true                     # default true
model = "claude-sonnet-4-6"        # default claude-sonnet-4-6

Reactive overflow detector

If a cycle hits the Claude context wall and exits abnormally, Kairos detects the overflow signature in the cycle output and writes the same .fresh-requested flag the freshness manager uses. The next cycle starts fresh automatically — a backstop in case the manager underweights signals.

Spec: docs/superpowers/specs/2026-04-29-freshness-manager-and-dream-tools-design.md.

Daemon ↔ Client Contract

The cycle loop runs in kairos-daemon.sh, which is not in this repo — it ships from backant-mcp at src/backant_mcp/kairos/skill_files/kairos-daemon.sh and is fetched at backant login / backant start via the /kairos/skills endpoint. Updates to the bash supervisor land via that repo, not this one.

This repo provides the backant kairos-internal subcommand surface the daemon shells to at five hook points in the cycle loop:

| Hook | When | Subcommand | Effect | |------|------|-----------|--------| | 1 | Top of cycle | consume-fresh-flag | Drops session when .fresh-requested is present | | 2 | Before dream-cycle claude call | prepare-dream-mcp | Writes per-workspace MCP config; daemon adds --mcp-config <path> | | 3 | After every cycle | check-overflow | Detects "Prompt is too long" in stream output, writes .fresh-requested | | 4 | After every cycle | maybe-spawn-freshness | Invokes freshness manager when cadence_cycles reached | | 5 | After dream cycle | cleanup-dream-mcp | Removes the temp MCP config |

The matching daemon bundle is KAIROS_VERSION=1.1.0 (see backant-mcp/src/backant_mcp/kairos/skills_store.py). Older daemons (1.0.0) do not invoke these subcommands; the new helpers ship dormant on those clients until the daemon updates.

To bump the contract: add or change a subcommand in src/commands/internal.ts here, then update kairos-daemon.sh in backant-mcp and bump KAIROS_VERSION.

License

MIT