Claude Code 소스 코드 분석

분석 대상: src/ 디렉토리 전체
분석 일자: 2026-03-31

프로젝트 개요
아키텍처 개관
최상위 핵심 모듈
주요 카테고리별 상세 분석
- 4.1 UI / 렌더링 계층
- 4.2 도구(Tool) 시스템
- 4.3 명령어(Command) 시스템
- 4.4 서비스(Services) 계층
- 4.5 브릿지(Bridge) 시스템
- 4.6 상태 관리(State)
- 4.7 태스크(Task) 시스템
- 4.8 CLI / 진입점(Entrypoints)
- 4.9 유틸리티(Utils)
- 4.10 플러그인 / 스킬 시스템
- 4.11 MCP (Model Context Protocol)
- 4.12 Ink 터미널 렌더링 엔진
- 4.13 키바인딩(Keybindings)
- 4.14 메모리(Memory) 시스템
- 4.15 원격(Remote) 세션
- 4.16 Vim 모드
- 4.17 음성(Voice) 모드
- 4.18 마이그레이션(Migrations)
- 4.19 기타 모듈
기술 스택 요약

1. 프로젝트 개요

Claude Code는 터미널 기반의 AI 코딩 어시스턴트이다. Anthropic의 Claude 모델을 활용하여 사용자가 터미널에서 대화형으로 코드를 작성, 편집, 검색, 실행할 수 있도록 하는 REPL(Read-Eval-Print Loop) 애플리케이션이다.

주요 특성:

Bun 런타임 기반 TypeScript 프로젝트 (빌드 시 bun:bundle feature flag 활용)
React Ink 기반 터미널 UI 렌더링
MCP(Model Context Protocol) 지원으로 외부 도구 통합
다중 에이전트/팀(Swarm) 아키텍처 지원
IDE 연동 (VS Code, JetBrains 등)
원격 세션(Bridge) 및 claude.ai 연동
플러그인/스킬 확장 시스템

2. 아키텍처 개관

┌─────────────────────────────────────────────────────────────────┐
│                         Entrypoints                             │
│   main.tsx (CLI)  │  mcp.ts (MCP 서버)   │  sdk/ (Agent SDK)     │
└────────┬──────────┴──────────┬──────────┴──────────┬────────────┘
         │                     │                     │
         ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Core Engine                              │
│  QueryEngine.ts  ←→  query.ts  ←→  Tool.ts / tools.ts           │
│  (메인 루프)           (API 호출)      (도구 정의/실행)                │
└────────┬──────────────────┬──────────────────┬──────────────────┘
         │                  │                  │
         ▼                  ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐
│  State Mgmt  │  │   Services   │  │     UI (React Ink)       │
│  AppState    │  │  API, MCP,   │  │  components/, screens/,  │
│  store.ts    │  │  Analytics,  │  │  ink/ (커스텀 렌더러)       │
│              │  │  LSP, OAuth  │  │                          │
└──────────────┘  └──────────────┘  └──────────────────────────┘
         │                  │
         ▼                  ▼
┌──────────────┐  ┌──────────────────────────────────┐
│   Bridge     │  │        Plugins / Skills          │
│  (원격 연동)   │  │  MCP 서버, 번들 스킬, 커스텀 확장      │
└──────────────┘  └──────────────────────────────────┘

3. 최상위 핵심 모듈

파일	역할
`main.tsx`	애플리케이션 진입점. Commander.js 기반 CLI 파싱, 인증, 설정 로드, GrowthBook 초기화, REPL 실행 등 전체 부트스트랩 수행
`QueryEngine.ts`	메인 대화 루프 엔진. 사용자 입력 → API 호출 → 도구 실행 → 응답 생성의 핵심 사이클 관리. 자동 compact, context collapse, speculation 등 고급 기능 포함
`query.ts`	Claude API 호출 계층. 메시지 정규화, 시스템 프롬프트 구성, 스트리밍 응답 처리, 에러 핸들링
`Tool.ts`	도구 타입 정의 및 인터페이스. `Tool`, `ToolUseContext`, `ToolPermissionContext` 등 핵심 타입 정의
`tools.ts`	도구 레지스트리. 사용 가능한 모든 도구(Bash, FileEdit, FileRead, Agent 등)를 등록하고 관리
`commands.ts`	슬래시 명령어 레지스트리. `/commit`, `/review`, `/mcp`, `/memory` 등 모든 슬래시 명령을 등록
`Task.ts`	태스크 타입 정의. 백그라운드 실행 단위(bash, agent, remote_agent, teammate 등) 정의
`tasks.ts`	태스크 디스패칭. 태스크 타입별 spawn/kill 라우팅
`setup.ts`	세션 초기화. 작업 디렉토리 설정, git 루트 탐색, 워크트리 생성, 세션 스토리지 초기화
`cost-tracker.ts`	비용/토큰 추적. API 호출별 토큰 사용량, USD 비용, 모델별 사용량 집계
`context.ts`	시스템/사용자 컨텍스트 생성. 운영체제, 셸, 프로젝트 정보를 시스템 프롬프트용 컨텍스트로 구성
`replLauncher.tsx`	REPL 화면 실행기. App + REPL 컴포넌트를 Ink로 렌더링
`ink.ts`	커스텀 Ink 인스턴스 생성. `createInkApp`과 Root 타입 export
`history.ts`	세션 이력 관리. 과거 대화 세션의 로드/저장

