AI Engineering

A language model is a text-to-text function. It has no filesystem handle, no shell, no network socket. Given “explain the code in complex.py”, the only correct response is that it cannot read files.

sequenceDiagram
    participant You
    participant LLM
    You->>LLM: Explain the code in complex.py
    LLM-->>You: No file access — supply the contents

Claude Code is the process that closes that gap. It is an agentic harness: it supplies tools, executes them on the model’s behalf, and drives the model in a loop until the task is done.

sequenceDiagram
    participant You
    participant CC as Claude Code
    participant LLM
    participant FS as Filesystem
    You->>CC: Explain the code in complex.py
    CC->>LLM: prompt + tool definitions
    LLM-->>CC: tool call — Read(complex.py)
    CC->>FS: open, read
    FS-->>CC: contents
    CC->>LLM: tool result
    LLM-->>CC: JWT validation, rejects expired tokens
    CC-->>You: JWT validation, rejects expired tokens

The model never touches the disk. It emits a tool call; the harness executes it and returns the result. Every capability and every safety control in Claude Code is a property of that intermediary position.

The agentic loop

The harness runs the exchange repeatedly. Each iteration has three phases — gather context, take action, verify results — and the model chooses the next action from the previous result.

flowchart LR
    P([Prompt]) --> G[Gather context]
    G --> A[Take action]
    A --> V[Verify results]
    V -->|incomplete| G
    V --> D([Done])

The phases are descriptive, not sequential. A codebase question may never leave gather; a refactor spends most of its iterations in verify.

For the task “fix the failing tests”, a typical trace is six tool calls:

Note that the first call is an action, not context gathering: running the suite is how the failure set is determined. Step 3 exists only because step 2 returned a stack trace; step 6 exists only because step 5 modified a file. Each call is conditioned on the previous result — that dependency is what distinguishes an agent from a scripted sequence.

Interrupt semantics

Two mechanisms, with different effects:

The second is the one to use when the current command is harmless but the direction is wrong.

Tools

Tools are the harness’s exposed capabilities. They fall into five categories:

Forty-five tools are available. The complete set, with the column that determines Chapters 3 and 4:

The permission column follows one rule: read-only operations do not prompt; state-changing and network operations do. Reading, searching and listing are unrestricted. Editing, executing and network access require approval. The permission system in Chapters 3 and 4 is a set of refinements on that rule, not a departure from it.

Tool coverage is extensible: skills add procedures, MCP adds external services, hooks add enforced behaviour, and subagents add isolated context. Each has its own chapter.

What a session loads

Starting claude in a directory gives the session access to:

Files are read on demand, not at startup. A repository’s size does not determine context consumption; the number of files actually opened does.

Because the harness sees the whole project rather than one open buffer, a single request can span multiple files, a configuration change and a test run in one unit of work.

Session state on disk

The conversation is written locally as it happens: every message, tool call and result appends to a plaintext JSONL file under ~/.claude/projects/. That file is what makes resuming, forking and rewinding possible — they are operations on a transcript, not on a server-side session.

Separately, before Claude edits a file, the harness snapshots the current contents. Checkpoints are independent of git and survive across resumes. They cover file edits only: changes made by shell commands, and anything affecting remote systems, are outside their scope. Chapter 9 covers both mechanisms.

Context window

The context window holds conversation history, file contents, command output, CLAUDE.md, auto memory, loaded skills and system instructions. As it fills, Claude Code clears older tool output first, then summarises the conversation. Requests and key code survive; detailed instructions given early in a conversation may not — which is the argument for putting durable rules in CLAUDE.md rather than in chat. /context reports current usage. Chapter 8 covers the mechanics.

MCP tool definitions are deferred by default and loaded on demand through tool search, so connected servers cost only their tool names until a specific tool is used.

Models

The harness is model-agnostic within the Claude family. Sonnet handles most coding work; Opus provides stronger reasoning for architectural decisions. Select with --model <alias> at launch or /model during a session, and set reasoning depth with --effort or /effort. Chapter 5 covers the selection and its cost implications.

Execution environments and interfaces

The loop and the tool set are identical across all of them. What varies is where code executes:

Interfaces: terminal, VS Code, JetBrains, desktop app, claude.ai/code, mobile, Slack, and CI via GitHub Actions or GitLab. All read the same CLAUDE.md, settings and MCP configuration. Chapter 20 covers them individually; this handbook uses the terminal.

Installation and authentication

Requirements: a terminal, a project, and a Claude subscription (Pro, Max, Team, Enterprise), a Claude Console account, or access via Amazon Bedrock, Google Cloud or Microsoft Foundry.

# macOS, Linux, WSL — auto-updates in the background
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Homebrew — does not auto-update; run brew upgrade yourself
brew install --cask claude-code

Homebrew provides two casks: claude-code tracks the stable channel (roughly a week behind, skipping releases with known regressions) and claude-code@latest tracks current. winget install Anthropic.ClaudeCode and apt/dnf/apk are also available.

Verify and authenticate:

claude --version     # prints a version followed by (Claude Code)
cd /path/to/project
claude               # browser auth flow on first run

Credentials persist; /login switches accounts later. Setting ANTHROPIC_API_KEY skips the login prompt and asks you to approve the key instead. On native Windows, install Git for Windows so the Bash tool is available; without it Claude Code falls back to PowerShell. WSL does not need it.

Two commands to know at setup time: /init generates a starting CLAUDE.md from the codebase, and /doctor runs a configuration checkup that diagnoses and offers to fix installation and settings problems.

Permission mode at first run

On Pro, Max and Team plans, interactive terminal and VS Code sessions start in auto mode, where a classifier reviews actions in the background instead of prompting you. On other plans the starting mode is Manual, which prompts before edits and shell commands. Shift+Tab changes mode at any point. Chapter 3 covers all six modes and the classifier’s rules.

Prompt construction

Specify the target and the symptom; leave the procedure unspecified. The harness derives the procedure from tool results, and a prescribed sequence discards that.

The checkout flow fails for users with expired cards.
Relevant code is in src/payments/. Investigate and fix.

This is shorter than naming files and line numbers, and it does not encode an assumption about where the defect is. Corrections mid-task are cheaper than re-prompting: the accumulated context from the failed attempt is retained.

Summary

• A language model produces text. Claude Code supplies tools, executes them, and drives the model in a loop.
• The loop is gather → act → verify, with each call conditioned on the previous result.
• Read-only tools do not prompt; state-changing and network tools do. That asymmetry is the basis of the permission system.
• Files load on demand; repository size does not dictate context usage.
• Esc cancels the in-flight tool call; typed text is read at the next decision point without interrupting.

Chapter 3 covers the six permission modes, the auto-mode classifier, and the thresholds at which it stops trusting itself.