# All the Concepts You Need to Understand This Book

> This chapter is your "pass" into everything that follows. If you feel lost in a later chapter, come back here for definitions. If you want a quick look-up for a term, this is your index.

> **🌍 Industry Context**: AI agent frameworks are rapidly forming their own terminologies. LangChain has four core abstractions—Chain, Agent, Tool, and Memory. AutoGPT has Task, Action, and Plugin. CrewAI has Agent, Task, and Crew. Claude Code's conceptual system (Tool/Agent/Session/Hook/MCP) overlaps with these frameworks but does not map one-to-one. For example, Claude Code's "Hook" is closer to Webpack's plugin tapable system than to LangChain's callback. This chapter helps you understand Claude Code's terminology precisely, preventing false equivalences imported from other frameworks.

---

## Reading Guide

Claude Code is an engineering system with **1,884 TypeScript files**. It contains a vast amount of internal terminology, much of which is tightly intertwined with the word "Claude" itself, making it easy to confuse.

The goal of this chapter is not to make you memorize every concept, but to:
1. Give you a **mental map** of the "rooms" in this system
2. Tell you **what each word means** so terminology doesn't trip you up
3. Help you understand the **hierarchy and subordination** between concepts
4. Provide an **analogy reference table** — use what you already know to understand what you don't

> 📚 **Bridge for student readers**: If you've studied operating systems, computer networks, or software engineering, many concepts in this book have classroom counterparts. This chapter labels 📚 Course Connections next to each core concept, helping you connect industrial practice with classroom theory. You'll find that Claude Code's architecture is exactly the engineering realization of those theories you learned, deployed in a real product.

---

## Core Metaphor: Claude Code Is an Operating System

Before diving into terminology, let's establish an overall intuitive framework.

You probably have a general idea of what an operating system (Windows, macOS, Linux) does: it manages hardware resources (CPU, memory, disk), schedules applications (processes), enforces security policies (user permissions), and provides extension mechanisms (drivers, package managers).

Claude Code does **almost exactly the same thing**—except it manages not hardware, but **AI agents**:

| OS Concept You Know | Claude Code Equivalent | One-Sentence Explanation |
|---|---|---|
| Kernel | QueryEngine + `queryLoop` | The core loop that schedules everything |
| System call (Syscall) | Tool invocation (Tool) | The only way for AI to access the outside world |
| Process (Process) | Agent | A standalone AI instance |
| Process scheduler (Scheduler) | Task system | Manages multiple concurrent AI instances |
| Filesystem (Filesystem) | JSONL session + File History | Persistent storage |
| Security model (Security) | Permission system + sandbox | Multi-layered access control |
| Device driver (Driver) | MCP server | Standardized external tool interface |
| Shell | REPL terminal interface | The interaction layer between user and "kernel" |
| /etc/ config | Settings system (nine layers) | System configuration management |
| Environment variables | System Prompt | Context information at process startup |
| Kernel module (Module) | Hooks | Inject custom logic at key nodes |
| Package manager (apt/npm) | Plugin system + Skills | Third-party extension mechanism |
| Shared memory (IPC) | Scratchpad | Inter-agent communication |
| Boot sequence (Boot) | main.tsx → init.ts | System startup sequence |

**In subsequent chapters, when you encounter an unfamiliar Claude Code concept, try finding its corresponding OS concept in this table—you'll likely understand it immediately.**

> 💡 **Plain English**: Never mind if you're not familiar with operating systems! This book also provides everyday-life analogies whenever a concept first appears. "Kernel" can be thought of as a **parcel sorting center**, "system call" as an **employee's skill certificate**, and "permission system" as **gated community access control**—these everyday metaphors will help you build intuition even if you've never studied computer science.

---

## Layer 1: The Five Core Concepts

> Understand these five concepts and you understand the skeleton of the system.

### 1. Tool

**Shortest definition**: A capability that the AI can invoke.

Whenever Claude says "I want to read this file" or "I want to run this command," it is actually invoking a Tool. The system has **40 built-in tool categories**, plus an unlimited number of external MCP tools.

| Tool | Function | OS Analogy |
|------|----------|------------|
| `Read` | Read a file | `read()` system call |
| `Edit` | Edit a file (diff replacement) | `write()` to a specific offset |
| `Write` | Create/overwrite a file | `creat()` + `write()` |
| `Bash` | Execute a shell command | `exec()` |
| `Agent` | Create a sub-agent | `fork()` |
| `WebFetch` | Fetch a web page | `connect()` + `recv()` |
| `Glob` | Search by filename | `glob()` |
| `Grep` | Search by content | `grep` command |

