Entrypoint System

• Entity ID: ent-20260410-13d0d22b73f8
• Type: concept
• Scope: shared
• Status: active
• Aliases: startup sequence, initialization, boot sequence

Description

The initialization and startup orchestration for Claude Code. Four entrypoints serve different operating modes: interactive CLI (REPL), headless/print mode, MCP server mode, and SDK embedding. The startup sequence is carefully ordered to minimize time-to-first-prompt while initializing network, auth, telemetry, and configuration in parallel where possible.

The four operating modes

1. Interactive CLI (REPL)

Condition: No -p/--print flag, TTY available What it does: Full terminal UI with interactive prompting — the default Claude Code experience. Uses Ink (React for CLIs) to render the TUI. Enters a REPL loop: user input → API call → tool execution → display result.

2. Headless/print mode (-p/--print)

Condition: -p/--print flag set, or !process.stdout.isTTY Handler: src/cli/print.ts — runHeadless() What it does: Non-interactive, single-shot execution. Processes one prompt (from argument or stdin), executes tools with permissions (no dialog — uses --permission-prompt-tool), outputs result, exits. Output formats: text (human-readable), json (single result object), stream-json (line-delimited streaming events)

3. MCP server mode (mcp serve)

Handler: src/entrypoints/mcp.ts — startMCPServer() What it does: Runs Claude Code as an MCP server over stdio. Exposes all tools via the MCP protocol (ListTools + CallTool). No interactive TUI, no full init sequence — just setup() then serve. Minimal AppState with empty permission context. Other MCP clients can call Claude Code's tools directly.

4. SDK mode (--sdk-url)

Condition: --sdk-url with --input-format=stream-json + --output-format=stream-json What it does: Treated as non-interactive. Same initialization as print mode but connects via WebSocket to a remote server. Stream-JSON I/O for structured protocol communication. Full init() and tool loading, but no TUI.

Startup sequence

Phase 1: CLI bootstrap (src/entrypoints/cli.tsx)

The very first code to run. Handles fast-path commands that exit immediately without heavy imports:

• --version / -v — print version, exit
• --dump-system-prompt — output rendered prompt (internal only)
• --claude-in-chrome-mcp — Chrome integration MCP server
• --daemon-worker=<kind> — internal daemon worker
• remote-control / rc — bridge mode
• daemon — long-running supervisor
• ps|logs|attach|kill / --bg — session management

Parallel prefetching starts immediately: - startMdmRawRead() — MDM (mobile device management) settings subprocess on macOS/Windows - startKeychainPrefetch() — parallel keychain reads for OAuth + legacy API keys

Phase 2: Setup (src/setup.ts, lines 56-477)

Per-session initialization, called from main.tsx:

1. Set working directory — setCwd(cwd) — MUST happen before hooks
2. Capture hooks configuration snapshot
3. Initialize FileChanged hook watcher
4. Worktree creation (if --worktree flag) — resolves to main repo root, optionally creates tmux session
5. Background jobs:
6. initSessionMemory() — synchronous
7. initContextCollapse() (feature-gated)
8. lockCurrentVersion()
9. Prefetch system (unless --bare):
10. Load available commands
11. Load plugin hooks
12. Register attribution hooks
13. Register session file access hooks
14. Start team memory watcher
15. Check for release notes
16. Get recent activity
17. Permission mode validation — check for dangerous root + --dangerously-skip-permissions
18. Emit telemetry — logEvent('tengu_started', {})

Phase 3: Init (src/entrypoints/init.ts, lines 57-341)

Memoized — called once per session. Handles external integrations:

1. Config enablement — load .claude/settings.json
2. Safe environment variables + CA certificates (before first TLS connection)
3. Graceful shutdown setup
4. Parallel async initialization:
5. 1P event logging
6. GrowthBook refresh
7. OAuth account info
8. JetBrains IDE detection
9. GitHub repo detection
10. Remote settings promises (if eligible):
11. initializeRemoteManagedSettingsLoadingPromise()
12. initializePolicyLimitsLoadingPromise()
13. Network configuration:
14. mTLS configuration
15. HTTP proxy agents
16. API TCP+TLS warmup (preconnectAnthropicApi())
17. Platform-specific: Windows shell setup, LSP manager cleanup, team cleanup

Phase 4: CLI parsing (src/main.tsx, lines 884-4400)

Commander.js parses process.argv and routes to the appropriate handler:

1. Determine session mode: isNonInteractive = hasPrintFlag || hasInitOnlyFlag || hasSdkUrl || !process.stdout.isTTY
2. Determine client type: cli, sdk-typescript, sdk-python, claude-vscode, claude-desktop, remote, etc.
3. Main command action handler (line 1006) — the massive handler that:
4. Loads trust dialog (interactive only)
5. Resolves initial model
6. Applies environment variables
7. Loads agents, tools, MCP servers
8. Initializes permission context
9. Loads plugins
10. Validates policy limits
11. Creates initial AppState
12. Diverges: calls either launchRepl() (interactive) or runHeadless() (print/SDK)
13. Other commands: mcp serve, auth login|status|logout, plugin install|uninstall|..., agents, doctor, etc.

Bootstrap state

src/bootstrap/state.ts manages global state set during initialization:

Feature gates

Many entrypoint branches are feature-gated with feature('FEATURE_NAME'), enabling dead code elimination at build time:

• DAEMON — daemon worker support
• BRIDGE_MODE — remote control bridge
• DIRECT_CONNECT — direct server connections (cc:// URLs)
• SSH_REMOTE — SSH session mode
• KAIROS — assistant mode
• CONTEXT_COLLAPSE — context optimization
• BG_SESSIONS — background session management
• CHICAGO_MCP — computer use MCP server
• LODESTONE — deep link protocol

What depends on it

• Every other system — the entrypoint initializes all services, tools, and state before anything else runs
• Service layer — services are initialized in init.ts in a specific order (network before API calls, config before feature flags)
• Agent lifecycle — agents inherit the initialization state from the parent session
• Permission system — permission mode is validated during setup, before any tools execute

Design trade-offs

Key claims

• Four entrypoints serve distinct operating modes from a single codebase
• Parallel prefetching (keychain, MDM, network warmup) minimizes time-to-first-prompt
• Feature gates enable dead code elimination — unused modes don't ship in the binary
• MCP server mode provides tool access without the full CLI initialization overhead

Relations

• rel-entrypoint-services: entrypoint-system --[initializes]--> service-layer
• rel-entrypoint-agent: entrypoint-system --[launches]--> agent-lifecycle
• rel-entrypoint-tools: entrypoint-system --[registers]--> tool-system

Sources

Source code at src/entrypoints/cli.tsx, src/main.tsx, src/setup.ts, src/entrypoints/init.ts, src/entrypoints/mcp.ts, src/bootstrap/state.ts