Claude Code Agent Loops: A Practical Guide
Claude Code has several built-in ways to keep work moving beyond one prompt: hooks, /goal, /loop, subagents, agent teams, and dynamic workflows.
The names make this sound more complicated than it is. The practical questions are:
- What gives Claude another turn?
- What state carries into that turn?
- What proves the work is finished?
Once those are clear, choosing the right mechanism is straightforward.
Start with the basic agent loop
Claude Code's basic agent loop alternates between decisions inside the model and actions outside it. The model chooses text or a tool call. The harness checks permissions, runs the tool, and returns the result. That observation becomes input to the next model call.
The harness is what turns isolated model calls into agentic work. Its three main building blocks are tools, memory, and hooks:
- Tools act. They read files, run commands, query services, and change external state.
- Memory carries. It keeps useful state available across turns and sessions.
- Hooks steer. They intervene at known lifecycle boundaries.
Claude Code memory exists at three different lifetimes. Working context is what the model can use right now. The transcript records the session and allows it to be resumed. Durable stores such as CLAUDE.md, auto-memory, and project files can survive across sessions—but only help after their contents are loaded back into context.
This is why long-running work benefits from compact artifacts: a clear goal, a current plan, important decisions, reusable commands, open risks, and verified evidence. “Saved somewhere” is not the same as “available to the model.”
Hooks add deterministic behavior at session, turn, and tool boundaries. A session hook can restore critical context after compaction. A turn hook can use a prompt or agent to decide whether work should continue. Tool hooks can block edits to protected files or format code after an edit.
Use /goal when done can be proven
/goal is for work that should continue immediately until a completion condition is satisfied.
The important part is not writing a longer prompt. It is writing an effective condition with evidence. A Node 22 migration is not complete because the package file changed; it is complete when the repository, tests, CI, container, and deployed runtime all prove that Node 22 is in use.
Claude Code separates doing the work from deciding whether it is done. The main model takes an ordinary turn and surfaces evidence in the conversation. When the turn stops, a session-scoped Stop hook sends the goal and conversation to a fresh evaluator. A NO response and its reason start another turn; YES completes the goal. This goal-specific hook does not appear in the ordinary /hooks menu.
The evaluator has no tools, so evidence must make it into the transcript. An unobserved deployment state is an unproven criterion. The built-in goal lives in session state; if its contract and proof trail must persist with the project, write them to durable files or use an extension such as GoalBuddy.
Use /loop when the next check belongs in the future
/loop is for polling, reminders, and work that depends on time or outside state.
For example, a pull request monitor can wake on a fixed interval, report automated checks and review status, classify the PR as ready or blocked, and explicitly avoid changing code or merging. The interval defines when to look again. The prompt still defines what to inspect, what authority Claude has, and when the loop should stop.
/loop is scheduled re-entry, not continuous inference. Claude performs a normal model-and-tool turn, then goes idle. No model call is running while it waits. When the schedule becomes due, the prompt is enqueued again. A dynamic loop can also let Claude choose the next interval.
Use /goal when progress can continue now. Use /loop when the correct next action is to wait.
Fixed loops repeat until they are stopped or expire after seven days, and each one counts toward the session's scheduled-task capacity.
Use subagents for bounded, isolated work
Subagents are useful when a larger job contains independent assignments that deserve their own contexts.
A good delegation names the worker's ownership, constraints, expected proof, and stopping point. If three workers migrate separate packages, each should return changed files, test results, and open risks. The parent should not integrate until every package is proven ready.
A subagent is not extra memory inside the parent. It is a separate model loop with its own startup context, tools, and transcript. The parent sends the bounded assignment and essential context; the worker returns a final report. Files can become shared state, but only when the relevant agent reads them. A deliberate fork of the current conversation is the exception, and Claude Code's transcript viewer can inspect the resulting session history.
Agent teams change the communication topology. Subagents use centralized, hub-and-spoke delegation: workers report to the parent. In an agent team, independent teammates can share tasks and communicate directly with each other. Anthropic's parallel agents overview covers the broader set of coordination options.
Teams share coordination, not one context window. Clear ownership still matters, especially when workers share a working tree; worktree isolation is available when concurrent changes need separate filesystems.
Choose the controller that matches the work
The useful comparison is not which mechanism is “more agentic.” It is who controls the next turn, where shared state lives, and what ends the work. Anthropic's workflow comparison uses the same practical distinction.
The shortest selection guide is:
Start with one session. Add only the outer control the work needs. The documentation also compares goals with loops and agent teams with subagents directly.
Use dynamic workflows when the orchestration should be rerunnable
Dynamic workflows move orchestration into code. They fit jobs that need explicit fan-out, branching, intermediate state, independent verification, or a reusable execution graph.
With an ultracode request, Claude can generate a workflow that discovers work, fans it out to multiple auditors, independently verifies the results, and returns one synthesized report. Anthropic also provides example workflow prompts.
Claude can write the workflow script, which holds the sequence and intermediate state. A separate runtime executes the graph while subagents do the work. The main session receives the final result.
That is the common shape behind Claude Code's agentic features: a model takes a turn, tools connect it to the world, state is carried forward, and some outer mechanism decides what happens next. Reliable autonomy comes from choosing that mechanism deliberately—and defining the exit before the loop starts.
Primary sources
The presentation and this article follow Anthropic's documentation in this order: