47  47. How Claude Code Works: The Agentic Loop and Tools

When you ask Claude Code to fix a bug, it doesn’t just type an answer. It reads files, runs commands, checks the results, and tries again. This page explains the loop behind that behavior, the tools that make it possible, and how the other pieces you’ll hear about (MCP servers, skills, hooks, plugins…) fit together.

47.1 The agentic loop

As of Oct 6, 2026 · Official docs: How Claude Code works

For every task, Claude works through three phases, over and over, until the task is done. The docs call this the agentic loop:

 your prompt
     │
     ▼
 ┌────────────────┐
 │ gather context │ ◄───────────────┐   read files, search, check git
 └───────┬────────┘                 │
         ▼                          │
 ┌────────────────┐                 │
 │  take action   │                 │   edit files, run commands
 └───────┬────────┘                 │
         ▼                          │
 ┌────────────────┐  not done yet   │
 │ verify results │ ────────────────┘   run tests, read the output
 └───────┬────────┘
         ▼ done
   answer to you          (you can interrupt at any point with Esc)

The phases blend together, and the loop adapts to the request. A question about your code may only need the first phase. “Fix the failing tests” might go like this:

  1. Run the test suite to see what fails.
  2. Read the error output.
  3. Search for the relevant source files.
  4. Read those files to understand the code.
  5. Edit the files to fix the problem.
  6. Run the tests again to verify the fix (and loop back if they still fail).

Each step gives Claude new information that decides the next step. You are part of the loop too: you approve actions, you can type a correction while Claude works, and Esc stops it. An agent, in this sense, is a model plus tools plus this loop (see AI-Assisted Development).

47.2 The model and the harness

As of Oct 6, 2026 · Official docs: How Claude Code works · Glossary

Two different things are working together:

  • The model (Claude: Opus, Sonnet, and so on) does the reasoning. When the docs say “Claude decides”, they mean the model.
  • The harness is Claude Code itself: the program around the model. It supplies the tools, decides what the model gets to see (its context), enforces your permission settings, runs the loop, and saves your sessions.

An analogy: the model is a brilliant consultant on a phone call; the harness is the office around them, with the keys to your filing cabinet, a person who carries out their requests, and rules about what needs your signature.

The model never touches your computer directly. It asks for an action; Claude Code checks your permissions, carries it out, and sends the result back:

 Claude (model)               Claude Code (harness)            your computer
 "Read src/index.html"  ───►  check permissions, run Read  ───►  the file
        ▲                                                           │
        └──────────── the file's contents come back as text ◄───────┘

47.3 Tools: how Claude acts

As of Oct 6, 2026 · Official docs: Tools reference

A tool is an action Claude can ask Claude Code to perform: read a file, edit code, run a shell command, search the web, start a helper agent. Without tools, a language model can only reply with text (see How Large Language Models Work). With tools, it can act. The main built-in tools, with their exact names:

Tool What it does Asks you first (Manual mode)?
Read Reads a file (also images, PDFs, and notebooks) No, inside the working directory
Edit Changes part of a file by replacing exact text Yes
Write Creates a file, or overwrites a whole file Yes
Bash Runs a shell command Yes, except a built-in set of read-only commands such as ls, cat, pwd, and git status
PowerShell Runs a PowerShell command (mainly on Windows) Yes
Glob, Grep Find files by name pattern; search inside files No, inside the working directory
WebFetch Fetches a web page and extracts what Claude asked for Yes, except some documentation sites
WebSearch Searches the web Yes
Agent Starts a subagent (a helper with its own conversation) No; the subagent’s own actions are checked
Skill Runs a skill Yes
AskUserQuestion Asks you a multiple-choice question No
ExitPlanMode Presents a plan for your approval Yes

The last column describes Manual mode. In auto mode, a safety classifier decides most of these instead of you (see Permissions, Modes, and Safety). The full list in the docs has more than forty tools, many for special situations; to see what your session has, ask Claude “What tools do you have access to?”

In the conversation, a tool call shows the tool and its target, for example Read(src/index.html) or Bash(git status) (some labels differ slightly from the official names). Press Ctrl+O to see every call in detail.

