️ Architecture Overview

Module Dependency Structure

┌─────────────────────────────────────┐
│         Entry Layer                  │
│  entrypoints/cli.tsx → main.tsx     │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│         Core Layer                   │
│  query.ts + QueryEngine             │
│  tools.ts + Tool.ts                 │
│  commands.ts + commands/            │
│  state/ + AppState                  │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│        Service Layer                 │
│  services/ (api/, mcp/, lsp/)       │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│         Tool Layer                   │
│  54 tools in tools/                 │
└─────────────────────────────────────┘

Startup System (cli.tsx)

Three-phase fast path optimization:

Phase 1: Zero-Import Check (<5ms)

// Before any module import
if (args.includes('--version')) {
  console.log(VERSION); // Compile-time constant
  process.exit(0);
}

Phase 2: Mode Routing (10+ Fast Paths)

• --daemon-worker - Daemon worker process
• remote-control / rc / bridge - Bridge mode
• --dump-system-prompt - Debug export
• mcp - MCP server mode
• sdk - SDK entry mode

Phase 3: Full Initialization

init() → setup() → main()

Compile-Time Feature Flags

Using Bun's bun:bundle module for dead code elimination:

import { feature } from 'bun:bundle';
if (feature('KAIROS')) {
  // This code physically doesn't exist in external builds
  const assistantModule = require('./assistant/index.js');
}

16 Major Feature Flags

Total: 89 feature flags (16 major + 73 minor/internal)

10 Runtime Modes

1. Interactive - Default TUI mode
2. Headless/Print - -p flag, stdout output
3. Bridge Remote - Remote control via WebSocket
4. KAIROS Assistant - 7×24 autonomous mode
5. Coordinator - Leader-Worker multi-Agent
6. Daemon - Background resident process
7. Voice - Real-time voice conversation
8. SDK - Programmatic API
9. MCP Server - Claude Code as MCP server
10. SSH Remote - Remote host sessions

main.tsx Structure (4,683 lines)

• Lines 1-100: Module imports with lazy require
• Lines 100-500: CLI parsing with Commander.js
• Lines 500-1000: Parallel initialization
• Lines 1000-2000: Mode activation (KAIROS, Coordinator)
• Lines 2000-3000: Tool pool construction
• Lines 3000-4000: REPL launch
• Lines 4000-4683: Helper functions