The Agentic Loop: How Claude Code Thinks and Acts
Claude Code isn't a chatbot — it's an agent running a continuous gather → act → verify loop. This article explains exactly how that loop works, what drives tool selection, why Claude sometimes gets stuck, and how a single prompt becomes a multi-step execution plan.
Quick Reference
- →The loop has three phases: Gather context → Take action → Verify results
- →Each phase can repeat many times before the task is complete
- →Claude picks the next tool based on what information is still missing
- →The loop runs until the task is done or Claude needs user input
- →You can interrupt the loop at any point by pressing Escape
- →A 'stuck' agent is usually missing context — give it the missing piece
- →Plan Mode separates the gather phase from the act phase intentionally
- →Tool calls are serialized — Claude waits for each result before deciding the next step
In this article
What Is the Agentic Loop?
The agentic loop is the continuous cycle Claude Code runs to complete a task. It phases through gathering context, taking action, and verifying results — repeating as many times as needed until the work is done or it needs input from you.
When you send Claude Code a message, you are not sending a prompt to a chatbot. You are handing a task to an agent that can read your codebase, run commands, edit files, search the web, and check whether its own changes worked. The agentic loop is what enables this — a cycle of thinking and doing that keeps going until the task is complete.
Unlike a single LLM call that returns one response, the agentic loop is non-linear. Claude might read three files, attempt an edit, run the tests, discover a failure, read a fourth file, and then fix the root cause. The path from your prompt to the final result can involve dozens of tool calls, each one building on the last.
The Three Phases
The official model for the agentic loop is three phases. They are not strictly sequential — Claude blends them and revisits earlier phases as new information surfaces.
Gather Context
Claude reads files, searches for patterns, explores directory structure, fetches docs, and runs read-only commands. This phase builds the mental model needed to act correctly. It ends when Claude believes it has enough context to proceed — or realizes it needs to ask you something.
Take Action
Claude edits files, creates new ones, runs shell commands, executes tests, or calls external tools. Each action is one tool call. Claude waits for the result of each call before deciding the next step — actions are serialized, not parallelized.
Verify Results
After acting, Claude checks whether the action worked. This might mean running the test suite, type-checking, reading the edited file to confirm the change landed correctly, or inspecting command output. If verification reveals a problem, the loop returns to Gather to understand why.
These phases are a mental model, not a strict state machine. Claude can gather more context mid-action, or take a small action during the gather phase (like creating a scratch file). What matters is that the loop keeps going until convergence.
How Claude Decides Which Tool to Call Next
At each step of the loop, Claude has a set of available tools and must decide which one to call. This decision is driven by the gap between what Claude knows and what it needs to know — or between the current state of the code and the target state.
| What Claude needs | Tool it will likely reach for |
|---|---|
| Find files matching a pattern | Glob |
| Search for a symbol or string in code | Grep |
| Read a file's contents | Read |
| Make a targeted change to a file | Edit |
| Create a new file | Write |
| Run tests, linter, or build | Bash |
| Look up an error or API docs | WebSearch or WebFetch |
| Understand what changed recently | Bash (git log / git diff) |
Claude doesn't have a hardcoded decision tree. It reasons about the task, identifies what information is missing, and picks the tool that most efficiently closes that gap. This is why giving Claude a clear, specific task leads to more efficient tool selection — vague goals produce more exploratory (and expensive) gather phases.
"Add a loading spinner to the checkout button" triggers a focused gather phase (find CheckoutButton, check current state, find the spinner component). "Make the checkout better" triggers a wide exploratory gather phase that reads far more files. Specific prompts are not just clearer — they are cheaper.
Single Tool Calls vs Multi-Step Plans
The difference between a single tool call and a multi-step plan is scope. For a simple task — read this file, tell me what function X does — Claude may make exactly one tool call (Read) and respond. For a complex task, Claude builds an implicit plan: a sequence of tool calls it expects to need, in the order it expects to need them.
Claude does not explicitly write out this plan by default. It reasons about the next step at each iteration, informed by what has already been done. This is why the loop can adapt mid-task: if an unexpected file structure or test failure surfaces, Claude revises the implicit plan on the fly rather than getting stuck executing a stale sequence.
Why Claude Gets Stuck and How to Unstick It
An agent gets stuck when the gather phase cannot produce the context it needs to proceed confidently. This usually happens for one of four reasons:
- ▸The relevant code is in an external package or behind an API boundary Claude cannot read
- ▸The task requires a decision that depends on business logic or product context Claude doesn't have
- ▸The environment has a broken state (dependency not installed, wrong Node version, missing env var) that causes every verification to fail
- ▸The task is underspecified — Claude has multiple valid interpretations and doesn't want to guess wrong
Paste the missing context
If Claude is reading the wrong package or can't find the API shape, paste the relevant code or docs directly into the chat. This skips the failing gather phase entirely.
Clarify the goal
If Claude seems to be spinning on ambiguous requirements, restate the task with a concrete expected outcome: 'The endpoint should return 429 with a Retry-After header when rate limited.'
Fix the environment first
If tests are failing due to a broken environment (missing env vars, wrong runtime, corrupted node_modules), fix those issues before asking Claude to continue. A broken feedback loop blocks verification.
Use Plan Mode
If Claude keeps attempting and failing, switch to Plan Mode (`Shift+Tab` until you see 'plan'). Ask Claude to explain its approach before executing. The explanation often reveals the wrong assumption.
A team was using Claude Code to migrate their API from REST to tRPC. Claude kept generating incorrect router calls because it couldn't find the tRPC router definition — it was in a monorepo package that wasn't in the working directory. Every verify phase failed (TypeScript errors), so Claude kept trying different incorrect approaches. The fix was simple: paste the router's type signature into the chat. Claude immediately understood the API shape and completed the migration in one pass.
Learn this in → When Claude loops without progress, the missing context is usually one paste away.
Controlling and Interrupting the Loop
The agentic loop runs autonomously, but you are always in control. You can interrupt at any point, and the way you configure Claude Code's permission mode determines how often it pauses to ask for approval.
| Permission Mode | How It Affects the Loop |
|---|---|
| default | Claude pauses and asks before risky operations (file writes, shell commands) |
| acceptEdits | Claude auto-approves file edits but still asks before shell commands |
| plan | Claude only gathers context — it will not write or edit files at all |
| bypassPermissions | Claude runs fully autonomously (use only in controlled environments) |
Pressing Escape while the loop is running sends a stop signal. Claude will finish its current tool call and then pause, giving you a chance to redirect. It does not cancel mid-tool — a file edit in progress will complete before Claude stops.
Best Practices
Do
- ✓Give Claude specific, outcome-oriented tasks to reduce exploratory tool calls
- ✓Paste missing context (API types, external docs) directly into the chat when Claude seems to be searching for it
- ✓Fix broken test environments before asking Claude to continue — verification failures block the loop
- ✓Use Plan Mode (Shift+Tab) before complex tasks to align on the approach before execution starts
- ✓Interrupt with Escape if Claude starts going in the wrong direction — redirect early
Don’t
- ✗Don't give vague tasks like 'improve the code' — Claude will make many exploratory reads before acting
- ✗Don't let Claude loop on the same failing verification step without investigating why it keeps failing
- ✗Don't assume a stuck agent means Claude is incapable — it usually means there is missing context
- ✗Don't use bypassPermissions mode in a production repository or on shared machines
Key Takeaways
- ✓The agentic loop is three phases — gather, act, verify — repeating until the task is done
- ✓Tool selection is driven by the gap between what Claude knows and what it needs to know
- ✓Specific prompts produce fewer tool calls because they reduce the gather phase
- ✓When Claude is stuck, it almost always needs one specific piece of missing context
- ✓You can interrupt the loop at any time with Escape, and permission modes control how autonomous it runs
Video on this topic
The Claude Code Agentic Loop Explained
tiktok