4. 주요 카테고리별 상세 분석

4.1 UI / 렌더링 계층

`components/` — React Ink 컴포넌트 (100+ 파일)

메인 UI를 구성하는 React 컴포넌트들의 대규모 컬렉션이다.

하위 영역	주요 컴포넌트	설명
앱 프레임	`App.tsx`, `FullscreenLayout.tsx`	전체 앱 래퍼, 레이아웃 관리
메시지 렌더링	`Message.tsx`, `Messages.tsx`, `MessageRow.tsx`, `VirtualMessageList.tsx`	대화 메시지 표시, 가상 스크롤 지원
프롬프트 입력	`PromptInput/`, `TextInput.tsx`, `VimTextInput.tsx`, `BaseTextInput.tsx`	사용자 입력 영역, Vim 모드 지원
다이얼로그	`BridgeDialog.tsx`, `CostThresholdDialog.tsx`, `ExportDialog.tsx`, `MCPServerApprovalDialog.tsx` 등	각종 모달/확인 다이얼로그
코드 표시	`HighlightedCode.tsx`, `Markdown.tsx`, `StructuredDiff.tsx`, `FileEditToolDiff.tsx`	코드 하이라이팅, 마크다운 렌더링, diffs
상태 표시	`StatusLine.tsx`, `Spinner.tsx`, `Stats.tsx`, `TokenWarning.tsx`, `MemoryUsageIndicator.tsx`	하단 상태바, 로딩 인디케이터, 통계
에이전트/팀	`agents/`, `teams/`, `CoordinatorAgentStatus.tsx`	다중 에이전트 관련 UI
설정	`Settings/`, `ThemePicker.tsx`, `OutputStylePicker.tsx`, `ModelPicker.tsx`	설정 화면, 테마/모델 선택기
온보딩	`Onboarding.tsx`, `IdeOnboardingDialog.tsx`, `ClaudeInChromeOnboarding.tsx`	최초 실행/연동 안내
MCP	`mcp/`	MCP 서버 관련 UI 컴포넌트
디자인 시스템	`design-system/`, `ui/`	공통 UI 프리미티브, 재사용 위젯
권한	`permissions/`, `TrustDialog/`, `sandbox/`	도구 실행 권한 확인 UI
기타	`Feedback.tsx`, `DevBar.tsx`, `SearchBox.tsx`, `LogSelector.tsx`	피드백, 개발자 도구, 검색

`screens/` — 화면 단위 컴포넌트

파일	설명
`REPL.tsx`	메인 REPL 화면. 대화 인터페이스의 최상위 화면
`Doctor.tsx`	진단(Doctor) 화면. 시스템 상태 점검
`ResumeConversation.tsx`	이전 세션 재개 화면

`hooks/` — React 커스텀 훅 (80+ 파일)

카테고리	주요 훅	설명
입력 처리	`useTextInput`, `useVimInput`, `useSearchInput`, `usePasteHandler`	텍스트/검색 입력, 붙여넣기 처리
세션 관리	`useSessionBackgrounding`, `useRemoteSession`, `useAssistantHistory`	세션 백그라운딩, 원격 세션
IDE 연동	`useIDEIntegration`, `useIdeConnectionStatus`, `useIdeSelection`	IDE 상태/선택 동기화
팀/스웜	`useSwarmInitialization`, `useSwarmPermissionPoller`, `useMailboxBridge`	다중 에이전트 초기화
도구 권한	`useCanUseTool`, `toolPermission/`	도구 사용 가능 여부 판정
UI 상태	`useBlink`, `useElapsedTime`, `useTerminalSize`, `useVirtualScroll`	시각적/레이아웃 관련
외부 연동	`useVoice`, `useReplBridge`, `useTeleportResume`	음성, 원격 조종, 텔레포트
알림	`notifs/`, `useUpdateNotification`, `useNotifyAfterTimeout`	알림 관리

