waiterxiaoyy/deep-dive-claude-code

Purpose and Deliverables

This repository is an educational deep dive into Claude Code architecture, not a Claude Code implementation. It combines chapter documentation, independently runnable TypeScript demonstrations, selected reconstructed source excerpts, and a Next.js interactive learning site. Core material is organized around 13 architectural topics in docs/ and source-code/.

Entry Points

• Web platform: Next.js App Router entry at web/src/app/page.tsx; chapter routing is rooted in web/src/app/chapter/[id]/page.tsx.

• Runnable demonstrations: individual scripts in agents/, beginning with agents/s01_agent_loop.ts; root dependencies are defined in package.json.

• Source walkthrough bootstrap path: source-code/dev-entry.ts → source-code/cli.tsx → source-code/main.tsx.

Agent Execution and Tool Boundary

The teaching model centers on an iterative model/tool loop: request processing, model response, tool invocation, result incorporation, and repeat. The representative engine is source-code/QueryEngine.ts, with query orchestration in source-code/query.ts. Tool contracts and registration form the capability boundary in source-code/Tool.ts and source-code/tools.ts.

Prompt, Security, and Authorization Stages

System prompts are assembled dynamically before execution through source-code/constants/prompts.ts. Shell execution is treated as a high-risk boundary: command validation/security precedes execution in source-code/tools/BashTool/bashSecurity.ts, while permissions are separately evaluated through source-code/tools/BashTool/bashPermissions.ts. Filesystem and general permission policy are represented by source-code/utils/permissions/filesystem.ts and source-code/utils/permissions/permissions.ts.

Context, Extensions, and Delegation

Long-running conversations use compaction stages to fit finite model context, including automatic and micro-compaction in source-code/services/compact/autoCompact.ts and source-code/services/compact/microCompact.ts. MCP extends the tool plane to external services, with configuration, authentication, and client communication separated in source-code/services/mcp/config.ts, source-code/services/mcp/auth.ts, and source-code/services/mcp/client.ts. Agent delegation is illustrated by source-code/tools/AgentTool/AgentTool.tsx.

Interactive Learning Platform

The web app renders generated documentation/source data, visualizations, and replayable scenario simulations. Build-time ingestion converts repository docs and source material into web data via web/scripts/build-docs.mjs and web/scripts/build-sources.mjs; outputs are consumed from web/src/data/generated/docs.json and web/src/data/generated/sources.json. Chapter pages compose a renderer, visualizations, and simulator controls, notably web/src/components/docs/doc-renderer.tsx, web/src/components/visualizations/index.tsx, and web/src/hooks/useSimulator.ts.

Runtime and External Dependencies

The educational site runs on Next.js 15/React with Tailwind, Framer Motion, and Markdown processing. The runnable demos use TypeScript execution and may require an API key via .env.example; bash-security examples can run locally without one. The analyzed upstream architecture targets Bun, React Ink/Commander CLI behavior, MCP-connected services, and feature-flag/experimentation infrastructure, though only selected source excerpts are present here.