**Key understanding**:
- Tools are not executed by Claude itself—Claude issues a **request** saying "I want to invoke tool X," and the local system **executes** it, returning the result to Claude
- Claude runs on a remote server and **cannot touch your computer**—tools are the only bridge between it and your filesystem
- Every tool call goes through a **permission check**—Claude cannot invoke whatever it wants

> 💡 **Plain English**: Tools are like **employee skill certificates**—a certificate for reading files, one for writing code, one for searching. When Claude wants to do something, it must present the corresponding certificate (tool invocation), pass an assessment (permission check), and only then can it act.

> **[Chart placeholder 1.3-A]**: Tool invocation cycle diagram — AI request → permission check → system execution → result returned → AI continues

---

### 2. `queryLoop`

**Shortest definition**: The entire processing pipeline from the moment you press Enter to the moment Claude finishes its response.

This is the heart of the system. The code lives in `query.ts` and is a `while(true)` loop:

```
Your input → API call → Claude speaks (may contain tool calls)
  → Tools are executed → Results returned → API call → Claude continues speaking
  → ... → Claude's final answer (no more tool calls) → Loop ends
```

**Metaphor**: The systole (calling the API) and diastole (processing tool results) of a heartbeat. Each "beat" is one API call. When Claude stops calling tools, the heart stops beating and this turn ends.

> 💡 **Plain English**: The `queryLoop` is like a **parcel sorting conveyor belt**—receive parcel → sort → load truck → deliver → get signature → wait for the next batch. Each loop iteration processes one batch of parcels. The belt stops only when all parcels are delivered (no more tool calls).

**Key understanding**:
- A single "response" may contain 5, 10, or 20 tool calls—the "final answer" the user sees is the result of **many loop iterations**
- The loop is an **AsyncGenerator**—it doesn't return the result all at once, but continuously yields a stream of events that the caller can process in real time
- The loop has **six exit conditions**: normal completion, max turns reached, user interruption, context full, API error, image error

---

### 3. Agent

**Shortest definition**: An independent AI instance running its own `queryLoop`.

When Claude needs to delegate a subtask to another AI instance, it invokes the `Agent` tool to create a sub-agent. The sub-agent has its own `queryLoop`, its own tool call history, and returns its result to the parent agent when done.

```
Main Agent (your conversation)
  ├── Sub-agent A (delegated: analyze this folder)
  │     └── Sub-sub-agent (delegated: analyze this file)
  └── Sub-agent B (delegated: run tests)
```

**Metaphor**:
- The main Agent is the **manager**—receives your request and decides who to assign it to
- Sub-agents are **employees**—each takes a task and executes it independently
- OS analogy: Agent = process; main Agent invoking the `Agent` tool = `fork()` to create a child process

**Key distinction**:
- **Main Agent**: The Claude responding to your input, running in the main interface
- **Sub-agent**: Created by the main Agent, runs in the background, and disappears when finished
- **Coordinator**: A special mode of the main Agent—it doesn't do tasks directly, only delegates and synthesizes (like a company CEO)

> 💡 **Plain English**: An Agent is like a **food delivery rider dispatched on an order**—the main Claude is the dispatch center, each Agent is a rider independently delivering different orders, reporting back when done. Coordinator mode means the dispatch center itself never delivers food; it only assigns orders and aggregates feedback.

> 📚 **Course Connection**: The multi-layer nested structure of Agents (main Agent → sub-agent → sub-sub-agent) is a direct mapping of the **process tree** from your operating systems class. The `Agent` tool = `fork()` system call, `Coordinator` mode = the init process (PID 1, managing child processes without doing business itself), and `Swarm` mode = the **Leader-Worker architecture** from your distributed systems class.

**Seven Agent/Task Types**:

| Type | Isolation Level | Metaphor |
|------|----------------|----------|
| `local_agent` | Independent message history, shared process | Different desks in the same office |
| `in_process_teammate` | Shared process and connection | Different people at the same desk |
| `remote_agent` | Fully independent machine | A remote team in another city |
| `local_bash` | Independent subprocess | A one-off task outsourced to the shell |
| `local_workflow` | Local workflow | An automation script executed step by step |
| `monitor_mcp` | MCP monitor | A sentry watching an external service |
| `dream` | Unconfirmed | — |

> **[Chart placeholder 1.3-B]**: Agent hierarchy tree diagram — main Agent → sub-agent → sub-sub-agent, with isolation levels labeled

