Claude Code Reverse Engineering

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](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](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](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](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](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 | MAXERRORSBEFORE_RECONNECT=3, SSE maxRetries=2, 15min poll timeout |

---

Part 6 — UI Layer

> [docs/06-ui-layer.md](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](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](docs/08-types-schemas-api.md) · 2,194 lines

Type System Layers
═══════════════════════════════════════════
┌─────────────────────────────────────────┐
│ Branded IDs                              │
│ SessionId, AgentId, TaskId, ToolUseId   │
├─────────────────────────────────────────┤
│ Core Types                               │
│ Tool, ToolResult,             │
│ ValidationResult, ToolUseContext (30+)   │
├─────────────────────────────────────────┤
│ Zod Schemas                              │
│ HookCommand (discriminated union),       │
│ SettingsSchema (~100 fields),            │
│ TransportSchema (6 literals)             │
├─────────────────────────────────────────┤
│ AppState                                 │
│ DeepImmutable<> wrapper,                 │
│ ~85 fields + Store 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/](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](infrastructure/01-local-development.md) | Ollama, vLLM, LM Studio, Docker Compose full stack | | [02-aws-architecture.md](infrastructure/02-aws-architecture.md) | VPC, ECS, Bedrock, Lambda sandbox, CloudWatch | | [03-azure-architecture.md](infrastructure/03-azure-architecture.md) | Container Apps, Azure OpenAI, Functions, Monitor | | [04-supabase-backend.md](infrastructure/04-supabase-backend.md) | 10-table schema, RLS policies, Edge Functions | | [05-cost-analysis.md](infrastructure/05-cost-analysis.md) | Real pricing: $9/mo solo → $25/dev enterprise | | [06-architecture-diagram.md](infrastructure/06-architecture-diagram.md) | 7 ASCII diagrams: system, data flow, auth, agents | | [terraform/](infrastructure/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 do

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jung-wan-kim](https://github.com/jung-wan-kim)
- **Source:** [jung-wan-kim/claude-code-reverse-engineering](https://github.com/jung-wan-kim/claude-code-reverse-engineering)
- **License:** MIT

Install and usage instructions live in the source repository linked above.