Claude Code 부트 시퀀스

터미널에 claude를 입력하면 첫 번째 프롬프트가 표시되기 전에 다단계 부트 파이프라인이 실행됩니다. 이 파이프라인을 이해하면 지연 시간의 원인을 추론하고, 시작 관련 이상 현상을 디버깅하며, 낮은 TTI(Time-to-Interactive) 지표를 유지하는 내장 병렬 처리 구조를 파악할 수 있습니다.

세 개의 중첩 레이어로 구성됩니다:

• 레이어 1 — CLI 진입점: cli.tsx가 무비용 패스트 패스, 환경 준비, argv 디스패치를 처리
• 레이어 2 — Main 함수: main.tsx가 Commander 파싱, 초기화, 마이그레이션, 권한 확인을 관리
• 레이어 3 — Setup + REPL: setup.ts + replLauncher.tsx가 세션 배선과 Ink 렌더링을 담당

프로세스 진입부터 첫 렌더링까지의 호출 시퀀스를 추적하는 종합 플로우차트입니다.

Phase 1 — CLI 진입점 (cli.tsx)

의도적으로 가볍게 설계된 부트스트랩으로, 동적 임포트를 활용합니다. --version, --daemon-worker, --claude-in-chrome-mcp 같은 패스트 패스는 무거운 CLI 표면을 로드하지 않고 바로 반환됩니다.