---

### 4. Session

**Shortest definition**: A complete conversation, from the moment you open Claude Code until you close (or clear) it.

A Session has a unique ID (UUID). Conversation history is saved on disk (in the `~/.claude/projects/` directory) in **JSONL** format—one JSON object per line.

**What a Session contains**:
- Complete message history (what you said + what Claude said + tool call records)
- Permission decision history (which operations were allowed during this session)
- File change records (needed by `/rewind`)

**Metaphor**: Session = a running ledger. Every "transaction" (message/tool call/result) gets one line, always appended. The book stays on disk and survives closing the terminal.

**Key understanding**:
- The Session is **persisted to disk**—this makes `/resume` (resume conversation), `/branch` (branch conversation), and `/rewind` (rollback) possible
- JSONL format is **append-friendly**—in a crash, at most the last line is lost; the whole file isn't corrupted
- A Session may last minutes or hours—a long Session needs context compression to manage token volume

---

### 5. Context Window

**Shortest definition**: The maximum amount of information Claude can "see" in a single API call, measured in tokens.

A **token** is the basic unit of text processing for AI, roughly equal to 3/4 of an English word, or 1–2 Chinese characters. Every Claude model has a maximum context window size (e.g., 200,000 tokens).

> 💡 **Intuitive conversion**: 1,000 tokens ≈ 750 English words ≈ 500–600 Chinese characters ≈ one A4 page of content. A 200,000-token context window ≈ a 100,000–150,000-word novella. Claude charges roughly $0.003 per 1,000 input tokens (cache hit) to $0.015 (uncached), and about $0.075 per 1,000 output tokens. In plain terms: having Claude read one A4 page costs less than a cent, but having it write one can cost a few dimes.

**Metaphor**: Context Window = computer RAM. Data needed during program execution must be in RAM—if there's too much data, the least-used parts must be swapped out to disk. Claude Code's context compression mechanism is exactly this "swap."

**Six Compression Mechanisms** (from light to heavy):

| Tier | Mechanism | Metaphor |
|------|-----------|----------|
| 1 | Tool result size trimming (toolResultBudget) | Folding large luggage |
| 2 | History snippet trimming (snipCompact) | Tearing out irrelevant diary pages |
| 3 | Micro-compaction (microcompact) | Removing filler words from documents |
| 4 | Context collapse (contextCollapse) | Compressing three months of diary into one summary |
| 5 | Auto full-text compression (autocompact) | Re-packing all luggage with vacuum bags |
| 6 | Reactive emergency compression (reactiveCompact) | Luggage overweight—emergency re-packing at the gate |

> The first five tiers execute **before** each AI call (in 99% of cases, the first three are enough). The sixth is **post-hoc remediation**—triggered only when the API returns a 413 error (context limit exceeded). If even emergency compression can't solve it, the conversation truly ends.

**Key understanding**: The Context Window is a **scarce resource**. Many of the system's design decisions (six compression tiers, token budget controls, tool description character limits, lazy tool loading) are about managing this finite resource.

> 📚 **Course Connection**: Context window management is fundamentally **memory management** from your OS class. The 200K token limit = physical memory size, the six compression tiers = multi-level page replacement algorithms, `autocompact` = memory compaction, and `reactiveCompact` (triggered by 413 error) = the OOM Killer (emergency measure when memory is exhausted). Once you understand OS memory management, Claude Code's context management holds no mystery.

---

## Layer 2: Key Concepts for Understanding System Operation

> These concepts appear repeatedly across chapters. Understanding them makes reading smoother.

### Token

The basic unit of AI text processing. The four common types in this book and their "water rates":

> 💡 **Plain English**: Tokens are like **mobile phone credit**—making a call = output token billing (most expensive), receiving a call = input token billing, in-plan calls = cache read (much cheaper), out-of-plan = full price (expensive). Every conversation with Claude is a "phone call," and budgeting credit is a core concern of the entire system.

| Type | Meaning | Cost (Opus 4.6) | Metaphor |
|------|---------|-----------------|----------|
| Input tokens | Text sent to Claude | $15/million | Tap water |
| Output tokens | Text generated by Claude | $75/million | Purified water (5× more expensive) |
| Cache read tokens | Cached input hits | $1.5/million | Reclaimed water (10× cheaper) |
| Cache write tokens | Writing to cache | $18.75/million | Building a reservoir (upfront investment) |

**Remember this 10× gap**: Cache-hit tokens are one-tenth the price of regular tokens. A large number of design decisions in the system are aimed at maximizing cache hit rate.