4.2 도구(Tool) 시스템

`tools/` — 개별 도구 구현 (40+ 도구)

Claude가 사용할 수 있는 모든 도구의 구현체이다. 각 도구는 독립 디렉토리 내에 정의된다.

카테고리	도구	설명
파일 작업	`FileReadTool`, `FileWriteTool`, `FileEditTool`, `GlobTool`, `GrepTool`	파일 읽기/쓰기/편집, glob 검색, 텍스트 검색
셸 실행	`BashTool`, `PowerShellTool`	Bash/PowerShell 명령 실행
에이전트	`AgentTool`, `SendMessageTool`, `TeamCreateTool`, `TeamDeleteTool`	서브 에이전트 생성/관리, 팀원 간 메시지
태스크 관리	`TaskCreateTool`, `TaskGetTool`, `TaskListTool`, `TaskOutputTool`, `TaskStopTool`, `TaskUpdateTool`	백그라운드 태스크 CRUD
계획(Plan)	`EnterPlanModeTool`, `ExitPlanModeTool`	계획 모드 진입/종료
워크트리	`EnterWorktreeTool`, `ExitWorktreeTool`	Git 워크트리 격리 작업
MCP	`MCPTool`, `McpAuthTool`, `ListMcpResourcesTool`, `ReadMcpResourceTool`	MCP 서버 도구 호출, 인증, 리소스
웹	`WebFetchTool`, `WebSearchTool`	웹 페이지 가져오기, 웹 검색
코드 분석	`LSPTool`, `ToolSearchTool`	LSP 기반 코드 분석, 도구 검색
사용자 상호작용	`AskUserQuestionTool`, `ConfigTool`	사용자 질문, 설정 변경
스킬	`SkillTool`	스킬 기반 코드 생성
기타	`TodoWriteTool`, `NotebookEditTool`, `REPLTool`, `SleepTool`, `BriefTool`, `SyntheticOutputTool`	TODO 관리, 노트북 편집, REPL 실행, 대기, 요약
스케줄링	`ScheduleCronTool`, `RemoteTriggerTool`	크론 작업, 원격 트리거
공유 유틸	`shared/`, `utils.ts`, `testing/`	도구 간 공통 로직, 테스트 헬퍼

4.3 명령어(Command) 시스템

`commands/` — 슬래시 명령어 (90+ 명령어)

사용자가 / 접두사로 실행하는 인터랙티브 명령어들이다.

카테고리	명령어	설명
Git 작업	`commit`, `commit-push-pr`, `diff`, `branch/`, `pr_comments/`	커밋, PR 생성, diff 표시, 브랜치 관리
코드 리뷰	`review`, `security-review`, `bughunter/`	코드/보안 리뷰, 버그 헌팅
컨텍스트	`context/`, `compact/`, `add-dir/`, `files/`	컨텍스트 확인/축소, 디렉토리/파일 추가
설정	`config/`, `theme/`, `color/`, `model/`, `effort/`, `output-style/`, `permissions/`	모델, 테마, 컬러, 노력 수준, 권한 설정
세션	`session/`, `resume/`, `share/`, `export/`, `clear/`	세션 관리, 재개, 공유, 내보내기, 초기화
MCP	`mcp/`, `reload-plugins/`	MCP 서버 관리, 플러그인 리로드
메모리	`memory/`	메모리 파일 관리
에이전트	`agents/`, `tasks/`	에이전트/태스크 관리
IDE	`ide/`, `desktop/`, `chrome/`	IDE/데스크톱/Chrome 연동
시스템	`doctor/`, `status/`, `version`, `help/`, `stats/`, `cost/`, `usage/`	진단, 상태, 버전, 도움말, 통계, 비용
원격	`bridge/`, `teleport/`, `remote-env/`, `remote-setup/`	원격 브릿지, 텔레포트, 원격 환경
계획	`plan/`, `ultraplan.tsx`	계획 모드, 울트라플랜
설치	`install.tsx`, `install-github-app/`, `install-slack-app/`	셸/앱 설치
기타	`btw/`, `good-claude/`, `feedback/`, `stickers/`, `onboarding/`, `voice/`, `vim/`	피드백, 온보딩, 음성/Vim 전환

4.4 서비스(Services) 계층

`services/` — 핵심 비즈니스 서비스

