KAIROS Autonomous Mode

What is KAIROS?

KAIROS (Greek καιρός for "the right moment") is Claude Code's 24/7 autonomous AI assistant mode. Unlike passive AI that waits for commands, KAIROS proactively takes action at opportune moments.

Found in 57 files with 158 occurrences in the source code, KAIROS is not an experimental feature but a core system deeply embedded in Claude Code's architecture.

Starting KAIROS Mode

claude assistant

This launches the autonomous assistant. You can also connect to a running session:

claude assistant [sessionId]

The Tick Mechanism

KAIROS operates on a heartbeat system called "tick":

HH:MM:SS AM/PM

• Contains user's current local time
• Triggered via setTimeout loop when proactive mode active
• Priority set to 'later' for batching
• Marked as isMeta: true (system metadata)

Essential KAIROS Tools

SleepTool

Controls AI's wake/sleep rhythm:

Use this when you have nothing to do or waiting for something.
Each wake-up costs an API call, but prompt cache expires after
5 minutes of inactivity — balance accordingly.

• Non-blocking (doesn't hold shell process)
• User can interrupt at any time
• Can be called concurrently with other tools

BriefTool

Sends state-aware messages to user:

{
  "message": "Build completed successfully",
  "status": "proactive"  // or "normal"
}

Status 'proactive' marks AI-initiated messages for different UI presentation.

SendUserFileTool

Proactively sends files to user (KAIROS exclusive):

• Generated reports
• Analysis results
• Code deliverables

PushNotificationTool

System push notifications for important events:

• Long build completions
• Monitored anomalies
• Key decision points requiring human input

SubscribePRTool

GitHub PR event subscription (requires KAIROS_GITHUB_WEBHOOKS):

• Monitor PR status changes
• Automated code review workflows
• CI fix interventions

Channel Integration

KAIROS can integrate with external communication channels (Slack, Discord, SMS) via MCP:

// Channel notification schema
{
  "method": "notifications/claude/channel",
  "params": {
    "content": "Message content",
    "meta": {}
  }
}

Requirements:

• KAIROS or KAIROS_CHANNELS feature flag
• GrowthBook tengu_harbor runtime flag
• claude.ai OAuth authentication (API key users blocked)
• Admin enablement for Teams/Enterprise

System Prompt for Autonomous Mode

When KAIROS activates, system prompt injects key instructions:

You are an autonomous agent. Use the available tools to do useful work.

You will receive  prompts that keep you alive between turns —
just treat them as "you're awake, what now?"

If you have nothing useful to do on a tick, you MUST call Sleep.
Never respond with only a status message — that wastes a turn.

Cost Management

KAIROS balances activity with cost:

• Each wake-up costs one API call
• Prompt cache expires after 5 minutes inactivity
• Sleep longer for slow processes, shorter for active iteration

Best Practices

• Start with clear goals for your autonomous agent
• Configure appropriate tool permissions beforehand
• Use BriefTool status 'proactive' for important notifications
• Monitor token usage during long-running sessions
• Set up Channel notifications for critical events