00A. Conceptual How It Works

Why This Chapter Exists

Before reading the source tree as engineering material, it helps to have a clean conceptual picture of how the product behaves. This chapter adapts the structure used in an external Mintlify overview and turns it into a study-oriented bridge chapter for this handbook.

Source reference: How Claude Code works

The Core Agent Loop

1. User sends a message in interactive mode or non-interactive mode.
2. The client assembles context: system context, user context, memory files, tools, and current environment facts.
3. The model responds with text and possibly structured tool calls.
4. The client checks permissions before each tool call.
5. Approved tools run and return results.
6. The loop repeats until the model stops calling tools or needs user input.

This is the best “first mental model” for the whole source tree. Almost every major subsystem exists to support one stage of this loop.

Context Loading

Conceptually, the client prepends context before every important model call. That context includes:

• System-level environment facts such as date and repo state
• User-level memory files and project notes
• The available tool inventory and related instructions

In our source-oriented reading, this conceptual block maps to context.ts, main.tsx, Tool.ts, tools.ts, and memory-related utilities.

Tool Execution Model

Conceptually, the model does not just “run commands.” It emits structured tool-use requests. The client then becomes the enforcement layer:

• It validates the tool input.
• It checks permission mode and rules.
• It may ask the user, auto-approve, or deny.
• It appends tool results back into the conversation.

In our handbook, this maps to Tool.ts, tools.ts, tools/BashTool/*, filesystem permission helpers, and the shared utils/permissions/* layer.

Interactive vs. Non-Interactive Mode

Sub-Agents and Delegation

Conceptually, the client can hand part of the job to a sub-agent. That sub-agent may have its own tool scope, task description, background behavior, and isolation mode. This is why the product starts to resemble a task system rather than one chat loop.

In this handbook, that maps to tools/AgentTool/*, task state, teammate support, and worktree or remote isolation helpers.

Conversation Storage and Compaction

Conceptually, the session is not just “current prompt + answer.” It is stored on disk, resumed later, compacted when it grows too large, and enriched by memory extraction. This is why history, compaction, and memory are all major subsystems in the tree.

In our source map, this corresponds to history.ts, services/compact/*, and services/SessionMemory/*.

How To Use This Chapter