하위 모듈	설명
`api/`	Claude API 클라이언트. 인증, 요청, 스트리밍, 에러 핸들링, 재시도 로직
`mcp/`	MCP 클라이언트 관리. MCP 서버 연결, 도구/리소스 동기화, 채널 권한, 공식 레지스트리
`analytics/`	분석/텔레메트리. GrowthBook 피처 플래그, Datadog 연동, 이벤트 로깅, 퍼스트파티 이벤트
`lsp/`	LSP(Language Server Protocol) 클라이언트. 코드 분석, 심볼 탐색, 진단
`oauth/`	OAuth 인증 플로우. 토큰 관리, 계정 정보
`compact/`	컨텍스트 압축(Compact). 자동/수동 대화 요약으로 토큰 절약
`plugins/`	플러그인 관리 서비스. CLI 명령어, 로드/언로드
`policyLimits/`	정책 제한. 조직/엔터프라이즈 수준 사용 제한
`remoteManagedSettings/`	원격 관리 설정. 관리자 배포 설정 동기화
`settingsSync/`	설정 동기화
`teamMemorySync/`	팀 메모리 동기화
`tips/`	사용 팁/힌트
`AgentSummary/`	에이전트 작업 요약
`MagicDocs/`	문서 자동 참조
`PromptSuggestion/`	프롬프트 제안
`SessionMemory/`	세션 메모리 관리
`extractMemories/`	메모리 자동 추출
`toolUseSummary/`	도구 사용 요약 생성
`autoDream/`	자동 Dream(백그라운드 작업)
`tools/`	도구 관련 서비스 헬퍼
기타	`rateLimitMessages.ts`, `tokenEstimation.ts`, `claudeAiLimits.ts`, `voiceStreamSTT.ts` 등

4.5 브릿지(Bridge) 시스템

`bridge/` — 원격 세션 연동

Claude Code와 claude.ai 웹 인터페이스를 연결하는 양방향 브릿지 시스템이다.

파일	설명
`bridgeMain.ts`	브릿지 메인 루프. 세션 생성, 폴링, 재연결, 용량 조절
`bridgeApi.ts`	브릿지 API 클라이언트. 인증, 세션 관리 REST 호출
`bridgeMessaging.ts`	인바운드/아웃바운드 메시지 처리
`bridgeConfig.ts`	브릿지 설정 로드/관리
`bridgePermissionCallbacks.ts`	원격 사용자 권한 요청 콜백
`bridgeUI.ts`	브릿지 상태 로깅/UI 표시
`replBridge.ts` / `replBridgeHandle.ts`	REPL 내 브릿지 통합
`sessionRunner.ts`	원격 세션 자식 프로세스 관리
`jwtUtils.ts`	JWT 토큰 스케줄링/갱신
`trustedDevice.ts`	신뢰 디바이스 토큰
`workSecret.ts`	작업 시크릿(SDK URL) 생성/검증
`inboundMessages.ts` / `inboundAttachments.ts`	수신 메시지/첨부 파일 처리
`pollConfig.ts` / `pollConfigDefaults.ts`	폴링 간격 설정
`capacityWake.ts`	용량 기반 웨이크업
`flushGate.ts`	메시지 플러시 게이트
`sessionIdCompat.ts`	세션 ID 호환성 변환
`remoteBridgeCore.ts`	원격 브릿지 핵심 로직

4.6 상태 관리(State)

`state/` — 앱 상태 관리

파일	설명
`AppState.tsx`	`AppStateProvider` React 컨텍스트 제공자. 상태 변경 감지 및 설정 배포
`AppStateStore.ts`	`AppState` 타입 정의. 메시지, 도구 권한, MCP 연결, 플러그인, 태스크, 팀원, 워크트리, 알림 등 애플리케이션 전체 상태를 단일 객체로 관리
`store.ts`	커스텀 상태 저장소 구현 (`zustand` 스타일 구독 패턴)
`selectors.ts`	상태 선택자(Selector) 함수
`onChangeAppState.ts`	상태 변경 시 사이드이펙트 처리
`teammateViewHelpers.ts`	팀원 뷰 헬퍼

`bootstrap/state.ts` — 부트스트랩 전역 상태

세션 ID, 비용 카운터, 토큰 카운터, 모델 사용량 등 부트스트랩 시점에 초기화되는 전역 상태를 보관한다. AppState와는 별도로 런타임 전반에 걸쳐 사용되는 원시 카운터/플래그들이다.

4.7 태스크(Task) 시스템

`tasks/` — 백그라운드 태스크 실행기

