claude-code-reverse-engineering
mcp
Reverse-engineered design documents for Anthropic Claude Code CLI - implementation-ready specifications
README.md
Claude Code CLI — Reverse Engineering Design Documents
Implementation-ready reverse engineering specifications for Anthropic's Claude Code CLI tool.
Extracted via source map analysis of the npm package (March 2026).
At a Glance
┌─────────────────────────────────────────────────────────────────────┐
│ Claude Code CLI │
│ │
│ ~1,900 files · 512,000+ LOC · TypeScript Strict · Bun │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ React │ │ Ink │ │ Yoga │ │Commander │ │
│ │ 19 │ │ (custom │ │ (WASM │ │ .js │ │
│ │ │ │ fork) │ │ layout) │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┴──────────────┴──────────────┘ │
│ Terminal UI │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Core Engine │ │
│ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ │
│ │ │ 45+ │ │ Query │ │ Streaming │ │ Cost │ │ │
│ │ │ Tools │ │ Engine │ │ Executor │ │ Tracker │ │ │
│ │ └─────────┘ └──────────┘ └───────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Extension Layer │ │
│ │ ┌─────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌─────┐ ┌──────┐ │ │
│ │ │ MCP │ │Plugins │ │ Skills │ │Hooks │ │ LSP │ │Bridge│ │ │
│ │ └─────┘ └────────┘ └────────┘ └──────┘ └─────┘ └──────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Services │ │
│ │ ┌────────┐ ┌──────┐ ┌───────────┐ ┌────────┐ ┌─────────┐ │ │
│ │ │ API │ │ Auth │ │ Analytics │ │Settings│ │Migration│ │ │
│ │ │(4 back)│ │OAuth │ │ DD+OTel │ │5-layer │ │ chain │ │ │
│ │ └────────┘ └──────┘ └───────────┘ └────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Security & Permissions │ │
│ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ 7 Perm │ │ 23 Bash │ │ Path │ │ Auto-Mode │ │ │
│ │ │ Modes │ │ Checks │ │Validator │ │ Classifier │ │ │
│ │ └──────────┘ └───────────┘ └──────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Design Documents
Part 1 — Architecture Overview
docs/01-architecture-overview.md· 1,101 lines
Startup Sequence (5 phases)
═══════════════════════════════════════════
Phase 0 ─► Module-level side effects (MDM, Keychain prefetch)
Phase 1 ─► main() entry, basic initialization
Phase 2 ─► Commander preAction → init() → migrations
Phase 3 ─► action() → setup() → auth/permissions
Phase 4 ─► REPL render + deferred prefetches
| Topic | Key Details |
|---|---|
| Module System | ESM-only, .js extensions required, lazy require() for cycles |
| Build | Bun bundler, feature() flags for dead code elimination |
| Config | 7 layers: Global → Project → Settings(5 sources) → CLI → MDM |
| Feature Flags | 89 flags via GrowthBook, bun:bundle compile-time DCE |
| State | 110 global fields in bootstrap/state.ts, DO NOT ADD MORE policy |
Part 2 — Core Engine
docs/02-core-engine.md· 1,352 lines
Tool Execution Pipeline
═══════════════════════════════════════════
User Input ──► QueryEngine ──► LLM API (streaming)
│
tool_use block
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Bash │ │ FileEdit │ │ Agent │
│ Tool │ │ Tool │ │ Tool │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
ToolResult ToolResult ToolResult
{ data, newMessages?, contextModifier?, mcpMeta? }
│
◄─────┘
Next LLM turn with results
| Topic | Key Details |
|---|---|
| Tool Interface | 60+ fields, buildTool() factory, 7 defaultable keys |
| Concurrency | isConcurrencySafe flag — safe tools run parallel, unsafe exclusive |
| Recovery | 8-stage chain: streaming fallback → model fallback → collapse drain → reactive compact |
| Cost Tracking | Per-session USD accumulator, multi-provider normalization |
Part 3 — Permission & Security
docs/03-permission-security.md· 1,178 lines
Permission Decision Pipeline (4 steps + auto-mode)
═══════════════════════════════════════════════════
Step 0 Config deny rules ──► deny (immediate)
Step 1 Tool.checkPermissions() ──► allow/deny/ask/passthrough
Step 2 Permanent allow rules ──► allow (skip prompt)
Step 3 passthrough → ask conversion
Step 4 Post-processing:
├── dontAsk mode ──► auto deny
├── auto mode ──► classifier pipeline:
│ ├── acceptEdits fast-path
│ ├── safe-tool allowlist
│ └── YOLO classifier (2-stage)
│ ├── allowed ──► allow
│ ├── blocked ──► deny + denial tracking
│ └── unavailable ──► iron_gate fail-closed
└── headless ──► hook or deny
| Topic | Key Details |
|---|---|
| 7 Modes | default, plan, acceptEdits, bypassPermissions, dontAsk, auto, bubble |
| Bash Security | 23 check IDs, 19 cross-platform + 7 Unix + 11 ANT-only patterns |
| Path Validation | 6-step: normalize → symlink resolve → traversal → Windows patterns → scope |
| TOCTOU Warning | Path validation and file access are not atomic — race condition window |
Part 4 — Multi-Agent & Memory
docs/04-multi-agent-memory.md· 1,416 lines
Agent Hierarchy
═══════════════════════════════════════════
┌───────────────┐
│ Coordinator │ (orchestrator — no direct tool use)
└───────┬───────┘
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Worker │ │ Worker │ │ Worker │
│ (fork) │ │ (spawn) │ │(in-proc) │
└──────────┘ └──────────┘ └──────────┘
Memory Hierarchy (5 layers)
═══════════════════════════════════════════
[1] Session Memory ── in-context summaries
[2] Project Memory ── .claude/memory/ files
[3] User Memory ── ~/.claude/memory/
[4] Team Memory ── server-synced shared memory
[5] External ── MCP servers, LSP, git
| Topic | Key Details |
|---|---|
| 3 Swarm Backends | fork (shared context), spawn (independent), in-process teammate |
| Task Types | 7 types with ID prefixes: bash, workflow, agent, teammate, remote, monitor, dream |
| Mailbox | File-based: .claude/teams/{team}/inboxes/{agent}.json |
| Team Sync | ETag-based conflict detection (412), no local file locking |
Part 5 — Extension Systems
docs/05-extension-systems.md· 1,709 lines
6 Extension Points
═══════════════════════════════════════════
┌─────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌─────┐ ┌──────┐
│ MCP │ │Plugins │ │ Skills │ │Hooks │ │ LSP │ │Bridge│
│ │ │ │ │ │ │ │ │ │ │ │
│8 cfg│ │market- │ │17 bun- │ │27 │ │code │ │IDE │
│types│ │place + │ │dled + │ │events│ │intel│ │comms │
│ │ │builtin │ │custom │ │ │ │ │ │ │
└─────┘ └────────┘ └────────┘ └──────┘ └─────┘ └──────┘
| Topic | Key Details |
|---|---|
| MCP Transports | TransportSchema: 6 types; McpServerConfig: 8 (+ ws-ide, claudeai-proxy) |
| Hook Priority | deny > ask > allow — any hook's deny overrides all allows |
| Plugin Loading | Parallel (marketplace + session) → builtins → merge → dependency verify |
| Reconnection | MAX_ERRORS_BEFORE_RECONNECT=3, SSE maxRetries=2, 15min poll timeout |
Part 6 — UI Layer
docs/06-ui-layer.md· 1,784 lines
Render Pipeline
═══════════════════════════════════════════
React Component Tree
│
▼
Custom Reconciler (React 19 HostConfig)
│
▼
Yoga Layout Engine (WASM)
│ ┌──────────────────────┐
├──│ Box (flexbox node) │
├──│ Text (measure func) │
└──│ Button (interactive) │
└──────────────────────┘
│
▼
Output Renderer (ANSI diff)
│
▼
Terminal stdout (throttled at FRAME_INTERVAL_MS)
| Topic | Key Details |
|---|---|
| Ink Fork | 96 files in src/ink/, custom reconciler, Yoga WASM integration |
| Components | 346 .tsx files in src/components/ |
| Hooks | 85+ custom hooks (useTextInput, useTerminalSize, useStdin, etc.) |
| Concurrency | maySuspendCommit() always returns false — Suspense disabled |
Part 7 — Services & Infrastructure
docs/07-services-infrastructure.md· 1,845 lines
API Client Factory (4 backends)
═══════════════════════════════════════════
┌──────────────────┐
│ buildFetch() │
│ + withRetry() │
└────────┬─────────┘
┌────────────────┼────────────────┐──────────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Anthropic│ │ Bedrock │ │ Foundry │ │ Vertex │
│ (Direct) │ │ (AWS) │ │ (Azure) │ │ (GCP) │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
Retry Strategy: 429 → Retry-After (≤20s: sleep, >20s: 30min cooldown)
529 → MAX_529_RETRIES=3 (non-subscriber only)
401 → token refresh → retry (no max refresh limit!)
| Topic | Key Details |
|---|---|
| Analytics | Datadog (44 allowed events, 16 tag fields) + OpenTelemetry + 1P logger |
| OAuth | PKCE flow, macOS Keychain with plaintext fallback (30s TTL cache) |
| Settings Merge | 5 sources: user → project → local → flag → policy (arrays concat, not override!) |
| Migrations | 11 sync + 1 async, includes migrateLegacyOpusToCurrent (ant-only DCE) |
Part 8 — Types, Schemas & API
docs/08-types-schemas-api.md· 2,194 lines
Type System Layers
═══════════════════════════════════════════
┌─────────────────────────────────────────┐
│ Branded IDs │
│ SessionId, AgentId, TaskId, ToolUseId │
├─────────────────────────────────────────┤
│ Core Types │
│ Tool<I,O,P>, ToolResult<T>, │
│ ValidationResult, ToolUseContext (30+) │
├─────────────────────────────────────────┤
│ Zod Schemas │
│ HookCommand (discriminated union), │
│ SettingsSchema (~100 fields), │
│ TransportSchema (6 literals) │
├─────────────────────────────────────────┤
│ AppState │
│ DeepImmutable<> wrapper, │
│ ~85 fields + Store<T> pattern │
├─────────────────────────────────────────┤
│ Environment Variables (60+) │
│ Feature Flags (89) │
│ Analytics Events (44 Datadog) │
└─────────────────────────────────────────┘
| Topic | Key Details |
|---|---|
| SettingsJson | ~100 fields across 15 categories (auth, permissions, MCP, hooks, model, UI...) |
| Settings Merge | policySettings internal priority: remote > HKLM/plist > file > HKCU |
| Env Vars | 60+ variables across 7 groups (API, model, auth, debug, feature, proxy, internal) |
| Feature Flags | 89 bun:bundle feature() calls, compile-time dead code elimination |
Infrastructure & Deployment
infrastructure/— Complete deployment blueprints with Terraform IaC
Deployment Options
═══════════════════════════════════════════
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Local Dev │ │ AWS │ │ Azure │ │ Supabase │
│ │ │ │ │ │ │ │
│ Ollama/vLLM │ │ ECS Fargate │ │ Container │ │ Edge Funcs │
│ Docker Stack │ │ Bedrock │ │ Apps │ │ Realtime │
│ RTX 4090 │ │ Lambda │ │ Azure OpenAI │ │ PostgreSQL │
│ │ │ Cognito │ │ AD B2C │ │ Auth │
│ $0-50/mo │ │ $45-180/mo │ │ $50-190/mo │ │ $0-25/mo │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
| Document | Description |
|---|---|
01-local-development.md |
Ollama, vLLM, LM Studio, Docker Compose full stack |
02-aws-architecture.md |
VPC, ECS, Bedrock, Lambda sandbox, CloudWatch |
03-azure-architecture.md |
Container Apps, Azure OpenAI, Functions, Monitor |
04-supabase-backend.md |
10-table schema, RLS policies, Edge Functions |
05-cost-analysis.md |
Real pricing: $9/mo solo → $25/dev enterprise |
06-architecture-diagram.md |
7 ASCII diagrams: system, data flow, auth, agents |
terraform/ |
10 .tf files — production-ready AWS IaC |
Cost Quick Reference
| 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.
Verification Status
These documents went through 8 rigorous verification passes against the actual source code:
Pass 1 ████████████████ 16 corrections (type/value accuracy)
Pass 2 ████ 4 fixes (blocking implementation gaps)
Pass 3 ███████ 7 corrections (line-by-line precision)
Pass 4 ███ 3 fixes (missing schemas/flows)
Pass 5 ███████ 7 additions (Bridge, MDM, Keychain, Plugin)
Pass 6 ██████████████ 42 caveats (structural problem warnings)
Pass 7 ██ 2 micro-fixes (convergence check)
Pass 8 ─────────────── CONVERGED (24/24 spot-checks verified)
═══════════════
Total: 39 corrections + 42 implementation caveats
Quick Start
# Clone the repo
git clone https://github.com/jung-wan-kim/claude-code-reverse-engineering.git
cd claude-code-reverse-engineering
# Read the design docs (start here)
open docs/01-architecture-overview.md
# Deploy infrastructure (AWS)
cd infrastructure/terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your settings
terraform init && terraform plan
Repository Structure
claude-code-reverse-engineering/
├── README.md ← You are here
├── 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/
├── main.tf
├── variables.tf
├── vpc.tf
├── compute.tf
├── database.tf
├── storage.tf
├── auth.tf
├── monitoring.tf
├── outputs.tf
└── terraform.tfvars.example
Disclaimer
This is a reverse-engineering effort for educational and security research purposes only. All rights to the original Claude Code software belong to Anthropic.
License
MIT (documentation only — does not cover the original Claude Code software)
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found