// cli.tsx — 패스트 패스: --version은 임포트가 전혀 필요 없음
const args = process.argv.slice(2)
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`)
  return
}

// 다른 모든 경로는 먼저 시작 프로파일러를 로드
const { profileCheckpoint } = await import('../utils/startupProfiler.js')
profileCheckpoint('cli_entry')

설계 패턴

feature('X') 호출은 Bun의 데드 코드 제거를 활용하는 빌드 타임 플래그입니다. BRIDGE_MODE, DAEMON, SSH_REMOTE 같은 기능은 외부 빌드에서 완전히 제거될 수 있습니다. 디스패치 테이블은 개방-폐쇄 원칙을 따라 main.tsx를 수정하지 않고도 새로운 패스트 패스를 추가할 수 있습니다.

환경 변수 변경은 모듈 평가 전에 수행됩니다: COREPACK 피닝이 비활성화되고, CCR 컨테이너는 NODE_OPTIONS를 통해 8GB 힙 제한을 받습니다.

Phase 2 — 병렬 프리페치 사이드 이펙트 (main.tsx 최상위)

다른 임포트 전에 세 가지 사이드 이펙트가 실행됩니다:

// 이 사이드 이펙트들은 다른 모든 임포트 전에 실행되어야 함:
profileCheckpoint('main_tsx_entry')   // 타임스탬프: 모듈 평가 시작

startMdmRawRead()     // plutil/reg query 서브프로세스를 병렬 실행
startKeychainPrefetch() // macOS 키체인 읽기 시작 (OAuth + API 키)

약 135ms의 정적 임포트가 로드되는 동안 MDM 정책과 키체인 읽기가 병렬로 실행됩니다.

Phase 3 — Commander 인수 파싱

임포트가 로드된 후 main()이 Commander 실행 전에 --settings와 --setting-sources 플래그를 위한 eagerLoadSettings()를 호출한 다음 Commander의 .parse()를 실행합니다. Commander는 cwd, permissionMode, --print/-p 모드, --model, --resume, --session, MCP 서버 구성 등을 해석합니다.

// main.tsx — 설정 버전 범프마다 한 번 마이그레이션 실행
const CURRENT_MIGRATION_VERSION = 11
function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings()
    migrateSonnet45ToSonnet46()  // 예: 모델 문자열 업그레이드
    migrateOpusToOpus1m()
    // ...8개 추가 마이그레이션 함수...
    saveGlobalConfig(prev => ({ ...prev, migrationVersion: CURRENT_MIGRATION_VERSION }))
  }
}

Phase 4 — setup() (setup.ts)

setup()은 신중하게 정해진 순서로 세션을 배선합니다:

1. Node.js 버전 게이트 (≥18 필수)
2. switchSession()을 통한 선택적 커스텀 세션 ID
3. UDS(Unix Domain Socket) 메시징 서버 시작
4. 팀메이트/스웜 스냅샷 (비bare 모드에서만)
5. iTerm2 및 Terminal.app 백업 복원 (중단된 설정용)
6. setCwd(cwd) — cwd를 읽는 코드보다 반드시 먼저 실행
7. Hooks 설정 스냅샷 — 새 cwd에서 .claude/settings.json 읽기
8. FileChanged 훅 감시기 초기화
9. 선택적 worktree 생성 + tmux 세션
10. 백그라운드 작업: initSessionMemory(), getCommands() 프리페치, 플러그인 훅
11. initSinks() — 분석 + 오류 싱크 연결, 대기열 이벤트 드레인
12. logEvent('tengu_started') — 최초의 신뢰할 수 있는 "프로세스 시작" 비컨
13. API 키 프리페치 (안전 경로에서만)
14. 릴리스 노트 확인 + 최근 활동 가져오기
15. 권한 안전 검사 (root/sudo 가드, Docker 샌드박스 게이트)
16. projectConfig에서 이전 세션 종료 메트릭 로깅

// setup.ts — setCwd 순서 주석 (소스에서 그대로)
// 중요: setCwd()는 cwd에 의존하는 다른 코드보다 먼저 호출되어야 합니다
setCwd(cwd)

// 중요: setCwd() 이후에 호출해야 올바른 디렉토리에서 훅이 로드됩니다
captureHooksConfigSnapshot()

Phase 5 — 전역 상태 (bootstrap/state.ts)

state.ts는 세션 범위 전역 상태의 단일 진실 소스입니다. 상단 주석: "여기에 더 많은 상태를 추가하지 마세요 — 전역 상태에 신중하세요."

추적되는 상태 범주:

• 식별 — 세션 & 경로: sessionId, originalCwd, projectRoot, cwd
• 비용 — 사용량 추적: totalCostUSD, modelUsage, 토큰 카운터, FPS 메트릭
• 플래그 — 세션 모드: isInteractive, sessionBypassPermissionsMode, isRemoteMode
• 텔레메트리 — OTel 프로바이더: meter, loggerProvider, tracerProvider
• 캐시 — 프롬프트 캐시: promptCache1hEligible, afkModeHeaderLatched, fastModeHeaderLatched
• 훅 — 런타임 훅: registeredHooks, invokedSkills, sessionCronTasks

// bootstrap/state.ts — 초기 상태 팩토리 (간소화 발췌)
function getInitialState(): State {
  let resolvedCwd = ''
  try {
    // 심볼릭 링크를 해석하여 세션 저장 경로를 일관되게 유지
    resolvedCwd = realpathSync(cwd())
  } catch { resolvedCwd = cwd() }

  return {
    originalCwd: resolvedCwd,
    projectRoot: resolvedCwd,
    sessionId: asSessionId(randomUUID()),
    isInteractive: true,
    totalCostUSD: 0,
    // ... 약 60개 추가 필드
  }
}

Phase 6 — Ink 렌더링 (replLauncher.tsx + ink.ts)

마지막 단계에서 React 기반 TUI를 렌더링합니다. launchRepl()이 순환 임포트를 피하기 위해 App과 REPL 컴포넌트를 동적으로 임포트한 후 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는 모든 렌더 호출을 <ThemeProvider>로 자동 래핑하여 ThemedBox와 ThemedText 컴포넌트가 테마 컨텍스트를 별도로 마운트하지 않아도 동작합니다:

// ink.ts — 모든 렌더를 ThemeProvider로 래핑
function withTheme(node: ReactNode): ReactNode {
  return createElement(ThemeProvider, null, node)
}

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

첫 렌더링 이후: startDeferredPrefetches()가 첫 렌더링에 필요하지 않은 백그라운드 작업을 시작합니다: initUser(), getUserContext(), MCP URL 프리페치, 모델 기능 새로고침, 파일 변경 감지기 초기화. 이 작업은 사용자가 첫 메시지를 입력하는 동안 실행됩니다 — 인간 반응 시간 윈도우를 활용하여 숨겨집니다.