모듈	설명
`LocalShellTask/`	로컬 Bash 셸 명령 실행
`LocalAgentTask/`	로컬 서브 에이전트 실행 (독립 컨텍스트)
`RemoteAgentTask/`	원격 에이전트 실행
`InProcessTeammateTask/`	인 프로세스 팀원(스웜) 에이전트
`DreamTask/`	Dream(백그라운드 자율 작업) 태스크
`LocalMainSessionTask.ts`	로컬 메인 세션 태스크
`types.ts`	`TaskState` 통합 타입 (각 태스크 유형별 상태)
`pillLabel.ts`	태스크 상태 표시 라벨
`stopTask.ts`	태스크 종료 로직

태스크 유형:

local_bash — 셸 명령 실행
local_agent — 로컬 서브 에이전트
remote_agent — 원격 에이전트
in_process_teammate — 프로세스 내 팀원
local_workflow — 로컬 워크플로우
monitor_mcp — MCP 모니터링
dream — 자율 백그라운드 작업

4.8 CLI / 진입점(Entrypoints)

`entrypoints/` — 실행 모드별 진입점

파일	설명
`cli.tsx`	CLI 모드 진입점 (대화형/비대화형)
`init.ts`	초기화 로직. 텔레메트리, OAuth, 정책, CA 인증서, 프록시 등
`mcp.ts`	MCP 서버 모드 진입점. Claude Code를 MCP 서버로 구동
`sdk/`	Agent SDK 타입/스키마. SDK 메시지, 제어 메시지, 핵심 타입 정의
`agentSdkTypes.ts`	SDK 관련 타입 (SDKMessage, SDKStatus, ModelUsage 등)
`sandboxTypes.ts`	샌드박스 관련 타입

`cli/` — CLI 인프라

파일/폴더	설명
`handlers/`	CLI 서브커맨드 핸들러 (`agents`, `auth`, `autoMode`, `mcp`, `plugins`)
`transports/`	이벤트 전송 계층: `WebSocketTransport`, `SSETransport`, `HybridTransport`, `SerialBatchEventUploader`
`print.ts`	CLI 출력 포맷팅
`structuredIO.ts`	구조화된 NDJSON 입출력
`remoteIO.ts`	원격 입출력
`exit.ts`	종료 처리
`update.ts`	자동 업데이트

4.9 유틸리티(Utils)

`utils/` — 범용 유틸리티 (300+ 파일)

프로젝트 전반에서 사용되는 방대한 유틸리티 모음이다.

카테고리	주요 파일/폴더	설명
인증	`auth.ts`, `aws.ts`, `secureStorage/`, `authPortable.ts`	API 키, OAuth, AWS 자격증명, 키체인 스토리지
설정	`config.ts`, `settings/`, `configConstants.ts`, `managedEnv.ts`	전역/프로젝트 설정, MDM 관리 설정
모델	`model/`, `modelCost.ts`, `effort.ts`, `fastMode.ts`, `thinking.ts`	모델 선택, 비용 계산, 노력 수준, Fast 모드, 사고(Thinking)
Git	`git.ts`, `git/`, `gitDiff.ts`, `gitSettings.ts`, `worktree.ts`	Git 작업, diff, 워크트리 관리
파일 시스템	`file.ts`, `fileRead.ts`, `fileReadCache.ts`, `fsOperations.ts`, `filePersistence/`	파일 읽기/쓰기/캐싱
셸	`Shell.ts`, `ShellCommand.ts`, `bash/`, `shell/`, `powershell/`	셸 프로세스 관리, 명령 실행
권한	`permissions/`, `classifierApprovals.ts`, `autoModeDenials.ts`	도구 실행 권한, 자동 승인 분류기
텔레메트리	`telemetry/`, `telemetryAttributes.ts`, `diagLogs.ts`	OpenTelemetry 계측, 진단 로그
포맷팅	`format.ts`, `markdown.ts`, `diff.ts`, `cliHighlight.ts`, `ansiToPng.ts`, `ansiToSvg.ts`	텍스트/마크다운/diff 포맷팅, 이미지 변환
메시지	`messages.ts`, `messages/`, `messageQueueManager.ts`, `contentArray.ts`	메시지 생성/변환/큐 관리
컨텍스트	`context.ts`, `contextAnalysis.ts`, `contextSuggestions.ts`, `queryContext.ts`	컨텍스트 분석, 시스템 프롬프트 구성
프로세스	`process.ts`, `genericProcessUtils.ts`, `subprocessEnv.ts`	프로세스 관리, 환경 변수
이미지	`imageResizer.ts`, `imageStore.ts`, `imageValidation.ts`, `imagePaste.ts`	이미지 처리/검증
네트워크	`http.ts`, `proxy.ts`, `caCerts.ts`, `mtls.ts`, `mcpWebSocketTransport.ts`	HTTP, 프록시, CA 인증서, mTLS
MCP	`mcp/`, `mcpValidation.ts`, `mcpOutputStorage.ts`	MCP 유틸리티
플러그인	`plugins/`	플러그인 로더, 관리 유틸리티
스킬	`skills/`	스킬 변경 감지, 로더
스웜(팀)	`swarm/`, `teammate.ts`, `teammateContext.ts`, `teammateMailbox.ts`	다중 에이전트 스웜 인프라
텔레포트	`teleport/`, `teleport.tsx`	세션 텔레포트 (환경 간 이동)
IDE	`ide.ts`, `idePathConversion.ts`, `jetbrains.ts`, `claudeDesktop.ts`	IDE 연동 유틸리티
훅(Hooks)	`hooks.ts`, `hooks/`	pre/post 패치 훅, 파일 변경 감지
크론	`cron.ts`, `cronScheduler.ts`, `cronTasks.ts`	크론 작업 스케줄링
메모리	`memory/`	메모리 파일 관리 유틸리티
TODO	`todo/`	TODO 리스트 관리
태스크	`task/`	태스크 디스크 출력, 유틸리티
기타	`uuid.ts`, `sleep.ts`, `memoize.ts`, `array.ts`, `json.ts`, `xml.ts`, `yaml.ts`, `crypto.ts`, `semver.ts` 등	범용 헬퍼

