Reverse Engineering

Claude Code Architecture

앤트로픽(Anthropic)이 만든 개발 도구 'Claude Code'가 내부에서 어떻게 작동하는지 뜯어본 분석 문서입니다. Claude Code는 터미널(검은 명령창)에 명령어를 쳐서 쓰는 프로그램(CLI, 명령줄 도구)입니다. 공개된 소스맵(source map, 배포용으로 압축된 코드를 원래 모습으로 되돌려 볼 수 있게 해 주는 지도 파일)을 실마리 삼아, 겉으로 드러나지 않는 내부 설계를 거꾸로 복원했습니다. 이렇게 남이 만든 완성품을 분해해 구조를 알아내는 작업을 리버스 엔지니어링이라고 합니다. 결과물은 8개 부분으로 나뉜 총 19,380줄 분량이며, 사실 확인을 8번 반복해 마쳤습니다.

~1,900
Source Files
512K+
Lines of Code
8
Design Docs
19,380
Doc Lines
System Overview
Architecture Layers
Claude Code CLI — TypeScript Strict · Bun · ESM-only
Terminal UI
React 19component tree
Ink (custom fork)96 files
Yoga WASMflexbox layout
Commander.jsCLI parser
346 .tsxcomponents
85+ hookscustom hooks
Core Engine
45+ ToolsbuildTool() factory
Query Enginestreaming executor
Concurrencysafe/unsafe flags
Recovery8-stage chain
Cost Trackerper-session USD
Extensions
MCP8 config types
Pluginsmarketplace + builtin
Skills17 bundled + custom
Hooks27 events
LSPcode intelligence
BridgeIDE comms
Services
API Client4 backends
Auth/OAuthPKCE + Keychain
AnalyticsDD + OTel
Settings5-layer merge
Migrations11 sync + 1 async
Security
7 Perm Modesdefault to bubble
23 Bash Checkscross-platform
Path Validator6-step pipeline
Auto-ModeYOLO classifier
Boot Sequence
Startup Pipeline
Phase 0
Side Effects
MDM, Keychain prefetch
Phase 1
main() entry
Basic initialization
Phase 2
preAction
init() → migrations
Phase 3
action()
setup → auth/perms
Phase 4
REPL render
Deferred prefetches
Core Engine
Tool Execution Flow
IN
User Input
prompt → QueryEngine
↓
AI
LLM API (streaming)
Anthropic / Bedrock / Vertex / Foundry
↓ tool_use block
FN
Tool Execution
Bash, FileEdit, Agent, MCP … 45+
↓
R
ToolResult
data, newMessages, contextModifier, mcpMeta
↺ next LLM turn
Documentation
8 Design Documents
01
Architecture Overview
5-phase startup, ESM-only module system, Bun bundler, 7-layer config, 89 feature flags, 110 global state fields
1,101 lines
startup config feature-flags
02
Core Engine
60+ field tool interface, buildTool() factory, concurrency safety flags, 8-stage recovery chain, per-session cost tracking
1,352 lines
tools streaming recovery
03
Permission & Security
7 permission modes, 4-step decision pipeline, 23 bash check IDs, 6-step path validation, YOLO auto-classifier
1,178 lines
permissions bash-security TOCTOU
04
Multi-Agent & Memory
3 swarm backends (fork/spawn/in-proc), 7 task types, file-based mailbox, 5-layer memory hierarchy, ETag-based sync
1,416 lines
agents memory teams
05
Extension Systems
6 extension points, MCP 8 transport types, 27 hook events, plugin marketplace, parallel loading, reconnection strategy
1,709 lines
MCP plugins hooks
06
UI Layer
Custom React reconciler (React 19), Ink fork (96 files), Yoga WASM layout, ANSI diff rendering, 346 .tsx components
1,784 lines
React Ink Yoga
07
Services & Infrastructure
4 API backends, OAuth PKCE with Keychain, Datadog + OTel analytics, 5-source settings merge, 11+1 migrations
1,845 lines
API OAuth analytics
08
Types, Schemas & API
Branded IDs, Zod schemas, ~100 field SettingsJson, DeepImmutable AppState, 60+ env vars, 89 feature flags, 44 DD events
2,194 lines
TypeScript Zod schemas
Security
Permission Decision Pipeline
0
Config deny rules
immediate deny
↓
1
Tool.checkPermissions()
allow / deny / ask / passthrough
↓
2
Permanent allow rules
skip prompt
↓
3
passthrough → ask conversion
 
↓
4
Post-processing
dontAsk • auto (YOLO) • headless
Multi-Agent
Agent & Memory Hierarchy
Agent Swarm Backends
Coordinator (orchestrator)
fork
shared context
spawn
independent
in-process
teammate
Memory Hierarchy (5 layers)
[1] Session Memory — in-context summaries
[2] Project Memory — .claude/memory/
[3] User Memory — ~/.claude/memory/
[4] Team Memory — server-synced shared
[5] External — MCP, LSP, git
Infrastructure
Deployment Options
Local Dev
Ollama/vLLM, Docker Stack, RTX 4090
$0–50/mo
AWS
ECS Fargate, Bedrock, Lambda, Cognito
$45–180/mo
Azure
Container Apps, Azure OpenAI, AD B2C
$50–190/mo
Supabase
Edge Functions, Realtime, PostgreSQL, Auth
$0–25/mo
Scale Supabase + API AWS Full Hybrid (Local GPU)
Solo (1 dev) $9–103/mo $240–280/mo $50/mo
Team (10 devs) $46–116/dev $65–110/dev $35–60/dev
Enterprise (100 devs) N/A $45–111/dev $25/dev

LLM token costs represent 60–95% of total spend at every scale.

Quality
8 Verification Passes
Pass 1
Type/value accuracy
16 corrections
Pass 2
Blocking implementation gaps
4 fixes
Pass 3
Line-by-line precision
7 corrections
Pass 4
Missing schemas/flows
3 fixes
Pass 5
Bridge, MDM, Keychain, Plugin additions
7 additions
Pass 6
Structural problem warnings
42 caveats
Pass 7
Convergence check
2 micro-fixes
Pass 8
CONVERGED — 24/24 spot-checks verified
0

Total: 39 corrections + 42 implementation caveats

Repository
File Structure
claude-code-reverse-engineering/ README.md docs/ 01-architecture-overview.md (1,101 lines) 02-core-engine.md (1,352 lines) 03-permission-security.md (1,178 lines) 04-multi-agent-memory.md (1,416 lines) 05-extension-systems.md (1,709 lines) 06-ui-layer.md (1,784 lines) 07-services-infrastructure.md (1,845 lines) 08-types-schemas-api.md (2,194 lines) infrastructure/ 01-local-development.md 02-aws-architecture.md 03-azure-architecture.md 04-supabase-backend.md 05-cost-analysis.md 06-architecture-diagram.md terraform/ (10 .tf files — production-ready IaC)
Disclaimer: 이 문서는 공부와 보안 연구를 위해, 완성된 프로그램을 분해해 구조를 알아낸 것(리버스 엔지니어링)입니다. 원본 Claude Code 프로그램에 대한 모든 권리는 Anthropic이라는 회사에 있습니다. 여기 정리한 분석 문서 자체에만 MIT 라이선스(누구나 자유롭게 쓰고 고칠 수 있게 허용하는 오픈소스 이용 약관)가 적용됩니다.