🚀 The Entrypoint Layer
src/entrypoints/ contains five files: cli.tsx, init.ts, mcp.ts, agentSdkTypes.ts, sandboxTypes.ts. cli.tsx is a thin bootstrap that fast-paths special commands BEFORE loading the 200+ module import graph.
Fast path 1: --version
Zero imports. Prints MACRO.VERSION inlined at build time.
Fast path 2: --daemon-worker
Loads only worker registry.
Fast path 3: Bridge/RC
Connects local machine as remote-controlled environment.
Fast path 4: Background sessions
ps, logs, attach, kill, --bg without loading interactive UI.
Fallthrough
Full CLI via main.tsx with 200+ module imports.
⚙️ init.ts — Shared Initialization
Memoized init() shared by all non-trivial entrypoints. Not called for fast-paths. 13 steps including configs, TLS certs, graceful shutdown, telemetry, OAuth, IDE detection, proxy agents, and API preconnect (~150ms in parallel with CLI parsing).
🔧 MCP Server Mode
When invoked with claude --mcp, Claude Code runs as a standard MCP server over stdio. Exposes all tools (Bash, Edit, Read, WebFetch) to other MCP clients. Forces isNonInteractiveSession: true and disables thinking.
💡 Symmetric Boundary
Claude Code can BE an MCP server (--mcp mode) while also CONSUMING MCP servers.
📦 Agent SDK Public API
V1 API (stable)
query() - headless one-shot query.
V2 API (@alpha)
unstable_v2_createSession(), resumeSession(), prompt() - persistent multi-turn sessions.
Session Management
listSessions, getSessionInfo, getSessionMessages, renameSession, tagSession, forkSession.
In-process MCP
createSdkMcpServer() and tool() for defining MCP tools.
💡 Stub Pattern
All function bodies throw 'not implemented'. Real implementations injected at runtime by SDK transport layer.
💬 Control Protocol
| Subtype | Direction | Purpose |
|---|---|---|
| initialize | SDK → CLI | Start session with hooks, MCP servers, agents |
| interrupt | SDK → CLI | Cancel currently running turn |
| can_use_tool | CLI → SDK | Request permission for tool use |
| set_permission_mode | SDK → CLI | Change permission mode mid-session |
| set_model | SDK → CLI | Switch model for subsequent turns |
| mcp_status | SDK → CLI | Query MCP server connection states |
🔗 Hook Events & Daemon Mode
26 named hook events for observing/intercepting lifecycle: PreToolUse, PostToolUse, PermissionRequest, SessionStart/End, PreCompact, SubagentStart, TaskCreated, etc.
💡 Daemon vs enableRemoteControl
Daemon mode: WebSocket lives in parent process, survives agent crashes. enableRemoteControl: WebSocket in child, dies with it. Use daemon for production reliability.