4.10 플러그인 / 스킬 시스템

`plugins/` — 플러그인 시스템

파일/폴더	설명
`builtinPlugins.ts`	빌트인 플러그인 정의
`bundled/index.ts`	번들 플러그인 초기화

플러그인은 추가 도구와 명령어를 제공하며, MCP 서버로도 동작할 수 있다. services/plugins/에서 로딩/관리가 이루어진다.

`skills/` — 스킬 시스템

파일/폴더	설명
`bundled/`	번들 스킬 정의
`bundledSkills.ts`	번들 스킬 레지스트리
`loadSkillsDir.ts`	스킬 디렉토리 로더
`mcpSkillBuilders.ts`	MCP 기반 스킬 빌더

스킬은 특정 도메인의 코드 생성/작업을 위한 템플릿화된 워크플로우이다.

4.11 MCP (Model Context Protocol)

MCP 관련 코드는 여러 위치에 분산되어 있다:

services/mcp/ — MCP 클라이언트 매니저, 서버 연결 관리, 타입 정의 (types.ts에 McpStdioServerConfig, McpSSEServerConfig 등)
tools/MCPTool/ — Claude가 MCP 서버 도구를 호출하는 도구
tools/ListMcpResourcesTool/, ReadMcpResourceTool/ — MCP 리소스 열람
tools/McpAuthTool/ — MCP OAuth 인증
commands/mcp/ — MCP 서버 관리 슬래시 명령어
components/mcp/ — MCP 관련 UI 컴포넌트
entrypoints/mcp.ts — Claude Code를 MCP 서버로 실행
utils/mcp/ — MCP 유틸리티

지원 전송 방식: stdio, sse, sse-ide, http, ws, sdk

4.12 Ink 터미널 렌더링 엔진

`ink/` — 커스텀 React Ink 포크

표준 Ink 라이브러리를 프로젝트 내에 포크/확장한 커스텀 터미널 렌더링 엔진이다.

영역	주요 파일	설명
렌더링 코어	`reconciler.ts`, `renderer.ts`, `render-node-to-output.ts`, `render-to-screen.ts`	React 재조정기, 노드→출력 변환
레이아웃	`layout/`, `measure-element.ts`, `measure-text.ts`	Yoga 기반 Flexbox 레이아웃
텍스트 처리	`stringWidth.ts`, `wrap-text.ts`, `wrapAnsi.ts`, `squash-text-nodes.ts`, `tabstops.ts`	문자열 너비 계산, 줄바꿈, ANSI 처리
터미널 I/O	`termio/`, `termio.ts`, `terminal.ts`, `terminal-querier.ts`	터미널 입출력, DEC 이스케이프 시퀀스
입력 처리	`parse-keypress.ts`, `focus.ts`, `events/`	키 입력 파싱, 포커스 관리
최적화	`optimizer.ts`, `node-cache.ts`, `line-width-cache.ts`	렌더링 최적화, 캐싱
기타	`colorize.ts`, `bidi.ts`, `searchHighlight.ts`, `selection.ts`, `screen.ts`	컬러, 양방향 텍스트, 검색 하이라이팅

4.13 키바인딩(Keybindings)

