🔄 What Is KAIROS?
Claude Code transforms from request-response CLI into an autonomous always-on daemon. Boots once, holds persistent sessions across restarts, schedules check-ins, sends unsolicited messages, consolidates memory autonomously.
| Flag | Unlocks | Scope |
|---|---|---|
| KAIROS | Full assistant mode, session continuity, daily-log memory | ant-only |
| KAIROS_BRIEF | BriefTool (SendUserMessage) independently | external |
| KAIROS_PUSH_NOTIFICATION | PushNotificationTool independently | external |
| AGENT_TRIGGERS | Cron scheduling system | gb-gated |
| PROACTIVE | Lighter proactive mode, SleepTool | ant-only |
🎯 The kairosActive Pivot
Single boolean in bootstrap/state.ts. Effects cascade: Memory switches to daily-log mode, BriefTool opt-in bypassed, Fast mode SDK restriction lifted, AutoDream gated off, Bridge registers as claude_code_assistant, Scheduler auto-enables.
⏱️ The Tick Loop
Heartbeat mechanism: model periodically receives <tengu_tick> XML messages. 'You're awake, what now?' If nothing useful, model MUST call SleepTool. Each wake-up costs an API call; prompt cache expires after 5 minutes.
SleepTool
Model chooses sleep duration. Cheaper than Bash(sleep). Interruptible by user messages.
Queue Priority
'now' interrupts immediately. 'next' wakes SleepTool. 'later' drains at end-of-turn.
Terminal Focus
Unfocused: lean into autonomous action. Focused: be more collaborative.
🛠️ KAIROS Tool Suite
Sleep
Yield execution without holding shell process. Feature: PROACTIVE || KAIROS.
SendUserMessage (Brief)
Primary output channel. Supports proactive (unsolicited) vs normal status.
PushNotification
System-level push notification when user walked away.
SubscribePR
GitHub PR webhook subscription for automatic wakeup.
CronCreate/Delete/List
Schedule prompts on cron expressions. One-shot or recurring.
🧠 AutoDream Memory Consolidation
Fires after 24 hours and 5 sessions. Forked sub-agent with hardened read-only tool constraints. Four phases: Orient (ls memory), Gather (daily logs, drifted memories), Consolidate (merge into topic files), Prune (update index under 25KB).
💡 Lock Mechanics
File-mtime lock. tryAcquireConsolidationLock() returns null if another process is mid-consolidation. Kill triggers rollbackConsolidationLock() to prevent permanent blockage.
📁 Daily Log Memory Model
Standard mode: single MEMORY.md file. KAIROS mode: append-only daily logs at logs/YYYY/MM/YYYY-MM-DD.md. Dream skill distills logs into topic files nightly. MEMORY.md becomes synthesized index.
💡 BriefTool Entitlement vs Activation
isBriefEntitled() checks if user is allowed. isBriefEnabled() checks if opted in. Without split, enrolling user in tengu_kairos_brief would silently activate Brief for all sessions.