Home / Fundamentals and the agent loop

Claude Code and the agent loop

Claude Code chains reflection, a real tool call and reading the result in a loop until the goal is reached, it does not answer once like a chat.

Claude Code does not return a single reply and then wait for a new question. Faced with a goal, it thinks about what action to take, calls a real tool, reading a file, running a command, modifying code, then observes what that tool produced before deciding what comes next. This loop repeats as many times as needed, until the goal is reached or control is handed back to the user.

What the loop changes compared with a chat

A classic conversational assistant produces a reply and stops there. Claude Code actually runs the commands it proposes, reads what they return on standard output and standard error, and adjusts its plan based on that result. Giving a complete goal, rather than a sequence of instructions broken down step by step, lets this loop deploy its own intermediate steps. A request phrased as fix the failing test in calc.test.js triggers a sequence that no one needs to spell out in advance: reading the test file, running the suite, reading the error message, fixing it, running it again.

Goal received: fix the failing test in calc.test.js

Reflection: read the test file to understand the failure
Tool: reading calc.test.js
Observation: the test expects 4, the function returns 5

Reflection: read the function concerned
Tool: reading calc.js
Observation: an addition replaces a subtraction

Reflection: fix the faulty line
Tool: editing calc.js
Observation: file modified

Reflection: check that the test now passes
Tool: running the test suite
Observation: loop finished, control handed back

Interrupting without losing the loop

The loop runs visibly in the terminal: every reflection, every tool called and every observation displays as it happens, not just the final result. This makes it possible to follow a long task without having to restart it to know where it stands, and to interrupt it partway through if the direction it is taking is not right, while keeping what has already been accomplished.

What feeds each turn of the loop

Each reflection draws on what the session already knows about the project. Part of this knowledge comes from a file read automatically at the start of the session, CLAUDE.md, covered in the next lesson, which sets rules before even the first turn of the loop. Without a complete goal or starting context, the loop still runs, but it then spends more turns discovering information that a memory file would already have carried.