`keybindings/` — 단축키 시스템

파일	설명
`KeybindingContext.tsx`	키바인딩 React 컨텍스트
`defaultBindings.ts`	기본 단축키 정의
`loadUserBindings.ts`	사용자 커스텀 단축키 로드
`parser.ts` / `match.ts`	키 조합 파싱/매칭
`resolver.ts`	키바인딩 해석기
`schema.ts` / `validate.ts`	스키마 정의, 유효성 검증
`reservedShortcuts.ts`	예약된 단축키 목록
`template.ts`	키바인딩 설정 템플릿 생성

4.14 메모리(Memory) 시스템

`memdir/` — 메모리 디렉토리 관리

파일	설명
`memdir.ts`	메모리 프롬프트 로드/관리
`findRelevantMemories.ts`	관련 메모리 탐색
`memoryScan.ts`	메모리 파일 스캔
`memoryAge.ts`	메모리 수명 관리
`memoryTypes.ts`	메모리 타입 정의
`paths.ts`	메모리 파일 경로 (`CLAUDE.md` 등)
`teamMemPaths.ts` / `teamMemPrompts.ts`	팀 메모리 경로/프롬프트

CLAUDE.md 파일을 통한 프로젝트별 지시사항, 사용자 메모리, 세션 메모리 등 다계층 메모리를 관리한다.

4.15 원격(Remote) 세션

`remote/` — 원격 세션 관리

파일	설명
`RemoteSessionManager.ts`	원격 세션 매니저
`SessionsWebSocket.ts`	세션 WebSocket 연결
`remotePermissionBridge.ts`	원격 권한 브릿지
`sdkMessageAdapter.ts`	SDK 메시지 어댑터

4.16 Vim 모드

`vim/` — Vim 에뮬레이션

