1.3 Codebase Map: How to Navigate 1,987 Files

Chapter goal: Build a mental map of the source tree so you know "which directory to go to for which feature."

Global Structure

ClaudeCode/
├── src/           ← core source code (1,987 .ts/.tsx files)
├── docs/          ← analysis docs (the tutorial you are reading)
├── shims/         ← JS fallbacks for native modules
├── vendor/        ← C++/Rust native binding source
├── package.json   ← dependency declarations
└── tsconfig.json  ← TypeScript config

src/ Directory Breakdown

🚪 Entry Files (Start Reading Here)

src/
├── dev-entry.ts      ← dev-mode entry, initializes MACRO constants
├── main.tsx          ← main entry (785 KB!) React root component + full REPL logic
└── query.ts          ← main loop (67 KB), Agent core

Tip: main.tsx is 785 KB; do not try to read it linearly. Start with query.ts to understand the core logic.

🔧 Tool System

src/tools/           ← one subdirectory per tool
├── BashTool/        ← execute shell commands
├── FileReadTool/    ← read files
├── FileEditTool/    ← edit files (string-replace style)
├── FileWriteTool/   ← write files (full overwrite)
├── GlobTool/        ← file path matching
├── GrepTool/        ← file content search
├── AgentTool/       ← recursively launch sub-agents
├── WebSearchTool/   ← web search
├── WebFetchTool/    ← fetch webpage content
├── MCPTool/         ← MCP protocol dynamic tools
├── TodoWriteTool/   ← task list management
└── ... (53 total)

src/Tool.ts          ← abstract base type definitions for tools (28 KB)
src/tools.ts         ← tool registry, assembles all tools together

💬 Command System

src/commands/        ← 87 slash commands, one subdirectory each
├── help/            ← /help
├── clear/           ← /clear
├── compact/         ← /compact (manual context compaction)
├── memory/          ← /memory
├── model/           ← /model (switch model)
├── mcp/             ← /mcp (MCP service management)
├── config/          ← /config
├── plan/            ← /plan (plan mode)
└── ...

src/commands.ts      ← command registry center (24 KB)

🏗️ State Management

src/bootstrap/
└── state.ts         ← global singleton state (54 KB)
                       includes: model, cost, session ID, telemetry Meter...

src/state/
└── AppState.ts      ← React app state type definitions

src/context/         ← React Context definitions
src/hooks/           ← 87 custom Hooks (state, permissions, UI, etc.)

🎨 UI Components

src/components/      ← 148 Ink/React terminal components
├── REPL.tsx         ← main conversation interface
├── Spinner.tsx      ← loading animation
├── PermissionRequest.tsx ← permission confirmation modal
├── MessageSelector.tsx   ← message selector
└── ...

src/ink.ts           ← Ink rendering engine wrapper
src/outputStyles/    ← output styling system

🤖 Advanced Feature Modules

src/assistant/       ← KAIROS persistent assistant mode
├── index.ts
└── sessionHistory.ts

src/coordinator/     ← multi-agent orchestration
└── coordinatorMode.ts

src/bridge/          ← remote control (33 files)
├── replBridge.ts    ← REPL-side bridge main file (98 KB)
├── remoteBridgeCore.ts ← remote-side core
└── ...

src/proactive/       ← proactive mode (autonomous operation when idle)
src/buddy/           ← AI virtual pet
src/voice/           ← voice interaction
src/vim/             ← Vim keybinding mode

🔌 Service Layer

src/services/
├── api/             ← Claude API client wrappers
│   ├── claude.ts    ← API call core
│   └── errors.ts    ← error types
├── mcp/             ← MCP protocol client
├── analytics/       ← event tracking (GrowthBook + custom)
├── compact/         ← context compaction algorithm
├── oauth/           ← OAuth auth
├── autoDream/       ← KAIROS memory consolidation
└── tools/           ← tool execution infrastructure
    └── toolOrchestration.ts ← tool concurrency scheduler

🛠️ Utility Functions

src/utils/           ← large collection of utility functions
├── config.ts        ← config file read/write
├── git.ts           ← Git operation wrappers
├── permissions/     ← permission decision logic
├── messages.ts      ← message formatting
├── model/           ← model selection logic
├── claudemd.ts      ← CLAUDE.md handling
├── cwd.ts           ← working directory management
└── ... (dozens of files)

How to Read This Codebase Efficiently

Method 1: Start from Feature Entry Points

Method 2: Trace the Data Flow

Receive user input in main.tsx → QueryEngine.submitMessage() → query() → queryLoop() → tool execution → streamed response back

Method 3: Read Type Definitions First

src/Tool.ts and the src/types/ directory define core data structures. Understand types first, then implementation.

Next

• Chapter 2: Six-Layer Architecture — understand the overall design
• Chapter 3: Deep Dive into query.ts — go straight into the core