Startup & Initialization

Overview

The startup process is highly optimized for parallel execution and dead code elimination via feature flags.

Startup Timeline

Phase 1: Pre-Import Side Effects (0-10ms)

// src/main.tsx (lines 9-20)
// These side-effects must run BEFORE all other imports:

// 1. Profile checkpoint marks entry
profileCheckpoint('main_tsx_entry');

// 2. Fire MDM subprocesses in parallel
startMdmRawRead();

// 3. Fire keychain reads in parallel
startKeychainPrefetch();

Key Optimization: MDM settings, Keychain, and API preconnect all start simultaneously before the ~135ms of remaining imports complete.

Phase 2: Import Loading (~135ms)

// During imports, heavy modules are lazily loaded:
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null;

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js')
  : null;

Phase 3: Pre-Action Hook (Before First Command)

// src/main.tsx (lines 907-967)
program.hook('preAction', async thisCommand => {
  // Wait for MDM and keychain prefetches to complete
  await Promise.all([
    ensureMdmSettingsLoaded(),
    ensureKeychainPrefetchCompleted()
  ]);
  
  // Initialize core systems
  await init();
  
  // Set process title
  process.title = 'claude';
  
  // Attach logging sinks
  const { initSinks } = await import('./utils/sinks.js');
  initSinks();
  
  // Run migrations
  runMigrations();
  
  // Load remote managed settings
  void loadRemoteManagedSettings();
  void loadPolicyLimits();
});

Initialization Functions

Core Initialization (init())

// src/entrypoints/init.ts
export async function init(): Promise<void> {
  // 1. Load settings
  const settings = getInitialSettings();
  
  // 2. Initialize services
  await initializeServices();
  
  // 3. Set up state management
  createStore();
  
  // 4. Register cleanup handlers
  registerCleanup(() => {
    // Cleanup logic
  });
}

Service Initialization

// Services are initialized in parallel
await Promise.all([
  initializeApiService(),
  initializeMcpService(),
  initializeOauthService(),
  initializeLspService(),
  initializeAnalyticsService()
]);

Feature Flag System

Feature gates are used extensively for dead code elimination:

import { feature } from 'bun:bundle';

// Conditional module loading
if (feature('COORDINATOR_MODE')) {
  const coordinatorModule = require('./coordinator/coordinatorMode.js');
  // Use coordinator functionality
}

if (feature('KAIROS')) {
  const assistantModule = require('./assistant/index.js');
  // Use assistant functionality
}

if (feature('DIRECT_CONNECT')) {
  // Handle direct connect URLs
  const parsed = parseConnectUrl(ccUrl);
}

Key Feature Flags

Migration System

Migrations run during pre-action hook:

// src/main.tsx (lines 325-352)
const CURRENT_MIGRATION_VERSION = 11;

function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings();
    migrateBypassPermissionsAcceptedToSettings();
    migrateEnableAllProjectMcpServersToSettings();
    resetProToOpusDefault();
    migrateSonnet1mToSonnet45();
    migrateLegacyOpusToCurrent();
    migrateSonnet45ToSonnet46();
    migrateOpusToOpus1m();
    migrateReplBridgeEnabledToRemoteControlAtStartup();
    if (feature('TRANSCRIPT_CLASSIFIER')) {
      resetAutoModeOptInForDefaultOffer();
    }
    if ("external" === 'ant') {
      migrateFennecToOpus();
    }
    saveGlobalConfig(prev => ({
      ...prev,
      migrationVersion: CURRENT_MIGRATION_VERSION
    }));
  }
}

Deferred Prefetches

Non-critical prefetches run after first render:

// src/main.tsx (lines 388-431)
export function startDeferredPrefetches(): void {
  // Skip in bare mode or when measuring startup
  if (isBareMode() || process.env.CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER) {
    return;
  }
  
  // Prefetch user context
  void initUser();
  void getUserContext();
  
  // Prefetch system context if safe
  prefetchSystemContextIfSafe();
  
  // Prefetch MCP URLs
  void prefetchOfficialMcpUrls();
  
  // Initialize analytics gates
  void initializeAnalyticsGates();
  
  // Start file change detectors
  void settingsChangeDetector.initialize();
  if (!isBareMode()) {
    void skillChangeDetector.initialize();
  }
}

Startup Performance Metrics

Security Considerations

1. Parallel Startup: Multiple processes run simultaneously
2. Feature Gates: Dead code elimination reduces memory footprint
3. Lazy Loading: Heavy modules loaded on demand
4. Error Boundaries: Graceful degradation on failures
5. Permission Modes: Startup respects permission settings

Startup Best Practices

1. Parallel Execution: MDM, Keychain, API all start together
2. Feature Flags: Conditional module loading
3. Migration System: Automatic settings updates
4. Deferred Work: Non-critical work after first render
5. Cleanup Handlers: Proper resource cleanup on exit