파일	설명
`types.ts`	Vim 상태/모드 타입 (Normal, Insert, Visual 등)
`motions.ts`	이동 명령 (w, b, e, 0, $, f, t 등)
`operators.ts`	연산자 (d, c, y 등)
`textObjects.ts`	텍스트 객체 (iw, aw, i", a( 등)
`transitions.ts`	모드 전환 로직

4.17 음성(Voice) 모드

`voice/` — 음성 입력

파일	설명
`voiceModeEnabled.ts`	음성 모드 활성화 여부

음성 관련 서비스 로직은 services/voice.ts, services/voiceStreamSTT.ts, services/voiceKeyterms.ts에 분산되어 있다. Feature flag(VOICE_MODE)로 게이트된다.

4.18 마이그레이션(Migrations)

`migrations/` — 설정/상태 마이그레이션

파일	설명
`migrateFennecToOpus.ts`	모델명 마이그레이션 (Fennec → Opus)
`migrateSonnet45ToSonnet46.ts`	Sonnet 4.5 → 4.6 마이그레이션
`migrateAutoUpdatesToSettings.ts`	자동 업데이트 설정 마이그레이션
`migrateBypassPermissionsAcceptedToSettings.ts`	권한 우회 설정 마이그레이션
`resetAutoModeOptInForDefaultOffer.ts`	자동 모드 옵트인 리셋
기타	레거시 설정 형식 → 현재 형식 변환

4.19 기타 모듈

모듈	설명
`coordinator/`	코디네이터 모드 (`coordinatorMode.ts`). 다중 에이전트 오케스트레이션 (feature flag: `COORDINATOR_MODE`)
`assistant/`	어시스턴트 모드 (`sessionHistory.ts`). 항상 실행되는 데몬 형태 (feature flag: `KAIROS`)
`buddy/`	컴패니언 시스템. 감정 반응 스프라이트(`CompanionSprite.tsx`), 알림(`useBuddyNotification.tsx`)
`context/` (하위)	React 컨텍스트. 메시지 큐, 모달, 오버레이, FPS 메트릭, 음성, 알림, 통계
`constants/`	상수 정의. API 제한, 베타, 에러 컴드, 시스템 프롬프트 섹션, 도구 제한, XML 태그
`types/`	공유 타입 정의. 명령, 생성된 타입, 훅, ID, 로그, 권한, 플러그인, 메시지
`schemas/`	Zod 스키마. 훅 설정 스키마
`native-ts/`	네이티브 TypeScript 바인딩. `color-diff/` (ANSI 색상 diff), `file-index/` (파일 인덱싱), `yoga-layout/` (레이아웃 엔진)
`outputStyles/`	출력 스타일. 커스텀 출력 포맷 로더
`moreright/`	`useMoreRight` 훅 (추가 우측 패널)
`upstreamproxy/`	업스트림 프록시. `relay.ts`, `upstreamproxy.ts` — HTTP(S) 프록시 릴레이
`query/`	쿼리 설정. `config.ts`, `deps.ts`, `stopHooks.ts`, `tokenBudget.ts`

5. 기술 스택 요약

영역	기술
런타임	Bun
언어	TypeScript (`.ts`, `.tsx`)
UI 프레임워크	React + 커스텀 Ink 포크 (터미널 렌더링)
레이아웃 엔진	Yoga (Flexbox)
CLI 파싱	Commander.js (`@commander-js/extra-typings`)
AI API	Anthropic Claude SDK (`@anthropic-ai/sdk`)
프로토콜	MCP (Model Context Protocol, `@modelcontextprotocol/sdk`)
상태 관리	커스텀 Store (zustand 스타일 구독 패턴)
검증	Zod v4
텔레메트리	OpenTelemetry, Datadog, GrowthBook (Feature Flags)
빌드	`bun:bundle` (Feature flag 기반 Dead Code Elimination)
전송	WebSocket, SSE, stdio (MCP 전송)
코드 분석	LSP (Language Server Protocol)
버전 관리	Git 연동 (worktree, diff, commit attribution)
인증	OAuth, API Key, AWS Credentials, JWT
보안	샌드박스, 권한 분류기, mTLS, CA 인증서

페이지 트리

Claude Code 소스 코드 분석

Claude Code 소스 코드 분석

목차

1. 프로젝트 개요

2. 아키텍처 개관

3. 최상위 핵심 모듈

4. 주요 카테고리별 상세 분석

4.1 UI / 렌더링 계층

components/ — React Ink 컴포넌트 (100+ 파일)

screens/ — 화면 단위 컴포넌트

hooks/ — React 커스텀 훅 (80+ 파일)

4.2 도구(Tool) 시스템

tools/ — 개별 도구 구현 (40+ 도구)

4.3 명령어(Command) 시스템

commands/ — 슬래시 명령어 (90+ 명령어)

4.4 서비스(Services) 계층

services/ — 핵심 비즈니스 서비스

4.5 브릿지(Bridge) 시스템

bridge/ — 원격 세션 연동

4.6 상태 관리(State)

state/ — 앱 상태 관리

bootstrap/state.ts — 부트스트랩 전역 상태

4.7 태스크(Task) 시스템

tasks/ — 백그라운드 태스크 실행기

4.8 CLI / 진입점(Entrypoints)

entrypoints/ — 실행 모드별 진입점

cli/ — CLI 인프라

4.9 유틸리티(Utils)

utils/ — 범용 유틸리티 (300+ 파일)

4.10 플러그인 / 스킬 시스템

plugins/ — 플러그인 시스템

skills/ — 스킬 시스템

4.11 MCP (Model Context Protocol)

4.12 Ink 터미널 렌더링 엔진

ink/ — 커스텀 React Ink 포크

4.13 키바인딩(Keybindings)

keybindings/ — 단축키 시스템

4.14 메모리(Memory) 시스템

memdir/ — 메모리 디렉토리 관리

4.15 원격(Remote) 세션

remote/ — 원격 세션 관리

4.16 Vim 모드

vim/ — Vim 에뮬레이션

4.17 음성(Voice) 모드

voice/ — 음성 입력

4.18 마이그레이션(Migrations)

migrations/ — 설정/상태 마이그레이션

4.19 기타 모듈

5. 기술 스택 요약

`components/` — React Ink 컴포넌트 (100+ 파일)

`screens/` — 화면 단위 컴포넌트

`hooks/` — React 커스텀 훅 (80+ 파일)

`tools/` — 개별 도구 구현 (40+ 도구)

`commands/` — 슬래시 명령어 (90+ 명령어)

`services/` — 핵심 비즈니스 서비스

`bridge/` — 원격 세션 연동

`state/` — 앱 상태 관리

`bootstrap/state.ts` — 부트스트랩 전역 상태

`tasks/` — 백그라운드 태스크 실행기

`entrypoints/` — 실행 모드별 진입점

`cli/` — CLI 인프라

`utils/` — 범용 유틸리티 (300+ 파일)

`plugins/` — 플러그인 시스템

`skills/` — 스킬 시스템

`ink/` — 커스텀 React Ink 포크

`keybindings/` — 단축키 시스템

`memdir/` — 메모리 디렉토리 관리

`remote/` — 원격 세션 관리

`vim/` — Vim 에뮬레이션

`voice/` — 음성 입력

`migrations/` — 설정/상태 마이그레이션