### Prompt Cache

An Anthropic API feature: if the **prefix** of two requests is identical (token-by-token comparison), the repeated portion does not need to be reprocessed.

**Metaphor**: Writing a letter to the same person every day. The salutation ("Dear Zhang San") is always the same. If the post office remembers this salutation, you only need to mail the new part.

> 💡 **Plain English**: Prompt Cache is like a **restaurant's prepped ingredients**—frequently ordered dishes have their mise en place ready (cached), so only the final cooking step is needed (only the changed part is processed), saving huge amounts of time and cost. Ordering the same dish again doesn't mean starting from scratch.

The system's prompt assembly order (most stable content first, most likely-to-change content last) is designed to **maximize this cache hit rate**.

> 📚 **Course Connection**: Prompt Cache works exactly like **prefix-matching cache** from your computer architecture class—similar to how CPU L1/L2 caches match by address prefix tags, Prompt Cache matches by token sequence prefix. Cache hit = 10% cost, cache miss = 100% cost. The system's prompt assembly strategy (stable content first, variable content last) maximizes hit rate—consistent with the principle of **spatial locality** optimization in CPUs.

### System Prompt

The "background information packet" sent to Claude, containing: role definition, tool list, CLAUDE.md content, current date, git status, and user-defined rules.

> 💡 **Plain English**: The System Prompt is like a **new employee onboarding handbook**—company policies (system instructions) + job responsibilities (tool descriptions) + personal memos (CLAUDE.md) + the boss's special notes (user-defined append). Claude "checks in" and reads this handbook every time it starts work.

**Key understanding**: The System Prompt is the **fixed cost of every API call**—no matter what you say, you always pay this "tax" of 15,000–34,000 tokens.

### CLAUDE.md

An "instruction file" written in Markdown that tells Claude about your project's rules and conventions. There are six sources:

| Type | Location | Committed to git? | Priority |
|------|----------|-------------------|----------|
| Project | `.claude/CLAUDE.md` | ✅ | Medium |
| Local | `.claude/CLAUDE.local.md` | ❌ | Medium |
| User | `~/.claude/CLAUDE.md` | — | Low |
| Managed | Enterprise policy path | — | High |
| Upstream | Parent directory's CLAUDE.md | ✅ | Medium |
| Workspace | Workspace root directory | ✅ | Medium |

### Permission

The mechanism that controls whether Claude can execute a given tool call. A **ten-step check chain** produces three outcomes:

| Outcome | Meaning | OS Analogy |
|---------|---------|------------|
| Allow | Allowed, execute directly | `rwx` permission granted |
| Ask | Requires user confirmation | `sudo` password prompt |
| Deny | Denied | Permission denied |

**Six permission modes**: default (daily use), plan (plan-only, no execution), auto-approve (automatic approval), bypassPermissions (bypass), apiServerMode (API mode), headless (headless mode).

### Hook

A mechanism for executing user-defined commands at specific moments in the system lifecycle. The system has **27** event nodes.

**Metaphor**: A toll booth on a highway. When a car (tool call) passes through, the toll booth (Hook) can inspect, let through, or intercept.

> 💡 **Plain English**: Hooks are like **SMS notifications from a parcel locker**—when a package arrives, you're automatically notified = event hook. You can set "notify me when it arrives" or "just leave it at the door" = custom Hook behavior. Exit code 2 is like being told "there's a problem with the package, it has been intercepted and returned."

Key: Exit code **2** = block (intercept the operation), any other non-zero = log the error but don't intercept.

### MCP (Model Context Protocol)

A third-party tool extension standard. External servers register new tools in the format `mcp__serverName__toolName`.

**Metaphor**: The USB protocol. Any manufacturer that builds a device to the protocol can plug it into any computer. Any MCP server that implements the protocol can plug into any AI system that supports MCP.

> 💡 **Plain English**: MCP is like a **MacBook USB adapter hub**—the MacBook only has USB-C ports, but to connect a mouse, keyboard, or projector you need adapters. MCP is Claude's universal adapter, letting it connect to any external tool or service.

### Sandbox

OS-level process isolation. Limits the files, network, and system resources that AI-invoked commands can access.

**Metaphor**: An airlock. The inside of the spacecraft (your system) is safe; outer space (untrusted code) is dangerous. The sandbox is the airlock in between—it allows limited operations while isolating danger.

| Platform | Technology |
|----------|------------|
| macOS | seatbelt profile |
| Linux | bubblewrap + seccomp |

