docs: rewrite README in English

README.md

@@ -1,244 +1,246 @@
-# cczip — Claude Code Source Analysis
+# Claude Code — Source Analysis
 
-> Anthropic의 공식 CLI 도구인 **Claude Code**의 소스코드를 분석하기 위한 레포지토리입니다.
+> An archive of [Anthropic](https://www.anthropic.com)'s official CLI tool **Claude Code** source code, for analysis and educational purposes.
 >
-> 참고: [트윗 원문](https://x.com/Fried_rice/status/2038894956459290963)
+> Reference: [Original tweet](https://x.com/Fried_rice/status/2038894956459290963)
 
 ---
 
-## 개요
+## Overview
 
-Claude Code는 터미널에서 직접 Claude와 대화하며 소프트웨어 엔지니어링 작업을 수행할 수 있는 CLI 도구입니다. 이 레포는 해당 도구의 `src/` 디렉토리를 분석 목적으로 아카이빙한 것입니다.
+Claude Code is a CLI tool that lets you interact with Claude directly from the terminal to perform software engineering tasks — editing files, running commands, searching codebases, managing git workflows, and more.
 
-- **언어**: TypeScript
-- **런타임**: Bun
-- **터미널 UI**: React + [Ink](https://github.com/vadimdemedes/ink) (React for CLI)
-- **규모**: 약 1,900개 파일, 512,000+ 라인
+This repository contains the `src/` directory extracted for study.
+
+- **Language**: TypeScript
+- **Runtime**: Bun
+- **Terminal UI**: React + [Ink](https://github.com/vadimdemedes/ink) (React for CLI)
+- **Scale**: ~1,900 files, 512,000+ lines of code
 
 ---
 
-## 디렉토리 구조
+## Directory Structure
 
 ```
 src/
-├── main.tsx                 # 엔트리포인트 (Commander.js 기반 CLI 파싱)
-├── commands.ts              # 커맨드 레지스트리
-├── tools.ts                 # 툴 레지스트리
-├── Tool.ts                  # 툴 타입 정의
-├── QueryEngine.ts           # LLM 쿼리 엔진 (Anthropic API 호출 핵심)
-├── context.ts               # 시스템/유저 컨텍스트 수집
-├── cost-tracker.ts          # 토큰 비용 추적
+├── main.tsx                 # Entrypoint (Commander.js-based CLI parser)
+├── commands.ts              # Command registry
+├── tools.ts                 # Tool registry
+├── Tool.ts                  # Tool type definitions
+├── QueryEngine.ts           # LLM query engine (core Anthropic API caller)
+├── context.ts               # System/user context collection
+├── cost-tracker.ts          # Token cost tracking
 │
-├── commands/                # 슬래시 커맨드 구현 (~50개)
-├── tools/                   # 에이전트 툴 구현 (~40개)
-├── components/              # Ink UI 컴포넌트 (~140개)
-├── hooks/                   # React 훅
-├── services/                # 외부 서비스 연동
-├── screens/                 # 전체 화면 UI (Doctor, REPL, Resume)
-├── types/                   # TypeScript 타입 정의
-├── utils/                   # 유틸리티 함수
+├── commands/                # Slash command implementations (~50)
+├── tools/                   # Agent tool implementations (~40)
+├── components/              # Ink UI components (~140)
+├── hooks/                   # React hooks
+├── services/                # External service integrations
+├── screens/                 # Full-screen UIs (Doctor, REPL, Resume)
+├── types/                   # TypeScript type definitions
+├── utils/                   # Utility functions
 │
-├── bridge/                  # IDE 연동 브릿지 (VS Code, JetBrains)
-├── coordinator/             # 멀티 에이전트 코디네이터
-├── plugins/                 # 플러그인 시스템
-├── skills/                  # 스킬 시스템
-├── keybindings/             # 키바인딩 설정
-├── vim/                     # Vim 모드
-├── voice/                   # 음성 입력
-├── remote/                  # 원격 세션
-├── server/                  # 서버 모드
-├── memdir/                  # 메모리 디렉토리 (영속 기억)
-├── tasks/                   # 태스크 관리
-├── state/                   # 상태 관리
-├── migrations/              # 설정 마이그레이션
-├── schemas/                 # 설정 스키마 (Zod)
-├── entrypoints/             # 초기화 로직
-├── ink/                     # Ink 렌더러 래퍼
-├── buddy/                   # 컴패니언 스프라이트 (Easter egg)
-├── native-ts/               # 네이티브 타입스크립트 유틸
-├── outputStyles/            # 출력 스타일링
-├── query/                   # 쿼리 파이프라인
-└── upstreamproxy/           # 프록시 설정
+├── bridge/                  # IDE integration bridge (VS Code, JetBrains)
+├── coordinator/             # Multi-agent coordinator
+├── plugins/                 # Plugin system
+├── skills/                  # Skill system
+├── keybindings/             # Keybinding configuration
+├── vim/                     # Vim mode
+├── voice/                   # Voice input
+├── remote/                  # Remote sessions
+├── server/                  # Server mode
+├── memdir/                  # Memory directory (persistent memory)
+├── tasks/                   # Task management
+├── state/                   # State management
+├── migrations/              # Config migrations
+├── schemas/                 # Config schemas (Zod)
+├── entrypoints/             # Initialization logic
+├── ink/                     # Ink renderer wrapper
+├── buddy/                   # Companion sprite (Easter egg)
+├── native-ts/               # Native TypeScript utils
+├── outputStyles/            # Output styling
+├── query/                   # Query pipeline
+└── upstreamproxy/           # Proxy configuration
 ```
 
 ---
 
-## 핵심 아키텍처
+## Core Architecture
 
-### 1. 툴 시스템 (`src/tools/`)
+### 1. Tool System (`src/tools/`)
 
-Claude Code가 사용하는 모든 도구의 구현체입니다. 각 툴은 독립적인 디렉토리에 정의되어 있습니다.
+Every tool Claude Code can invoke is implemented as a self-contained module. Each tool defines its input schema, permission model, and execution logic.
 
-| 툴 | 설명 |
+| Tool | Description |
 |---|---|
-| `BashTool` | 셸 명령 실행 |
-| `FileReadTool` | 파일 읽기 (이미지, PDF, 노트북 포함) |
-| `FileWriteTool` | 파일 생성/덮어쓰기 |
-| `FileEditTool` | 파일 부분 수정 (string replacement) |
-| `GlobTool` | 파일 패턴 매칭 검색 |
-| `GrepTool` | ripgrep 기반 콘텐츠 검색 |
-| `WebFetchTool` | URL 콘텐츠 가져오기 |
-| `WebSearchTool` | 웹 검색 |
-| `AgentTool` | 서브에이전트 생성 |
-| `SkillTool` | 스킬 실행 |
-| `MCPTool` | MCP 서버 툴 호출 |
-| `LSPTool` | Language Server Protocol 연동 |
-| `NotebookEditTool` | Jupyter 노트북 편집 |
-| `TaskCreateTool` / `TaskUpdateTool` | 태스크 생성/관리 |
-| `SendMessageTool` | 에이전트 간 메시지 전송 |
-| `TeamCreateTool` / `TeamDeleteTool` | 팀 에이전트 관리 |
-| `EnterPlanModeTool` / `ExitPlanModeTool` | 계획 모드 전환 |
-| `EnterWorktreeTool` / `ExitWorktreeTool` | Git worktree 격리 |
-| `ToolSearchTool` | 지연 로드된 툴 검색 |
-| `CronCreateTool` | 스케줄 트리거 생성 |
-| `RemoteTriggerTool` | 원격 트리거 |
-| `SleepTool` | 프로액티브 모드 대기 |
-| `SyntheticOutputTool` | 구조화된 출력 생성 |
+| `BashTool` | Shell command execution |
+| `FileReadTool` | File reading (images, PDFs, notebooks) |
+| `FileWriteTool` | File creation / overwrite |
+| `FileEditTool` | Partial file modification (string replacement) |
+| `GlobTool` | File pattern matching search |
+| `GrepTool` | ripgrep-based content search |
+| `WebFetchTool` | Fetch URL content |
+| `WebSearchTool` | Web search |
+| `AgentTool` | Sub-agent spawning |
+| `SkillTool` | Skill execution |
+| `MCPTool` | MCP server tool invocation |
+| `LSPTool` | Language Server Protocol integration |
+| `NotebookEditTool` | Jupyter notebook editing |
+| `TaskCreateTool` / `TaskUpdateTool` | Task creation and management |
+| `SendMessageTool` | Inter-agent messaging |
+| `TeamCreateTool` / `TeamDeleteTool` | Team agent management |
+| `EnterPlanModeTool` / `ExitPlanModeTool` | Plan mode toggle |
+| `EnterWorktreeTool` / `ExitWorktreeTool` | Git worktree isolation |
+| `ToolSearchTool` | Deferred tool discovery |
+| `CronCreateTool` | Scheduled trigger creation |
+| `RemoteTriggerTool` | Remote trigger |
+| `SleepTool` | Proactive mode wait |
+| `SyntheticOutputTool` | Structured output generation |
 
-### 2. 커맨드 시스템 (`src/commands/`)
+### 2. Command System (`src/commands/`)
 
-사용자가 `/`로 시작하는 슬래시 커맨드입니다.
+User-facing slash commands invoked with `/` prefix.
 
-| 커맨드 | 설명 |
+| Command | Description |
 |---|---|
-| `/commit` | Git 커밋 생성 |
-| `/review` | 코드 리뷰 |
-| `/compact` | 컨텍스트 압축 |
-| `/mcp` | MCP 서버 관리 |
-| `/config` | 설정 관리 |
-| `/doctor` | 환경 진단 |
-| `/login` / `/logout` | 인증 |
-| `/memory` | 영속 기억 관리 |
-| `/skills` | 스킬 관리 |
-| `/tasks` | 태스크 관리 |
-| `/vim` | Vim 모드 토글 |
-| `/diff` | 변경사항 확인 |
-| `/cost` | 비용 확인 |
-| `/theme` | 테마 변경 |
-| `/context` | 컨텍스트 시각화 |
-| `/pr_comments` | PR 코멘트 확인 |
-| `/resume` | 이전 세션 복원 |
-| `/share` | 세션 공유 |
-| `/desktop` | 데스크톱 앱 연결 |
-| `/mobile` | 모바일 앱 연결 |
+| `/commit` | Create a git commit |
+| `/review` | Code review |
+| `/compact` | Context compression |
+| `/mcp` | MCP server management |
+| `/config` | Settings management |
+| `/doctor` | Environment diagnostics |
+| `/login` / `/logout` | Authentication |
+| `/memory` | Persistent memory management |
+| `/skills` | Skill management |
+| `/tasks` | Task management |
+| `/vim` | Vim mode toggle |
+| `/diff` | View changes |
+| `/cost` | Check usage cost |
+| `/theme` | Change theme |
+| `/context` | Context visualization |
+| `/pr_comments` | View PR comments |
+| `/resume` | Restore previous session |
+| `/share` | Share session |
+| `/desktop` | Desktop app handoff |
+| `/mobile` | Mobile app handoff |
 
-### 3. 서비스 레이어 (`src/services/`)
+### 3. Service Layer (`src/services/`)
 
-| 서비스 | 설명 |
+| Service | Description |
 |---|---|
-| `api/` | Anthropic API 클라이언트, 파일 API, 부트스트랩 |
-| `mcp/` | Model Context Protocol 서버 연결 및 관리 |
-| `oauth/` | OAuth 2.0 인증 플로우 |
-| `lsp/` | Language Server Protocol 매니저 |
-| `analytics/` | GrowthBook 기반 피처 플래그 및 분석 |
-| `plugins/` | 플러그인 로더 |
-| `compact/` | 대화 컨텍스트 압축 |
-| `policyLimits/` | 조직 정책 제한 |
-| `remoteManagedSettings/` | 원격 관리 설정 |
-| `extractMemories/` | 자동 기억 추출 |
-| `tokenEstimation.ts` | 토큰 수 추정 |
-| `teamMemorySync/` | 팀 메모리 동기화 |
+| `api/` | Anthropic API client, file API, bootstrap |
+| `mcp/` | Model Context Protocol server connection and management |
+| `oauth/` | OAuth 2.0 authentication flow |
+| `lsp/` | Language Server Protocol manager |
+| `analytics/` | GrowthBook-based feature flags and analytics |
+| `plugins/` | Plugin loader |
+| `compact/` | Conversation context compression |
+| `policyLimits/` | Organization policy limits |
+| `remoteManagedSettings/` | Remote managed settings |
+| `extractMemories/` | Automatic memory extraction |
+| `tokenEstimation.ts` | Token count estimation |
+| `teamMemorySync/` | Team memory synchronization |
 
-### 4. 브릿지 시스템 (`src/bridge/`)
+### 4. Bridge System (`src/bridge/`)
 
-IDE 확장(VS Code, JetBrains)과 Claude Code CLI를 연결하는 양방향 통신 레이어입니다.
+A bidirectional communication layer connecting IDE extensions (VS Code, JetBrains) with the Claude Code CLI.
 
-- `bridgeMain.ts` — 브릿지 메인 루프
-- `bridgeMessaging.ts` — 메시지 프로토콜
-- `bridgePermissionCallbacks.ts` — 권한 콜백
-- `replBridge.ts` — REPL 세션 브릿지
-- `jwtUtils.ts` — JWT 기반 인증
-- `sessionRunner.ts` — 세션 실행 관리
+- `bridgeMain.ts` — Bridge main loop
+- `bridgeMessaging.ts` — Message protocol
+- `bridgePermissionCallbacks.ts` — Permission callbacks
+- `replBridge.ts` — REPL session bridge
+- `jwtUtils.ts` — JWT-based authentication
+- `sessionRunner.ts` — Session execution management
 
-### 5. 권한 시스템 (`src/hooks/toolPermission/`)
+### 5. Permission System (`src/hooks/toolPermission/`)
 
-모든 툴 호출에 대해 권한을 검사하는 시스템입니다. 사용자에게 승인/거부를 요청하거나, 설정된 권한 모드(`default`, `plan`, `bypassPermissions`, `auto` 등)에 따라 자동으로 처리합니다.
+Checks permissions on every tool invocation. Either prompts the user for approval/denial or automatically resolves based on the configured permission mode (`default`, `plan`, `bypassPermissions`, `auto`, etc.).
 
-### 6. 피처 플래그
+### 6. Feature Flags
 
-Bun의 `bun:bundle` feature flag를 활용한 데드코드 제거:
+Dead code elimination via Bun's `bun:bundle` feature flags:
 
 ```typescript
 import { feature } from 'bun:bundle'
 
-// 빌드 시점에 비활성 코드를 완전히 제거
+// Inactive code is completely stripped at build time
 const voiceCommand = feature('VOICE_MODE')
   ? require('./commands/voice/index.js').default
   : null
 ```
 
-주요 피처 플래그: `PROACTIVE`, `KAIROS`, `BRIDGE_MODE`, `DAEMON`, `VOICE_MODE`, `AGENT_TRIGGERS`, `MONITOR_TOOL` 등
+Notable flags: `PROACTIVE`, `KAIROS`, `BRIDGE_MODE`, `DAEMON`, `VOICE_MODE`, `AGENT_TRIGGERS`, `MONITOR_TOOL`
 
 ---
 
-## 주요 파일 상세
+## Key Files in Detail
 
-### `QueryEngine.ts` (~46K 라인)
+### `QueryEngine.ts` (~46K lines)
 
-LLM API 호출의 핵심 엔진입니다. 스트리밍 응답 처리, 툴 호출 루프, thinking 모드, 재시도 로직, 토큰 카운팅 등을 담당합니다.
+The core engine for LLM API calls. Handles streaming responses, tool-call loops, thinking mode, retry logic, and token counting.
 
-### `Tool.ts` (~29K 라인)
+### `Tool.ts` (~29K lines)
 
-모든 툴의 기본 타입과 인터페이스를 정의합니다. 툴 입력 스키마, 권한 모델, 진행 상태 타입 등이 포함됩니다.
+Defines base types and interfaces for all tools — input schemas, permission models, and progress state types.
 
-### `commands.ts` (~25K 라인)
+### `commands.ts` (~25K lines)
 
-모든 슬래시 커맨드의 등록과 실행을 관리합니다. 조건부 임포트를 통해 환경별로 다른 커맨드 세트를 로드합니다.
+Manages registration and execution of all slash commands. Uses conditional imports to load different command sets per environment.
 
 ### `main.tsx`
 
-Commander.js 기반의 CLI 파서 + React/Ink 렌더러 초기화. 시작 시 MDM 설정, 키체인 프리페치, GrowthBook 초기화 등을 병렬로 수행합니다.
+Commander.js-based CLI parser + React/Ink renderer initialization. At startup, parallelizes MDM settings, keychain prefetch, and GrowthBook initialization for faster boot.
 
 ---
 
-## 기술 스택
+## Tech Stack
 
-| 카테고리 | 기술 |
+| Category | Technology |
 |---|---|
-| 런타임 | [Bun](https://bun.sh) |
-| 언어 | TypeScript (strict) |
-| 터미널 UI | [React](https://react.dev) + [Ink](https://github.com/vadimdemedes/ink) |
-| CLI 파싱 | [Commander.js](https://github.com/tj/commander.js) (extra-typings) |
-| 스키마 검증 | [Zod v4](https://zod.dev) |
-| 검색 | [ripgrep](https://github.com/BurntSushi/ripgrep) (Grep 툴) |
-| 프로토콜 | [MCP SDK](https://modelcontextprotocol.io), LSP |
+| Runtime | [Bun](https://bun.sh) |
+| Language | TypeScript (strict) |
+| Terminal UI | [React](https://react.dev) + [Ink](https://github.com/vadimdemedes/ink) |
+| CLI Parsing | [Commander.js](https://github.com/tj/commander.js) (extra-typings) |
+| Schema Validation | [Zod v4](https://zod.dev) |
+| Code Search | [ripgrep](https://github.com/BurntSushi/ripgrep) (via GrepTool) |
+| Protocols | [MCP SDK](https://modelcontextprotocol.io), LSP |
 | API | [Anthropic SDK](https://docs.anthropic.com) |
-| 텔레메트리 | OpenTelemetry + gRPC |
-| 피처 플래그 | GrowthBook |
-| 인증 | OAuth 2.0, JWT, macOS Keychain |
+| Telemetry | OpenTelemetry + gRPC |
+| Feature Flags | GrowthBook |
+| Auth | OAuth 2.0, JWT, macOS Keychain |
 
 ---
 
-## 주목할만한 설계 패턴
+## Notable Design Patterns
 
-### 병렬 프리페치
+### Parallel Prefetch
 
-시작 시간을 최적화하기 위해 MDM 설정, 키체인, API preconnect 등을 병렬로 프리페치합니다.
+Startup time is optimized by prefetching MDM settings, keychain reads, and API preconnect in parallel — before heavy module evaluation begins.
 
 ```typescript
-// main.tsx — 모듈 임포트 전에 side-effect로 실행
+// main.tsx — fired as side-effects before other imports
 startMdmRawRead()
 startKeychainPrefetch()
 ```
 
-### 지연 로딩 (Lazy Loading)
+### Lazy Loading
 
-무거운 모듈(OpenTelemetry ~400KB, gRPC ~700KB)은 실제로 필요할 때까지 `import()`로 지연 로딩합니다.
+Heavy modules (OpenTelemetry ~400KB, gRPC ~700KB) are deferred via dynamic `import()` until actually needed.
 
-### 에이전트 스웜
+### Agent Swarms
 
-`AgentTool`을 통해 서브에이전트를 생성하고, `coordinator/`가 멀티에이전트 오케스트레이션을 담당합니다. `TeamCreateTool`로 팀 단위 병렬 작업도 지원합니다.
+Sub-agents are spawned via `AgentTool`, with `coordinator/` handling multi-agent orchestration. `TeamCreateTool` enables team-level parallel work.
 
-### 스킬 시스템
+### Skill System
 
-`skills/` 디렉토리에 재사용 가능한 워크플로우를 정의하고, `SkillTool`로 실행합니다. 사용자가 커스텀 스킬을 추가할 수 있습니다.
+Reusable workflows defined in `skills/` and executed through `SkillTool`. Users can add custom skills.
 
-### 플러그인 아키텍처
+### Plugin Architecture
 
-`plugins/` 를 통해 빌트인 플러그인과 서드파티 플러그인을 로드합니다.
+Built-in and third-party plugins are loaded through the `plugins/` subsystem.
 
 ---
 
-## 라이선스
+## License
 
-이 레포지토리는 분석 및 학습 목적으로만 사용됩니다. 원본 소스코드의 저작권은 [Anthropic](https://www.anthropic.com)에 있습니다.
+This repository is for analysis and educational purposes only. All original source code is copyrighted by [Anthropic](https://www.anthropic.com).