The Agent Loop

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.