### Settings

**Nine layers** of configuration, from enterprise policy down to user preferences. Higher priority overrides lower priority.

**Metaphor**: Russian nesting dolls. The outermost layer (enterprise policy) sets the broadest boundaries; each inner layer can only adjust within what the outer layer allows.

> 💡 **Plain English**: The settings system is like **layers of clothing**—underwear = default config → shirt = project config → coat = user config → bulletproof vest = enterprise policy. Outer layers cover inner layers, but the bulletproof vest has the highest priority and you can't take it off.

---

## Layer 3: Internal Codenames and Special Names

> These are internal names that appear in the code, not UI vocabulary. Understanding them helps when reading technical-detail chapters.

| Codename | Meaning | Appears In |
|----------|---------|------------|
| `tengu` | Internal project codename for Claude Code | Function names, analytics events, feature flags |
| `queryLoop` | AI main loop | query.ts |
| `AppState` | Global state object | state/AppStateStore.ts |
| `ToolUseContext` | Context during tool execution | Tool.ts |
| `querySource` | "Who initiated this AI call" | Distinguishes main agent / sub-agent / speculative execution |
| `forkedAgent` | AI instance forked from a parent request | Shares Prompt Cache |
| `speculation` | Speculative execution | Runs AI ahead of time while the user is typing |
| `omitClaudeMd` | Skip CLAUDE.md loading | Optimization for read-only sub-agents |
| `CacheSafeParams` | Parameter constraints guaranteeing cache hits | Compile-time type checking |
| `bypass-immune` | Non-bypassable security limits | Permission system |
| `iron gate` | Safety valve for auto mode | Consecutive rejections → forced human review |
| `ant` | Anthropic employee build | Some features are ant-only |
| `tungsten` | tmux integration codename | Swarm mode backend |
| `bagel` | Web browser tool codename | Internal tool |
| `chicago` | Computer Use codename | MCP server |
| `amber_quartz` | Voice mode codename | Feature gate |
| `cobalt_harbor` | Auto-connect codename | MCP auto-discovery |
| `sage_compass` | Advisor system codename | GrowthBook gate |
| `friend-2026-401` | Buddy system codename | April Fools' 2026 release |

---

## Layer 4: System Hierarchy

> Understanding "who contains whom" and "who calls whom" is the foundation for understanding system design.

### From Largest to Smallest

```
Claude Code process
  └── AppState (global state)
        ├── Main Session
        │     ├── Query Loop (main loop)
        │     │     ├── API calls × N
        │     │     ├── Tool calls × M
        │     │     └── Compression checks
        │     ├── Sub-agents × P
        │     │     └── Query Loop (sub-loop)
        │     ├── Speculation agent (background)
        │     └── SessionMemory agent (background)
        ├── MCP connections × Q
        ├── Hook registry
        ├── File history snapshots
        └── Buddy companion
```

### From Caller to Called

```
User input
  → REPL interface (React + Ink)
      → QueryEngine.submitMessage()
          → Assemble system prompt (fetchSystemPromptParts)
          → queryLoop()
              → callModel() (Anthropic API)
                  → Streaming response
              → StreamingToolExecutor (streaming-stage parallelism)
                  → Tool.call() × N
                      → May create sub-agent
                          → Recursive queryLoop()
              → Collect tool_result
              → callModel() again
              → ... until final answer
          → PostSamplingHooks
              → SessionMemory extraction
              → Prompt Suggestion generation
          → fileHistoryMakeSnapshot()
      → [Optional] Speculation launch
```

> **[Chart placeholder 1.3-C]**: Complete system call stack diagram

### Three Data-Flow Highways

1. **Main pipeline**: User input → `queryLoop` → API → tool execution → final answer → render
2. **Background pipeline**: After AI response → SessionMemory + PromptSuggestion + FileHistory + Speculation
3. **Extension pipeline**: MCP server connection → tool registration → plugin/skill/hook loading

---

## Layer 5: Common Confusions Clarified

> These concepts are easily confused. Clearing them up now will save a lot of confusion later.

### Agent vs Tool

| | Agent | Tool |
|--|-------|------|
| What is it | A complete AI instance | A capability |
| Has a `queryLoop`? | ✅ | ❌ |
| Has its own message history? | ✅ | ❌ |
| OS analogy | Process | System call |
| Relationship | `Agent` is a **special kind of Tool** | Tool is a capability invoked by an Agent |

### Hook vs Tool

