The Agent Loop
How Claude thinks
The agent loop is the core mechanism behind Claude Code. Unlike an ordinary chat, where the model answers a message once, an agent repeats a reason–act–observe cycle until the task is solved. On every iteration Claude analyzes the current state, selects a single tool — for example Read, Edit, Bash, or Grep — executes it, then evaluates the result and decides what step comes next. That is why Claude can read a file, locate a bug, apply a fix, and run tests on its own without asking you at every intermediate step. Crucially, exactly one action happens per pass of the loop: the model does not invent a full plan to the end up front, but builds it step by step based on what the previous tool actually returned. This feedback loop makes the agent robust to surprises — if a file is not what it expected, the next step adapts to the fact rather than to an assumption.
A key detail is that each action and its result are appended to the context window, the shared memory of the current session. It holds the system prompt, the conversation history, and data returned by tools. When the window is nearly full, Claude Code automatically compacts the older history into a short summary so it can keep going. You can also trigger this manually with /compact — useful before a long task to free space while keeping what matters. Understanding this explains why an agent sometimes “forgets” details from the start of a very long session: they were compacted away. For the same reason it pays to keep sessions topically focused and to start a fresh one when the task changes — that keeps the context free of clutter, so the agent works more accurately and more cheaply on tokens.
The loop is not infinite. Claude stops when the task is complete, when it needs your input or confirmation, when a step or context limit is reached, or when a critical error occurs. When to use this knowledge: phrase the task so the agent has a checkable completion signal (for example “tests pass”), and the loop will run itself to the end. Common pitfalls: a vague goal makes the agent spin through extra iterations; huge files fill the context fast; and missing a “done” criterion leads to an early stop asking for clarification. Concrete example: given “fix the bug in auth.ts”, the agent reads the file (Read), finds a missing null check, applies the fix (Edit), reruns the tests (Bash), and only ends the loop once the tests pass.
Analyze
Claude analyzes the request and current context
Understanding the goal, identifying required information, assessing current state
Analyze
Claude analyzes the request and current context
Understanding the goal, identifying required information, assessing current state
Select Tool
Selects the appropriate tool for the next step
Read, Edit, Bash, Grep, Task or another from 18+ tools
Execute
Executes action with the selected tool
Reading file, editing code, running command, etc.
Evaluate
Evaluates the result and decides what to do next
Task complete? More actions needed? Error occurred?
Each action adds information to the context. When context fills up, Claude automatically compresses it:
💡 Use /compact for manual context compression while preserving important information
Task completed
Claude determines the goal is achieved
User input needed
Confirmation or additional information required
Limit reached
Step count or context size exceeded
Error
Critical error requiring intervention
Key Understanding
Claude Code is not just a text generator. It's an agent that autonomously works in a loop until the task is complete. It can make dozens of iterations, reading files, fixing code, running tests — all without your involvement at each step.
Frequently asked questions
What is the agent loop in Claude Code?
The agent loop is the repeating analyze → select tool → execute → evaluate cycle that drives Claude Code. Unlike a normal chat, the agent decides each next step from the previous step's result and keeps iterating until the task is done or a stop condition fires.
When does Claude Code stop the loop?
It stops in four cases: the task is complete, it needs your input or confirmation, a step or context-size limit is reached, or a critical error occurs. Give the task a checkable completion signal (like "tests pass") so the loop can finish on its own.
What is the context window and why use /compact?
The context window is the session's working memory: system prompt, conversation history, and tool results. Each action is appended to it, and when it nears full, Claude Code auto-compacts older history into a summary. The /compact command triggers that manually, freeing space before a long task while keeping what matters.
Why does Claude Code forget details from a long session?
Because once the context window fills, older history is automatically compacted into a short summary and individual early details drop out. Keep sessions topically focused and start a fresh one when the task changes to avoid clutter.
This lesson is part of a structured LLM course.
My Learning Path