On macOS, Linux, and WSL, Claude Code leaves the Glob and Grep tools out of the default set. Claude searches with find and grep through the Bash tool instead (Claude Code supplies its own built-in versions of both), so in your transcript you see Bash(grep ...) rather than Grep(...). On Windows, Glob and Grep are part of the default set. Similarly, the to-do checklist tools (TaskCreate, TaskList, …) are included by default only with older models (Opus 4.7, Sonnet 4.6, Haiku 4.5, and earlier), not with the current models. Details like these change between versions, which is why the tools reference page is worth bookmarking.

WebFetch takes a URL and a question. It downloads the page and converts it to Markdown; then, for most pages, a separate model call answers the question about the page, and Claude receives that answer rather than the raw page. The docs list this as one of the safeguards against hidden instructions on web pages (prompt injection), but it makes WebFetch “lossy”: if the answer says the page doesn’t mention something, the question may simply not have asked about it. WebFetch also refuses localhost; Claude uses curl through Bash to reach a local web server.

47.4 One mental model for all the pieces

As of Oct 6, 2026 · Official docs: Extend Claude Code · Glossary · Plugins overview · Mods overview

People often mix up tools with the other things you can add to Claude Code. They are different kinds of things:

Claude Code (the harness)
├── the model (Claude) ...... reasons and decides which tool to call next
├── built-in tools .......... Read, Edit, Write, Bash, WebFetch, Agent, Skill, ...
├── MCP servers ............. connect outside services and add MORE tools
├── skills .................. instructions for a kind of task (loaded via the Skill tool)
├── subagents ............... helper agents with their own context (started via the Agent tool)
├── hooks ................... your commands that run automatically on events
├── CLAUDE.md ............... instructions loaded into every session
└── plugins ................. installable packages of skills, subagents, hooks, MCP servers, ...
    └── mods ................ plugins whose code runs inside Claude Code and customizes it
Piece What it is Example Details
Tool An action Claude can call Read, Bash this page
MCP server A program that gives Claude extra tools (and data) from another service a GitHub server with a “create issue” tool MCP Servers
Skill A SKILL.md file of instructions or knowledge; Claude loads it when relevant, or you run it as /name. It is not a new tool a “write release notes” checklist Skills
Subagent A helper agent with its own context window and tools; it returns a summary the built-in Explore subagent Subagents
Hook A handler (usually a shell command) that Claude Code runs at a fixed moment, such as right before or after a tool call; it can even block the call run a code formatter after every edit Hooks
Plugin A package that bundles skills, subagents, hooks, MCP servers, and more, installed as one unit a team’s code-review setup Plugins
Mod A plugin made of JavaScript or TypeScript code that runs inside Claude Code and changes how it looks and behaves a pane that charts context usage Mods

The most important difference: Claude chooses when to use a tool or a skill, but a hook always runs when its event happens, whatever Claude thinks. So “never edit .env” written in CLAUDE.md is a request, while a hook or a permission rule that blocks the edit is enforcement. Extending Claude Code: The Big Picture shows when to use which.

47.5 Why it acts differently from a chat window

As of Oct 6, 2026 · Official docs: How Claude Code works · Glossary

The same Claude models power ordinary claude.ai chats and Claude Code, yet Claude Code behaves very differently. The model is the same; the harness around it is not:

  1. Tools. In a regular chat, Claude mostly works with what you type, upload, or connect. In Claude Code it can read your whole project, run your commands, and edit your files itself.
  2. Context. Claude Code automatically tells the model about your environment: the working directory, operating system, shell, whether the folder is a Git repository (with its branch, status, and recent commits), and the instructions in your CLAUDE.md files.
  3. System prompt. Before your conversation, Claude Code sends its own instructions on every request (the system prompt): how to use the tools, how to behave safely, and how to format answers for software work.
  4. The loop. Claude Code keeps acting and checking until the task is done, instead of stopping after one reply.