| | Hook | Tool |
|--|------|------|
| Triggered by | System automatically | AI actively |
| Purpose | Inject logic at key nodes | Execute operations |
| OS analogy | Kernel module | System call |
| Can it block an operation? | ✅ (exit code 2) | ❌ |

### Session vs Context Window

| | Session | Context Window |
|--|---------|---------------|
| Stored in | Disk (JSONL file) | Memory (API request body) |
| Size limit | None (disk space) | ~200K tokens |
| Lifecycle | Persistent | Rebuilt on every API call |
| Relationship | Session may be much larger than Context Window | — |
| OS analogy | File on hard disk | Data in RAM |

### Skill vs Command

| | Skill | Command |
|--|-------|---------|
| Triggered by | AI autonomously decides **or** user `/<name>` | Only user `/xxx` |
| Key field | `whenToUse` description | None |
| OS analogy | Shell script (can be run automatically by cron) | Manually executed command |

### Plugin vs MCP

| | Plugin | MCP |
|--|--------|-----|
| What is it | Feature pack (can contain multiple components) | External tool protocol |
| Can contain | Tools + Skills + Hooks + MCP configs + commands | Only provides tools |
| Relationship | Plugin can contain MCP configs | MCP is one component of a Plugin |
| OS analogy | apt package (can contain multiple programs) | USB device driver |

### Prompt Cache vs Context Compression

| | Prompt Cache | Context Compression |
|--|-------------|-------------------|
| What it does | Reuse the prefix of previous requests | Reduce the size of message history |
| Effect | Lowers cost and latency | Extends conversation lifespan |
| Cost | Requires keeping the prefix stable | Loses some information |
| Relationship | Compression **breaks** cache (because it rewrites messages) | — |
| Design tension | These two are **in tension**—the system seeks balance between them | — |

> 🌍 **How competitors choose differently**: Different AI coding tools make different trade-offs on these concepts. **Aider** uses a "repo map" instead of heavy context compression—pre-loading only relevant function signatures rather than loading everything and then compressing. **Cursor**'s Agent has no multi-layer sub-agent nesting; instead it uses single-layer "multi-step" execution. **GitHub Copilot** has a much smaller tool set than Claude Code (about 10 vs. 40 built-in tool categories), focusing on code completion rather than general-purpose agents. These different choices reflect the classic engineering trade-off between "simple but constrained" and "complex but flexible."

### QueryEngine vs query()

