The Claude Code Boot Sequence

When you type claude in your terminal, a sophisticated multi-phase boot pipeline runs before you see the first prompt. Understanding this pipeline helps you: reason about startup latency, debug weird first-launch behaviors, and appreciate the careful parallelism engineers built in to keep time-to-interactive low.

At the highest level, boot happens in three nested layers:

The diagram below traces the exact call sequence from process entry to first render:

Phase 1 — CLI Entrypoint (cli.tsx)

cli.tsx is a deliberate thin bootstrap. All imports are dynamic so the "zero module" fast paths (--version, --daemon-worker, --claude-in-chrome-mcp) return without loading any of the heavy CLI surface. This is a significant UX win — claude --version returns in milliseconds.

// cli.tsx — fast-path: --version needs zero imports
const args = process.argv.slice(2)
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`)
  return
}

// For all other paths, load the startup profiler first
const { profileCheckpoint } = await import('../utils/startupProfiler.js')
profileCheckpoint('cli_entry')

Before loading main.tsx, cli.tsx also handles environment mutations that must happen at process start, before any module evaluates: COREPACK pinning is disabled, and CCR containers get an 8 GB heap cap via NODE_OPTIONS.

Phase 2 — Parallel prefetch side-effects (main.tsx top-level)

The very top of main.tsx has three side-effects that execute before any other imports are evaluated — marked with an ESLint disable comment to make the intent explicit:

// These side-effects must run before all other imports:
profileCheckpoint('main_tsx_entry')   // timestamp: module eval started

startMdmRawRead()     // fires plutil/reg query subprocesses in parallel
startKeychainPrefetch() // starts macOS keychain reads (OAuth + API key)

By the time the ~135ms of static imports finish loading, MDM policy and keychain reads are already in flight. This parallelism shaves significant time from first-auth flows.

Phase 3 — Commander argument parsing

After imports load, main() calls eagerLoadSettings() to handle --settings and --setting-sources flags before Commander even runs, then invokes Commander's .parse(). Commander resolves and validates: cwd, permissionMode, --print/-p mode, --model, --resume, --session, MCP server configs, and many more flags.

// main.tsx — runs migrations once per config version bump
const CURRENT_MIGRATION_VERSION = 11
function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings()
    migrateSonnet45ToSonnet46()  // example: model string upgrades
    migrateOpusToOpus1m()
    // ...8 more migration functions...
    saveGlobalConfig(prev => ({ ...prev, migrationVersion: CURRENT_MIGRATION_VERSION }))
  }
}

Phase 4 — setup() in setup.ts

setup() is where the session is actually wired up. It receives the parsed arguments and performs checks in a carefully ordered sequence:

1. Node.js version gate (≥18 required)
2. Optional custom session ID via switchSession()
3. UDS (Unix Domain Socket) messaging server startup — so hook processes can find the socket
4. Teammate/swarm snapshot (non-bare mode only)
5. iTerm2 and Terminal.app backup restoration for interrupted setups
6. setCwd(cwd) — must happen before anything that reads cwd
7. Hooks config snapshot — reads .claude/settings.json from the new cwd
8. FileChanged hook watcher initialization
9. Optional worktree creation + tmux session
10. Background jobs: initSessionMemory(), getCommands(), plugin hooks
11. initSinks() — attaches analytics + error sinks, drains queued events
12. logEvent('tengu_started') — the first reliable "process started" beacon
13. API key prefetch (safe path only)
14. Release notes check + recent activity fetch
15. Permission safety checks (root/sudo guard, Docker sandbox gate)
16. Previous session exit metrics logged from projectConfig

// setup.ts — setCwd ordering comment (verbatim from source)
// IMPORTANT: setCwd() must be called before any other code that depends on the cwd
setCwd(cwd)

// IMPORTANT: Must be called AFTER setCwd() so hooks are loaded from the correct directory
captureHooksConfigSnapshot()

Phase 5 — Global State (bootstrap/state.ts)

state.ts is the single source of truth for all session-scoped global state. The comment at the top says it plainly: "DO NOT ADD MORE STATE HERE — BE JUDICIOUS WITH GLOBAL STATE."

State tracked includes:

// bootstrap/state.ts — initial state factory (simplified excerpt)
function getInitialState(): State {
  let resolvedCwd = ''
  try {
    // Resolve symlinks so session storage paths are consistent
    resolvedCwd = realpathSync(cwd())
  } catch { resolvedCwd = cwd() }

  return {
    originalCwd: resolvedCwd,
    projectRoot: resolvedCwd,
    sessionId: asSessionId(randomUUID()),
    isInteractive: true,
    totalCostUSD: 0,
    // ... ~60 more fields
  }
}

Phase 6 — Ink render (replLauncher.tsx + ink.ts)

The final step is rendering the React-based TUI. launchRepl() dynamically imports App and REPL components (avoiding circular imports) then calls renderAndRun():

// replLauncher.tsx
export async function launchRepl(
  root: Root,
  appProps: AppWrapperProps,
  replProps: REPLProps,
  renderAndRun: (root: Root, element: React.ReactNode) => Promise<void>,
): Promise<void> {
  const { App }  = await import('./components/App.js')
  const { REPL } = await import('./screens/REPL.js')
  await renderAndRun(root, <App {...appProps}><REPL {...replProps} /></App>)
}

ink.ts wraps every render call with <ThemeProvider> automatically, so ThemedBox and ThemedText components work without each call site having to mount the theme context:

// ink.ts — wraps every render with ThemeProvider
function withTheme(node: ReactNode): ReactNode {
  return createElement(ThemeProvider, null, node)
}

export async function render(node, options) {
  return inkRender(withTheme(node), options)
}