Before you type anything, Claude Code loads: its system prompt; Claude’s own auto memory notes from earlier sessions (the start of a MEMORY.md file); environment information and Git status; the names (not full descriptions) of any MCP tools; one-line descriptions of available skills; and your CLAUDE.md files. Every file Claude reads and every command output then adds more. All of this shares one context window, and when it fills up, Claude Code summarizes older parts. Run /context to see what is using space. Managing this is covered in Context, Models, Effort, and Usage.

Practice Questions

Easy

Question 1 · Short answer

Name the three phases of the agentic loop.

Gather context, take action, and verify results. Claude repeats them until the task is done (and you can interrupt at any point).

Question 2 · Multiple choice

In the docs, what is the “agentic harness”?

  1. The Claude model that does the reasoning
  2. Claude Code itself: the layer around the model that provides tools, manages context, enforces permissions, and runs the loop
  3. A safety belt that stops Claude from deleting files
  4. The terminal window

b. Claude is the model inside; Claude Code is the harness around it. The model (a) does the reasoning but has no access to your computer by itself. Permission checks are one job of the harness, not the whole thing (c), and the terminal (d) is just where you see it.

Question 3 · Matching

Match each built-in tool with what it does.

Tool What it does
1. Read A. Runs a shell command
2. Edit B. Creates a file or overwrites a whole file
3. Write C. Starts a subagent
4. Bash D. Reads a file
5. WebFetch E. Replaces exact text inside a file
6. Agent F. Fetches a web page and extracts information

1 → D, 2 → E, 3 → B, 4 → A, 5 → F, 6 → C.

Question 4 · True or false

Without tools, a language model can only respond with text.

True. Tools are what make Claude Code an agent: they let Claude read files, run commands, edit code, and search the web. Each tool result then informs the next step.

Question 5 · Multiple choice

Which piece adds new tools that connect Claude to an outside service such as GitHub or a database?

  1. A skill
  2. A hook
  3. An MCP server
  4. CLAUDE.md

c. An MCP server is a program that gives Claude extra tools (and data). A skill (a) gives instructions or knowledge, a hook (b) runs your command on an event, and CLAUDE.md (d) holds instructions loaded every session; none of these adds tools.

Medium

Question 6 · Ordering

Put these steps for “fix the failing tests” in a sensible order: (A) edit the source files, (B) run the tests again, (C) run the test suite, (D) read the relevant source files, (E) read the error output.

C → E → D → A → B. Run the tests to see what fails, read the errors, read the code involved, edit it, and run the tests again to verify. If they still fail, the loop continues.

Question 7 · Matching

Match each piece with its description.

Piece Description
1. Tool A. Runs automatically at a lifecycle event, such as before a tool call
2. Skill B. A package that bundles several of the other pieces
3. Hook C. An action Claude can call
4. Subagent D. Instructions or knowledge for a type of task, in a SKILL.md file
5. Plugin E. A plugin whose code runs inside Claude Code and changes how it looks and behaves
6. Mod F. A helper agent with its own context window that returns a summary

1 → C, 2 → D, 3 → A, 4 → F, 5 → B, 6 → E.

Question 8 · Scenario

Your team wants a code formatter to run after every file edit, with no exceptions, even if Claude forgets. Which piece fits best, and why?

A hook (one that runs after each edit tool call). Hooks are deterministic: Claude Code runs them every time the event happens. An instruction in CLAUDE.md or a skill only asks Claude to do it, and Claude might not.

Question 9 · Scenario

You keep pasting the same five-step checklist for writing release notes into the chat. Which piece fits best?

A skill: a SKILL.md file holding the checklist. Claude can load it when it is relevant, or you can run it yourself as /release-notes (or whatever you name it). Its full text only loads when it is used, unlike CLAUDE.md, which is loaded into every session.

Question 10 · Predict

Maria, on a Mac, asks Claude to find every file that mentions “portfolio”. In the transcript she sees Bash(grep -rn "portfolio" .) instead of a Grep tool call. Why?

On macOS, Linux, and WSL, Claude Code leaves the Grep and Glob tools out of the default tool set. Claude searches with grep and find through the Bash tool instead (Claude Code provides its own built-in versions of both). On Windows, the Grep and Glob tools are part of the default set.

