# Claude Code 소스 코드 분석
> **분석 대상**: `src/` 디렉토리 전체
> **분석 일자**: 2026-03-31
---
## 목차
1. [프로젝트 개요](#1-프로젝트-개요)
2. [아키텍처 개관](#2-아키텍처-개관)
3. [최상위 핵심 모듈](#3-최상위-핵심-모듈)
4. [주요 카테고리별 상세 분석](#4-주요-카테고리별-상세-분석)
- 4.1 [UI / 렌더링 계층](#41-ui--렌더링-계층)
- 4.2 [도구(Tool) 시스템](#42-도구tool-시스템)
- 4.3 [명령어(Command) 시스템](#43-명령어command-시스템)
- 4.4 [서비스(Services) 계층](#44-서비스services-계층)
- 4.5 [브릿지(Bridge) 시스템](#45-브릿지bridge-시스템)
- 4.6 [상태 관리(State)](#46-상태-관리state)
- 4.7 [태스크(Task) 시스템](#47-태스크task-시스템)
- 4.8 [CLI / 진입점(Entrypoints)](#48-cli--진입점entrypoints)
- 4.9 [유틸리티(Utils)](#49-유틸리티utils)
- 4.10 [플러그인 / 스킬 시스템](#410-플러그인--스킬-시스템)
- 4.11 [MCP (Model Context Protocol)](#411-mcp-model-context-protocol)
- 4.12 [Ink 터미널 렌더링 엔진](#412-ink-터미널-렌더링-엔진)
- 4.13 [키바인딩(Keybindings)](#413-키바인딩keybindings)
- 4.14 [메모리(Memory) 시스템](#414-메모리memory-시스템)
- 4.15 [원격(Remote) 세션](#415-원격remote-세션)
- 4.16 [Vim 모드](#416-vim-모드)
- 4.17 [음성(Voice) 모드](#417-음성voice-모드)
- 4.18 [마이그레이션(Migrations)](#418-마이그레이션migrations)
- 4.19 [기타 모듈](#419-기타-모듈)
5. [기술 스택 요약](#5-기술-스택-요약)
---
## 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 인증서 |