# This Is Not a Chatbot

When you type `claude` in your terminal, you are not opening a chat window—you are launching an engineering system composed of 1,884 TypeScript files.

> **🌍 Industry Context**: By 2026, AI coding assistants have completed a paradigm shift from "single-point completion" to "agent cluster orchestration." **Cursor** introduced Background Agents for parallel refactoring in cloud VMs; **Windsurf**'s Cascade Engine delivers sub-second predictive edits; **GitHub Copilot**'s Agent Mode is now fully GA (with dedicated Explore/Plan/Task agents built in); **CodeX** is OpenAI's terminal tool rewritten in Rust (supporting parallel agent workflows); **Kimi Code** leverages K2.5 to enable Agent Swarm with up to 100 concurrent sub-agents; **OpenCode** has become the open-source CLI benchmark with 110K+ stars (supporting 75+ model providers); **GLM (Z.ai)** trained a 744-billion-parameter model entirely on domestic Ascend 910B chips and offers Z Code as a privatized programming foundation. What sets Claude Code apart from all of them: it is a **purely terminal-native** AI Agent that depends on no IDE, and its source scale (1,884 files) far exceeds most comparable tools—meaning a more complex engineering system, but also more design decisions to analyze and learn from. This book dissects that system layer by layer.

> 📚 **Course Connection**: If you have studied software engineering, Claude Code's architecture covers almost every classic pattern in the textbook—Event Loop, Chain of Responsibility, Pub-Sub, Adapter, Bridge, Factory. Reading this book is equivalent to seeing the industrialized application of these patterns in a real product. Every time a pattern first appears, it will be marked with 📚 to help you map it back to your coursework.

---

## Two Fundamentally Different Mental Models

**Model A (wrong)**: User types a message → API call → AI outputs → displayed to user

**Model B (actual)**:

```
User input
  → [Permission system] Checks whether this operation is allowed
  → [Context construction] Assembles git status + CLAUDE.md + conversation history
  → [queryLoop main loop] Starts AI reasoning
      → AI says: I want to read this file
      → [StreamingToolExecutor] Starts reading the file while the AI is still speaking
      → [Tool concurrency] Three files read simultaneously (not serially)
      → AI says: I want to edit this file
      → [Permission prompt] Requests user approval
      → AI continues...
      → [Context compaction] When tokens are nearly full, uses another AI to summarize the conversation
  → [SessionMemory] Background AI updates project notes
  → [Prompt Suggestion] Predicts your next message
  → [Speculation] Starts executing AI with a predicted message (before you even type)
```

This is not an API call. It is an **engineering system with its own lifecycle, multi-AI collaboration, and pipeline execution**.

---

## Where the System's Boundary Lies

Most people's understanding of Claude Code stops at "an AI assistant with tools." But the precise description is:

**An AI main loop (`queryLoop`), plus multiple subsystems working around it.**

The main loop is the heart: an AsyncGenerator (asynchronous generator—like a faucet that continuously streams events) running `while(true)`, receiving user input, calling the API, processing tools, until a final answer is produced.

> 💡 **Plain English**: The main loop is like a **package-sorting conveyor belt**—receive package (user input) → sort (determine which tools are needed) → load truck (execute tools) → deliver (return results) → get signature (display to user) → wait for the next package (continue looping). The belt never stops until every package is delivered.

The subsystems surrounding the main loop operate independently, coordinated through shared state (AppState) and the hooks system:

| Subsystem | Responsibility | Competitor Comparison |
|-----------|---------------|----------------------|
| Permission system | Decides whether each operation is allowed | Aider only has a `--yes` switch; Cursor uses simplified pop-ups |
| Context construction | Assembles the complete prompt sent to the AI | Aider uses repo map pre-filtering; Cursor uses .cursorrules |
| Tool execution | Parallel, streaming execution of tools called by the AI | Most competitors execute serially |
| Context compaction | Seamlessly compresses conversation when tokens are running low | Aider chooses pre-filtering rather than post-hoc compression |

> 💡 **Plain English**: Context compaction is like a **meeting note-taker**—recording the entire meeting would be too long → create an executive summary → archive the original recording. For the next meeting, bring the summary; you don't need to replay three hours of audio.
| Agent system | Creates and manages sub-agent instances |
| MCP layer | Connects to external tool servers |
| SessionMemory | Extracts and maintains session notes in the background |
| Speculation | Predicts the next user input and executes ahead of time |

---

## How Big This System Is

- 1,884 source files (1,332 `.ts` + 552 `.tsx`)
- Main entry `main.tsx`: 785 KB, single file
- AI main loop `query.ts`: approximately 1,700 lines
- Permission system `permissions.ts`: approximately 1,400 lines
- CLAUDE.md loader `claudemd.ts`: approximately 1,300 lines
- Tool interface `Tool.ts`: 20+ methods/properties

It uses React (for terminal UI rendering), Zod (type validation), Anthropic SDK (AI calls), OpenTelemetry (observability), GrowthBook (feature gating), and dozens of other dependencies.

> 💡 **Plain English**: GrowthBook's "feature gating" is like a **restaurant's secret menu**—the dish is prepared, but only VIPs or staff can order it. Regular customers don't see it on the menu, but as soon as the server (feature gate) allows it, it can be served right away.

---

## Why These Designs Are Worth Understanding Deeply

Claude Code is a system built under extremely demanding constraints:

- **Must not lose context**: Conversation history has a token limit and needs automatic compression
- **Must not interrupt workflow**: Tool execution must be efficient, and user waiting time must be minimized
- **Must not accidentally damage files**: The permission system must have multiple lines of defense
- **Must not waste tokens**: Caching strategy must be carefully designed
- **Must not trust all inputs**: Tool results may contain injection attacks

Every design decision carries the shadow of these constraints. Understand these constraints, and you will understand the "why is it so complicated" questions in the codebase.

---

## How to Read This Book

**Part 2 (Complete Code Architecture Deconstruction)** is the foundation. It systematically dismantles the entire codebase, from the boot sequence to the terminal UI, dissecting every subsystem layer by layer.

**Part 3 (Curiosity-Driven Deep Q&A)** is the core. Each chapter picks one "counter-intuitive" or "confusing" design, starting from "you might think…" to reveal the actual implementation and the trade-offs behind it.

**Part 4 (Complete Subsystem Reference)** is the reference material. If you want to dive into the full details of a particular subsystem, look here.

**Part 5 (Engineering Philosophy)** is the distillation. What engineering ideas does Claude Code demonstrate that are worth borrowing?

**Part 6 (Critique and Beyond)** is the reflection. Which designs are costly trade-offs? Where could things be done better?

---

*Suggested reading approach*: Start with any chapter in Part 3 to build an initial impression, then jump according to the linked chapters. Every chapter can be read independently.

---

## Key Source Code Entry Points

- `src/main.tsx` — The system's entry file (4,684 lines). Boot sequence, REPL loop, and global state initialization all live here
- `src/query.ts` — The heart of the Agent loop: a `while(true)` `queryLoop` that drives the heartbeat of "call API → execute tools → call again"
- `src/services/api/claude.ts` — Wraps Anthropic API calls, streaming response handling, token counting, and cache control
- `src/Tool.ts` — Base tool interface definition; all 40+ built-in tool implementations conform to this interface