Cold Start, Entry Points, Startup Sequence, And Runtime Boot Paths
Real Entry Points
entrypoints/cli.tsx is the real process bootstrap. It handles cheap fast paths first, including --version, special MCP or native-host modes, bridge and daemon modes, and then imports main.tsx for the standard client path.
main.tsx is the primary CLI runtime entry. It wires arguments, startup profiling, settings loading, trust-sensitive initialization, command parsing, setup, MCP prefetching, REPL rendering, and headless branching.
entrypoints/init.ts runs one-time process initialization behind the commander preAction hook in main.tsx.
setup.ts runs after CLI options are known and before the first real query. It establishes cwd, handles worktree behavior, starts UDS messaging when needed, captures hook config, initializes session memory, and restores terminal backups if startup was interrupted.
Standard Interactive Cold Start Sequence
entrypoints/cli.tsx handles fast paths. If none match, it imports main.tsx.
main.tsx immediately starts early side effects in parallel: startup profiler checkpoints, MDM raw reads, and keychain prefetch.
main.tsx rewrites argv early for direct-connect URLs, deep links, assistant mode, and SSH remote mode before commander finalizes parsing.
The commander preAction hook awaits the earlier MDM and keychain promises, calls init(), attaches sinks, processes inline plugin dirs, runs migrations, and starts remote managed settings and policy-limit fetching.
The main action handler validates options, determines whether the session is interactive or headless, constructs the initial tool pool, and calls setup().
setup.ts establishes cwd and worktree state, starts UDS messaging if needed, initializes watchers, and launches background bookkeeping such as session memory and plugin hook prefetch.
main.tsx loads commands and agent definitions, resolves model and agent settings, mounts Ink, and renders setup and trust screens through interactiveHelpers.tsx and dialogLaunchers.tsx.
After trust is granted, main.tsx enables risky subsystems: full config env application, LSP manager, quota or bootstrap API prefetches, MCP execution, and session-start hooks.
screens/REPL.tsx becomes the long-lived host for prompt input, message rendering, permission dialogs, task panes, notifications, and ongoing turn execution.
Headless And SDK Differences
The front half is shared, but after setup() the process branches into cli/print.ts.
Headless mode treats trust as implicit and applies the full config environment before the first query.
MCP connections are pushed into a headless app-state store so the first turn can discover tools and resources as they resolve.
QueryEngine.ts becomes the long-lived conversation owner for headless and SDK flows.
Remote And Bridge Differences
entrypoints/cli.tsx can bypass the normal main.tsx path entirely for bridge mode and jump straight to bridge/bridgeMain.ts.
Remote session viewing uses remote/RemoteSessionManager.ts and SessionsWebSocket.ts rather than local REPL query execution.
Startup Rules That Matter
Trust comes before risky execution in interactive mode.
Worktree setup must finish before command and agent definitions are loaded if cwd can change.
Many startup imports are intentionally lazy because first-render performance is actively managed.
Comments in main.tsx about ordering are there because startup latency, trust safety, or prompt-cache behavior broke in the past.