Question 11 · Short answer

In Manual mode, which of these run without asking you: Read on a file in the project, Edit on a file in the project, Bash running ls, Bash running npm install?

Read inside the project and Bash running ls run without asking (ls is in the built-in set of read-only commands). Edit and Bash running npm install ask first, because they change things.

Question 12 · Compare

What is the difference between the Edit and Write tools?

Edit makes a targeted change: it replaces one exact piece of text in an existing file with new text. Write creates a new file or overwrites an entire file with the full content provided. For small changes to existing files, Claude uses Edit.

Hard

Question 13 · Long answer

The same Claude model powers a claude.ai chat and Claude Code. Explain why it behaves so differently in Claude Code.

The model is the same, but the harness is different:

  • Tools: Claude Code lets the model read your project, run commands, and edit files itself; in a chat it mostly works with what you type, upload, or connect.
  • Context: Claude Code automatically adds information about your environment (working directory, OS, Git branch and status) and your CLAUDE.md instructions.
  • System prompt: Claude Code sends its own instructions about using tools, safety, and formatting for software work on every request.
  • Loop: Claude Code keeps gathering context, acting, and verifying until the task is done, instead of producing one reply.

Question 14 · Evaluate

A classmate says: “A skill is just another tool, like Read or Bash.” Is that right? Explain.

Not quite. A tool is an action Claude can call. A skill is instructions or knowledge (a SKILL.md file) for a type of task. Skills don’t add new tool entries: Claude loads a skill through the existing built-in Skill tool, and the skill’s instructions then tell Claude how to use its ordinary tools for that task. (By contrast, an MCP server really does add new tools.)

Question 15 · Explain why

Why is the “verify results” phase so important, and how can you help Claude do it well?

Without verification, the only thing deciding that the work is finished is Claude’s own belief, and code that looks plausible can still be wrong. Verifying (running tests, building the project, running the app, comparing a screenshot) gives Claude real evidence and lets it loop back and fix mistakes. You help by giving Claude a check it can run: tell it the test command, how to start the app, or what the correct output should look like.

Question 16 · Find the bug

A student wrote this in their notes. Find and fix the mistake: “Hook: Claude decides when it is useful and runs it, just like a skill.”

Hooks are not chosen by Claude. A hook is deterministic: Claude Code runs it every time its lifecycle event happens (for example right before or after a tool call), whatever Claude thinks. Skills are the ones Claude decides to use (or you invoke with /name). Corrected note: “Hook: a handler that Claude Code runs automatically on a specific event; it can even block an action.”

Question 17 · Scenario

Claude uses WebFetch on a documentation page and reports that the page “does not mention Windows”. You are fairly sure it does. What might have happened, and what can you ask Claude to do?

WebFetch does not give Claude the raw page: a separate model call answers the specific question Claude asked about the page, and Claude only receives that answer. If the question didn’t ask about Windows, the answer may leave it out, so the result is lossy. Ask Claude to fetch the page again with a more specific question (for example “list every mention of Windows”), or to download the raw page with curl.

Question 18 · Compare

When would you want a subagent rather than doing the work in your main conversation?

When a side task would flood your main conversation with material you won’t need again, for example exploring dozens of files to answer one question. A subagent works in its own context window and returns only a summary, so your main context stays clean. It is also useful for running independent tasks in parallel or for a specialized helper with limited tools.

Challenge

Question 19 · Hands-on

In a practice project, ask Claude “What tools do you have access to?”. Then give it a small task (for example “find where the page title is set and change it to My Portfolio”) and press Ctrl+O to open the detailed transcript. List each tool call it made and label each one as gather context, take action, or verify.

A typical answer: Claude’s tool list included Read, Edit, Write, Bash, WebFetch, WebSearch, Agent, Skill, and others (the exact list depends on your platform and version). For the task, the transcript might show Bash(ls ...) or a search (gather context), Read(src/index.html) (gather context), an edit to src/index.html (take action), and a final Read or git diff to check the result (verify). A good answer notes which calls asked for permission and which ran without asking.

© 2025-2026 Y. Rosenthal. All rights reserved.