Agent loop

The agent loop is the cycle Claude Code runs on each task: it gathers context, takes an action with a tool, checks the result, and repeats until the work is done or you stop it.

Last updated: 29 Sep, 2026 · Claude Code

A model on its own can only write text. Claude Code is the part around the model that reads files, runs commands and edits code, and the loop between them is what you are using.

The video draws the loop on a whiteboard. A prompt goes in, such as "create a UI for tracking calories". The loop has three parts: gather context from the project, take action on the task, verify the results. If the result is not good enough it goes round again, gathering more context and acting again, until it is satisfied and the task is done.

You are part of that loop. You can interrupt it, add context, change the instruction, switch the model, or add a tool such as web search. The loop also adapts to the job: a question about the codebase may only need the first part, while a bug fix can cycle through all three many times, running the code and trying again until the bug is gone. The docs call this an agentic harness around Claude: the tools, the context management and the execution environment that turn a language model into a coding agent.

The same loop as a picture comes next, then one turn captured on this course's project.

The same turn, captured

The --output-format stream-json flag prints every step of a run instead of only the answer. This is that run, with the tool calls left in and the long results cut short so it fits (shown here as a table for reading; the raw flag prints one JSON object per line).

claude -p "Which function decides the short code? Name the file and function only." \
  --output-format stream-json --verbose

TOOL   Bash   grep -r "short" /tmp/linkshort --include="*.py" | head -20
RESULT /tmp/linkshort/shorten.py:"""Turn a long URL into a short code, and back again."""
TOOL   Read   /tmp/linkshort/shorten.py
RESULT 1  """Turn a long URL into a short code, and back again."""
TEXT   **shorten.py** - next_code()
RESULT turns: 3   duration: 7.6s   cost: $0.017

Two tools and one sentence. It searched, read the file the search pointed at, and answered. Three turns means three trips to the model, because every tool result goes back to the model before it decides what to do next.

That is the loop. Everything else in this course is a way of changing what happens inside it: which tools are allowed, what the model already knows when it starts, and who does the work.

What it can reach for

The tools fall into a few groups, and the group matters more than the individual names.

Execution is the one to notice. Anything you can type in that terminal, it can run, which is where the usefulness comes from and why permissions get a lesson of their own.

Related

• Previous: Installation and setup
• Next: Codebase search
• Reference: Claude Code docs