| | QueryEngine | query() |
|--|-------------|---------|
| What is it | Session-level facade (facade, a software design pattern term meaning "unified external entry point") | Turn-level state machine (state machine, like a traffic light switching between fixed states according to rules) |
| Responsibility | Orchestrate one submission (collect messages, check session context, call `ask()`) | Run a single loop iteration (call model → parse → execute tools → decide whether to continue) |
| Lifecycle | Bound to the session | Bound to a single query call |
| OS analogy | Front-desk receptionist (receive mail, register, triage) | Head chef in the back kitchen (take order → cook → serve → check if there's another dish) |
| Common misconception | ❌ "QueryEngine is the execution engine" | ❌ "query() manages the whole session" |
| Source file | `QueryEngine.ts` | `query.ts` (core loop is in `queryLoop()`) |

> 💡 **Plain English**: QueryEngine is the courier company's "customer service desk," responsible for taking orders, verifying addresses, and arranging delivery. `query()` is the actual delivery rider on the electric scooter—each trip (one turn) includes picking up the parcel, delivering it, getting a signature, and checking if there's another order.

### Tool vs Task

| | Tool | Task |
|--|------|------|
| What is it | A capability (what to do) | A managed container (how to manage lifecycle) |
| Focus | Execution logic, permission checks, result formatting | State persistence, foreground/background switching, stop/resume |
| Lifecycle | One invocation | May span multiple turns |
| Relationship | Tool is "the hand that does the work"; Task is "the manager of the hand" | Task uses Tool indirectly via `query()` |
| OS analogy | System call (read/write) | Process control block (PCB) |

### subagent vs teammate

| | subagent | teammate |
|--|----------|----------|
| Creation | AgentTool.call() → fork/local | Assigned by Swarm Leader |
| Communication | Results returned via generator chain (generator = a producer that passes results piece by piece like an assembly line, rather than returning everything at once) | Async communication via Mailbox filesystem (Mailbox = a real file directory; teammates read and write files in this directory to pass messages) |
| Coordination protocol | Simple (call-return) | Complex (idle = not started / plan approval = waiting for approval / shutdown = finished and powered off; three coordination signals) |
| Isolation | Shared kernel or git worktree (git worktree = git's multi-directory checkout feature) | Independent terminal processes (tmux / iTerm2 / in-process are all terminal multiplexers, giving each AI instance its own pane) |
| OS analogy | Child process | Distributed compute node |

### bridge vs remote vs teleport

| | bridge | remote | teleport |
|--|--------|--------|----------|
| Responsibility | Local exposure: let Web/phone attach to local session | Remote execution: send work to cloud CCR to run | Recovery protocol: reconnect to session after crash |
| Direction | Outside → Inside (remote observes local) | Inside → Outside (local pushes to remote) | Time dimension (resume from breakpoint) |
| Key files | `replBridge.ts` | `RemoteAgentTask.tsx` | `bridgePointer.ts` |
| OS analogy | SSH server | Remote job submission (slurm) | Session recovery after power loss (tmux attach) |

> 💡 **Plain English**: bridge is a security camera you installed at home (view from outside), remote is sending a housekeeper to work at someone else's house (you check progress from afar), teleport is saving your game before a power outage and continuing from the save afterwards.

### tool pool vs tool registry

| | tool pool | tool registry |
|--|-----------|---------------|
| What is it | Subset of tools visible to the model in the current turn | Complete list of all registered tools in the system |
| Size | Dynamic (depends on permission mode, feature gate, MCP status) | Relatively fixed (43 built-in + dynamic MCP) |
| Construction | `assembleToolPool()` reassembles on every query call | `getAllBaseTools()` registers at startup |
| OS analogy | System call table available to the current process | Kernel's complete system call table |

### feature() vs GrowthBook

| | feature() | GrowthBook |
|--|-----------|------------|
| Type | Compile-time gate | Runtime experiment |
| When evaluated | Build time, dead code eliminated by Bun bundler | Runtime, pulling config from remote |
| Rollback possible? | ❌ Requires rebuild | ✅ Flipped remotely in seconds |
| Use case | Cut dead code for unreleased features | A/B testing, gradual rollout, emergency killswitch |
| Source | `feature('BUDDY')` literals | `GrowthBook.isOn()` / `GrowthBook.getPayload()` |

### viewerOnly vs "read-only"

| | viewerOnly | "read-only" |
|--|------------|-------------|
| What is disabled | Controller semantics (interrupt, watchdog, title ownership) | All write operations |
| What is kept | Message send/receive, permission handling, tool_result rendering, thumbs up/feedback | Only reads |
| Essence | **Role redefinition**—from "controller" to "observer + light interactor" | Simple permission disable |
| Dependencies | `useAssistantHistory()` + `useRemoteSession()` dual data sources | Single data source |

---

## Layer 6: Order-of-Magnitude Awareness

> Having the right order-of-magnitude intuition for system scale is more valuable than memorizing exact numbers.

| Dimension | Value | Intuition |
|-----------|-------|-----------|
| TypeScript files | ~1,884 | Large project (VS Code ~3,000) |
| Built-in tools | 43 | Medium-sized tool set |
| Slash commands | 101 | Very many—most users only use 5–10 |
| Hook events | 27 | Far more than the 5–6 mentioned in docs |
| Config source layers | 9 | Enterprise-grade complexity |
| Compression mechanism layers | 6 | Gradient design from light to heavy |
| Agent types | 7 | Spectrum from lightweight to fully isolated |
| System prompt size | 15K–34K tokens | The "fixed tax" on every API call |
| Context Window | ~200K tokens | Limited "RAM" |
| MAX_SNAPSHOTS | 100 | 100 file-history snapshot points |
| Prompt Cache savings | 10× | Cache hit = one-tenth the price |
| Module load time | ~135ms | Pre-import parallelism uses this time |

---

## Quick Lookup Index

| If you want to learn about... | Go to... |
|-------------------------------|----------|
| Overall system architecture | Part 1 Chapter 2 |
| Complete code-base map | **Part 2 Chapter 1** |
| Startup sequence | **Part 2 Chapter 2** |
| How prompts are assembled | **Part 2 Chapter 3** |
| How the main loop works | **Part 2 Chapter 4** |
| Full picture of the tool system | **Part 2 Chapter 5** |
| Agent orchestration | **Part 2 Chapter 6** |
| Security and permissions | **Part 2 Chapter 7**, Part 3 Q05, Part 4 Chapter 1 |
| State and persistence | **Part 2 Chapter 8** |
| MCP/Hooks/Plugins/Skills | **Part 2 Chapter 9** |
| Token economics | **Part 2 Chapter 10** |
| Settings system | **Part 2 Chapter 11**, Part 3 Q08 |
| Terminal UI | **Part 2 Chapter 12** |
| Performance tricks before import | Part 3 Q01 |
| Context compression | Part 3 Q02 |
| Streaming tool execution | Part 3 Q04 |
| Speculative execution | Part 3 Q06 |
| CLAUDE.md loading | Part 3 Q07 |
| SessionMemory | Part 3 Q09 |
| Conversation branching and rollback | Part 3 Q11 |
| Multi-Claude collaboration | Part 3 Q14 |
| Buddy companion | Part 3 Q15 |
| Voice mode | Part 3 Q17 |
| Cross-conversation memory | Part 3 Q18 |
| Thinking depth control | Part 3 Q19 |
| Dream Mode (sleep memory) | Part 2 Chapter 13 Section 6 |
| Auto-Memory | Part 2 Chapter 13 Section 7 |
| GrowthBook (remote config) | Part 2 Chapter 13 Section 12 |
| Error retry and degradation | Part 2 Chapter 13 Section 2 |
| Token design philosophy | Part 5 Chapter 2 |
| Cost of the system | Part 6 Chapter 1 |

---

## Key Source Code Entry Points

Below are the most frequently referenced source files in this book. Knowing them in advance will help you locate discussion context more quickly:

- `src/main.tsx` (4,684 lines): The system's startup entry point and React root component
- `src/Tool.ts`: The base class interface for all tools—the starting point for understanding the tool system
- `src/services/api/claude.ts`: The `query()` function—the core driver of the `queryLoop`
- `src/utils/permissions/permissions.ts` (~1,500 lines): The ten-step permission state machine
- `src/utils/settings/settings.ts`: The merge logic of the settings system

## Key Call Chains Quick Reference

> **This section is a fast index for engineer readers**—if you are a humanities reader, you can **skip** this section without affecting your understanding of later chapters. If you are an engineer or browsing the source code, this table helps you quickly locate where each function sits in the system and in what order.
>
> A call chain means: **the sequence of function calls a feature goes through from entry to result**, like dominoes—you knock over the first one (user presses Enter), and the rest fall in sequence (startup chain → execution chain → return result).

Below are the most important call chains in Claude Code. When you see a function name in a later chapter, this table helps you quickly locate its position in the system.

**Startup chain** (what happens after you type `claude`):
```
cli.tsx → main.tsx → setup() → getCommands() → launchRepl() → REPL.tsx → query()
```

**Execution chain** (what happens after AI says "I want to read a file"):
```
tool_use block → runTools()/StreamingToolExecutor → runToolUse()
→ checkPermissionsAndCallTool() → tool.call() → toolResultStorage → write back to message history
```

**Agent chain** (what happens when AI decides "this task is too complex, I'll dispatch a sub-agent"):
```
AgentTool.call() → team/fork/remote/local branching
→ runAgent()/runForkedAgent() → query() (sub-agent reuses the same core loop)
```

**Cross-environment chain** (checking work progress on your Mac mini from your phone):
```
bridge: useReplBridge.tsx → replBridge.ts → Work Poll / SSE → bridge UI
remote: teleportToRemote() → RemoteAgentTask → CCR session → polling → local task update
```

**Context compression chain** (how the system extends life when a conversation gets too long):
```
applyToolResultBudget → snipCompact → microcompact
→ applyCollapsesIfNeeded → autocompact → reactiveCompact (when triggered)
```

> 💡 **Plain English**: These five chains are like the body's five major systems—the startup chain is "waking up in the morning" (from opening your eyes to getting out of bed), the execution chain is "doing work" (from receiving a task to completing it), the Agent chain is "asking a colleague for help" (from realizing you're overwhelmed to finding a coworker), the cross-environment chain is "checking on home while traveling" (from opening your phone to seeing progress), and the compression chain is "tidying your desk" (from cluttered to cleared so you can keep working).

---

## On the Limits of Terminology

It is worth noting that the boundaries between these concepts are not always crystal-clear. In actual source code, the meaning of "Agent" depends on context—sometimes it refers to a subprocess (Task), sometimes to a Coordinator worker node. Likewise, "permission" has different meanings at different levels—tool-level permissions and enterprise policy-level permissions are entirely different mechanisms. If a term confuses you in a later chapter, it may be because it has a special meaning in that context—come back here to confirm its base definition, then notice how that chapter extends or narrows the definition.