AIGuide
The real mechanics

Loop engineering in Claude Code

Now the concrete version. Here's the exact loop Claude Code runs, how subagents are defined and called, and how the whole thing lives inside the VS Code editor.

The agentic loop, in detail

Five phases, spinning until the task is done

The simple "act → observe → decide" you saw in the basics expands into five real phases inside Claude Code. It isn't following a script — every turn, it decides the next move from what it just observed.

🧭 1 · Gather context files · memory · git 🧠 2 · Reason / plan pick the next step 🛠️ 3 · Act (tools) Read · Edit · Bash… 👀 4 · Observe read tool results 🔀 5 · Decide loop · delegate · stop more work to do → next turn ✓ task complete → stop

Each tool result feeds the next decision — that feedback is what makes it "agentic" rather than scripted.

🧭 1 — Gather context

Reads project files (via Glob, Grep, Read), loads CLAUDE.md and saved memory, checks git status and the working directory, and loads any MCP tool definitions.

🧠 2 — Reason / plan

Uses that context to model the task, break it into steps, and choose which tool to call next. With extended thinking on, it reasons harder before acting.

🛠️ 3 — Act with tools

Invokes tools — and can fire several in parallel in a single turn (e.g. read three files at once). Every call is tracked by a tool_use_id.

👀 4 — Observe results

Tool outputs return in the message stream. Claude reads them and updates its understanding of the task.

🔀 5 — Decide

Continue the loop, delegate to a subagent, or stop because the goal is met. You can press Esc to interrupt at any point.

🔁 …and repeat

The cycle spins until the stopping condition is satisfied. That whole design — goal, steps, verification, stop signal — is loop engineering.

Subagents

Delegating a job to a helper with its own loop

A subagent is a specialised assistant that runs in its own isolated context window, with its own system prompt, its own tool access, and its own permissions. It works independently and returns only the relevant result to the main conversation.

1 · Define it — a Markdown file

Drop a file in .claude/agents/ (per-project) or ~/.claude/agents/ (all your projects). It's YAML frontmatter + a system prompt.

--- name: code-reviewer description: Reviews a diff for bugs. Use proactively after edits. tools: Glob, Grep, Read # read-only model: sonnet --- # this body is the subagent's system prompt You are a meticulous reviewer. Inspect the changes, list concrete bugs with file:line, and rank them by severity. Be terse.

Frontmatter fields: name and description are required; tools, model, disallowedTools, permissionMode, maxTurns and more are optional.

2 · Invoke it — three ways

Let Claude choose

Just describe the work. Claude reads each agent's description and delegates automatically when it fits — the "use proactively" hint encourages this.

@-mention it

Type @agent-code-reviewer to guarantee that specific subagent runs.

Session-wide flag

Launch with claude --agent code-reviewer to use it for the whole session.

🎁

What comes back

The subagent's entire working history — every file it read, every log — stays in its context. The main agent receives only the final summary, plus an id it can use to resume that subagent later.

Main agent running its loop… 🔁 "go review this" 🔒 subagent's own isolated context window reads 40 files runs its own loop verbose logs stay in here ✅ concludes writes a short summary only the summary returns → main context stays lean

Context isolation in one picture: the messy work happens inside the subagent; the manager gets a clean answer.

Batteries included

Built-in subagents you already have

Claude Code ships with ready-made subagents. You can use them without writing a single config file.

🔍

Explore

Read-only file discovery and codebase search. Fast — runs on a lighter model.

🗺️

Plan

Gathers context, then proposes an implementation strategy before any edits.

🧰

General-purpose

Tackles complex tasks needing both exploration and code changes.

⌨️

Bash

Runs terminal commands in an isolated context so output doesn't flood the main chat.

Where it lives

Inside the VS Code editor

The Claude Code extension puts the whole loop into a graphical panel next to your code. Install it from the marketplace and the extension bundles its own CLI, then connects to the editor through a local ide MCP server.

  • Side-by-side diffs. Every edit shows as a reviewable diff — accept, reject, or tweak before it lands.
  • Editable plans. Plan-mode output opens as a document you can comment on before the loop starts working.
  • @-mentions. Reference exact files or line ranges like @auth.ts#5-10 to steer context.
  • Permission modes. Switch between Manual, Plan, Edit-automatically and Auto — controlling how much the loop can do unattended.
  • Parallel sessions & history. Run multiple conversations in tabs; browse and resume past sessions.
auth.ts — VS Code
7  function verify(t) {
8   return t.exp < now;
8   return t.exp > now;
9  }
◂ side-by-side diff
🔁 Claude Code

Found the bug in verify() — the comparison was flipped.

🧪 Delegated to test-runner subagent…

✓ 34 passing. Ready to accept?

Accept Reject

Illustration of the extension: the loop runs on the right, its edits appear as diffs on the left.

Ready to go deeper?

The patterns that make loops reliable

You've seen the machinery. The advanced page covers context-window management, parallel fan-out, and the verification & adversarial patterns that turn a loop from clever into trustworthy.

Next lesson: Advanced
⌂ Back to all lessons