How Claude Code Works — Deep Dive

The Agentic Loop

Claude Code is not a chatbot. It is an agent — a system that takes actions, observes results, and loops until the task is done.

User prompt
    │
    ▼
┌─────────────────────────────────┐
│  Plan: what steps are needed?   │
└──────────────┬──────────────────┘
               │
    ┌──────────▼──────────┐
    │  Choose a tool call  │  ◄─────────┐
    └──────────┬──────────┘             │
               │                        │
    ┌──────────▼──────────┐             │
    │  Execute the tool    │             │
    └──────────┬──────────┘             │
               │                        │
    ┌──────────▼──────────┐             │
    │  Observe the result  │             │
    └──────────┬──────────┘             │
               │                        │
    ┌──────────▼──────────┐             │
    │  Task complete?      │── No ───────┘
    └──────────┬──────────┘
               │ Yes
    ┌──────────▼──────────┐
    │  Reply to user       │
    └─────────────────────┘

This loop runs entirely on Claude’s side. You see the final answer, but many tool calls may happen silently in between.

The Tool System

Everything Claude does is through tools. Claude cannot do anything that isn’t backed by a tool.

Built-in Tools

Tool	What it does
Read	Read a file from disk
Write	Create a new file
Edit	Modify part of an existing file
Glob	Find files by pattern
Grep	Search file contents with regex
Bash	Execute a shell command
WebFetch	Fetch a URL
WebSearch	Search the web
Agent	Spawn a subagent
TodoWrite / TodoRead	Manage task lists

How a Tool Call Works

1. Claude decides it needs to read a file
2. Claude generates a tool call: Read("src/index.ts")
3. The harness intercepts — checks permissions
4. If allowed: executes the read, returns content
5. If denied (or user says no): Claude sees an error and adjusts
6. Claude incorporates the file content and continues planning

Parallel Tool Calls

Claude can issue multiple tool calls in a single step when they are independent:

Step 1: Read("src/auth.ts"), Read("src/routes.ts"), Read("tests/auth.test.ts")
         ↓ all three run in parallel ↓
Step 2: Edit("src/auth.ts") based on findings

This is why Claude Code is fast — it doesn’t wait for each read one by one.

How Context Is Built

Claude’s context window at any point contains:

┌────────────────────────────────────────────┐
│  System prompt (built-in + CLAUDE.md)      │
│  Auto memory index (MEMORY.md)             │
│  Project files (if loaded)                 │
├────────────────────────────────────────────┤
│  Conversation history                      │
│  ├── User messages                         │
│  ├── Claude's text responses               │
│  └── Tool call results (file contents,     │
│       command output, search results)      │
└────────────────────────────────────────────┘

Context window size is finite. As the conversation grows, older content is compressed or dropped. The /compact command or auto-compact (when enabled) summarizes the conversation to free space.

How Files Are Read

Claude does NOT load your entire codebase upfront. It reads files on demand as it needs them.

The typical flow for “fix this bug”:

1. Claude reads the file mentioned in your prompt
2. Discovers imports → reads those files
3. Discovers the test file → reads it
4. Reads related config if needed
5. Makes targeted edits

This is why naming the file in your prompt helps: it tells Claude where to start.

How CLAUDE.md Is Loaded

Session start
    │
    ▼
Load managed CLAUDE.md (org-wide)
    │
    ▼
Load ~/.claude/CLAUDE.md (user)
    │
    ▼
Load ./CLAUDE.md or ./.claude/CLAUDE.md (project)
    │
    ▼
Load ./CLAUDE.local.md (personal, gitignored)
    │
    ▼
Load .claude/rules/*.md for any files already in context
    │
    ▼
All loaded content goes into the system prompt

Import resolution: @./path/to/file.md is resolved once at load time and the file content is inlined. It is not re-read on every turn.

Path-scoped rules are loaded dynamically: when Claude opens a file that matches a rule’s paths: pattern, that rule file is added to the context for that turn.

How Sessions Work

A session = one conversation thread with a unique ID.

~/.claude/projects/<project-hash>/sessions.jsonl

Each session stores:

• All messages and tool calls
• Which files were read/edited
• Timestamps and cost

Session lifecycle:

• claude → new session
• claude --continue → resumes most recent session
• claude --resume → pick any past session
• Ctrl+D or /exit → ends session cleanly

Sessions are kept for cleanupPeriodDays (default 30 days), then purged.

How Permissions Flow

User types a prompt
    │
    ▼
Claude plans a tool call
    │
    ▼
Harness checks: is this tool in the allow list?
    │
    ├── Yes, pre-approved → execute immediately
    │
    ├── No, in deny list → return error to Claude
    │
    └── Unknown → check defaultMode
              │
              ├── default / acceptEdits → prompt user
              │       User approves → execute
              │       User denies → return error
              │
              ├── auto → analyze safety → execute or prompt
              │
              ├── plan → block all writes/shell
              │
              └── bypassPermissions → execute always

Pre-approved tools (in allow list) never prompt. This is why configuring your allow list in .claude/settings.json makes your workflow much smoother.

How Auto Memory Works

During a session:
    Claude notices something worth remembering
    (e.g. "tests require npm install first")
           │
           ▼
    Claude calls Write / Edit on a file in
    ~/.claude/projects/<hash>/memory/
           │
           ▼
    Updates MEMORY.md index

Next session:
    MEMORY.md is loaded into system prompt
    Claude reads referenced memory files on demand

The memory system is just files — you can read, edit, or delete them at any time.

How Subagents Work

When Claude spawns a subagent:

Main Claude session
    │
    │  Agent("Explore", "find all auth middleware")
    ▼
┌──────────────────────────────┐
│  New Claude instance         │
│  - Fresh context window      │
│  - Inherits tool permissions │
│  - Isolated from main session│
│  - Runs in parallel (opt)    │
└──────────┬───────────────────┘
           │
           │  Returns: result text
           ▼
Main Claude continues with result

Subagents:

• Have their own isolated context (they don’t see your full conversation)
• Can be given restricted tool lists
• Can run in separate git worktrees (so their file edits don’t conflict)
• Are billed separately (their tokens count toward your usage)

What Happens When You Press Enter

1. Your message is appended to the conversation
2. All registered hooks for PreMessage fire (if any)
3. Claude processes the full context and generates a response
4. If the response contains tool calls, the harness executes them
5. Tool results are added to context
6. Claude generates the next response
7. This repeats until Claude produces a final text-only response
8. PostMessage hooks fire
9. The response is displayed to you

How Compact / Auto-Compact Works

When the context grows large:

1. /compact or auto-compact triggers
2. Claude is asked to summarize the conversation so far
3. The summary replaces the conversation history
4. Full context of recently-read files is retained
5. The summary is much smaller → Claude can continue

This is lossy — detail from early in the conversation may be lost. Use /recap before /compact to preserve a human-readable summary.

🧠 Quick Recall

• Trick: “One model + tools in a loop — no magic.”
• Everything is visible: Ctrl+O shows the full transcript.

👨‍🏫 Teach It

• Say: understanding the loop is what demystifies every failure later.
• Show: one turn in verbose transcript — name each tool call as it streams.
• They’ll trip on: thinking Claude “remembers” — every turn re-sends everything (caching makes it cheap).

---

Learning path: ⬅ 05-interactive-mode-shortcuts.md · Index · ➡ 07-tools-deep-dive.md