Inside Claude Code's architecture: how the agent loop works

The first time you watch Claude Code edit a file, run your tests, read the failure, and patch the code without you saying a word, it feels like magic. It isn't. Underneath is a remarkably small set of primitives wired together in a tight loop, and once you understand how those primitives connect, you stop treating the agent as a black box and start engineering it. This post traces the architecture end to end — from the moment your prompt arrives to the moment a subagent returns its result — so you can reason about what the system will do before you run it.

The agent loop is the engine, everything else is fuel

At its core, Claude Code is an agent loop: a cycle that takes the current conversation state, asks the model what to do next, executes any tool calls the model requests, appends the results, and repeats until the model decides it is finished. Anthropic's Claude models are trained to emit structured tool-use blocks, so the loop is genuinely model-driven — the orchestration code does not decide which file to read or which command to run. It only faithfully executes the calls the model emits and feeds the outputs back.

That distinction matters enormously for how you think about the system. The loop is deterministic plumbing; the intelligence lives in the model and in the context you assemble for it. A turn looks like this: assemble messages, send to Opus 4.8 or Sonnet 4.6, receive a response that may contain text plus one or more tool-use blocks, run those tools, wrap each result as a tool-result block, and loop. The model keeps control of the whole trajectory because every tool result re-enters its context on the next iteration, letting it adapt to what actually happened rather than a plan it committed to up front.

Because the loop is provider-native, error handling is graceful by design. If a shell command exits non-zero, that exit code and stderr come back as a tool result, and the model reads them like a human would — then tries something else. You are not writing brittle retry trees; you are letting a capable model close the loop on its own outputs.

Context assembly: the 1M-token window is a budget, not a bucket

Claude Code runs on a context window of up to one million tokens in 2026, but the window is a budget you spend, not a bucket you fill. On every turn the harness assembles a layered context: the system prompt and tool definitions, the project's instruction files, the running message history, file contents the model has read, and tool results. The art of building a good agent is deciding what earns a place in that budget and what gets summarized, truncated, or fetched on demand.

flowchart TD
  A["User prompt arrives"] --> B["Harness assembles context: system + tools + project files + history"]
  B --> C["Send to Claude model"]
  C --> D{"Response has tool calls?"}
  D -->|No| E["Emit final answer to user"]
  D -->|Yes| F["Execute tools: shell, edit, MCP, subagent"]
  F --> G["Wrap outputs as tool-result blocks"]
  G --> B

Notice the loop in the diagram closes back on context assembly, not on the model call. That is the single most important architectural fact about Claude Code: every iteration rebuilds context, which is why techniques like compaction and selective file reads have such leverage. When history grows large, the harness can compact older turns into a summary, freeing budget for fresh tool results. The model never sees raw, unbounded history; it sees a curated working set.

Subagents: parallel context windows with isolated state

A subagent in Claude Code is a fresh agent loop with its own context window, spawned by the main agent to handle a scoped task. This is the system's answer to context pollution. Instead of dumping the contents of forty files into the primary conversation, the orchestrator dispatches a subagent with a tight brief — "find every call site of this function and report the file paths" — and the subagent burns its own context exploring, then returns a compact result that costs the parent only a few hundred tokens.

Subagents run in parallel, which is where the real speedups come from. When you ask Claude Code to investigate a bug across the frontend, the API layer, and the database schema simultaneously, it can fan out three subagents that each explore independently and report back. The trade-off is tokens: multi-agent runs typically consume several times more tokens than a single agent doing the same work serially, because each subagent re-pays for its own context. You spend tokens to buy parallelism and isolation, so you deploy subagents deliberately, not reflexively.

MCP and skills: how external capability plugs into the loop

The agent loop only knows how to call tools, so everything Claude Code can touch in the outside world is exposed as a tool. The Model Context Protocol (MCP) is the open standard, introduced by Anthropic in November 2024, that lets external servers advertise tools, resources, and prompts to the agent over a uniform interface. When you connect an MCP server — a database, a ticketing system, an internal API — its tools appear in the model's tool list, and from the loop's perspective they are indistinguishable from the built-in file and shell tools.

Skills complement MCP from the other direction. An Agent Skill is a folder of instructions, scripts, and resources that Claude loads dynamically when a task makes it relevant. MCP gives the agent the ability to call a system; a skill teaches the agent how and when to use it well — the conventions, the gotchas, the right sequence of calls. In architectural terms, MCP extends the tool surface and skills extend the knowledge that governs that surface, and both are pulled into context only when needed so they do not permanently tax the budget.

Hooks and the deterministic edges of a probabilistic system

Not everything should be left to the model's judgment. Hooks are deterministic callbacks the harness fires at fixed points in the loop — before a tool runs, after a file is edited, when the session ends. They are how you bolt non-negotiable rules onto a probabilistic core: run the formatter after every edit, block any shell command that touches production, log every tool call for audit. Because hooks execute outside the model's control, they give you guarantees the model cannot, by construction, violate.

This pairing — a model-driven loop ringed by deterministic hooks — is the architectural signature of a production-grade agent. The model supplies adaptability; the hooks supply the rails. Teams that ship reliable agents almost always end up here: they let the model reason freely inside a fence built from hooks, permissions, and tightly scoped tools.

How the pieces fit, in one sentence

End to end: a prompt triggers context assembly, the model emits tool calls, the harness executes them through built-in tools or MCP servers (guided by any loaded skills and constrained by hooks), results flow back into a freshly assembled context, and the loop repeats — optionally fanning out subagents with isolated windows — until the model declares the task done. Every advanced behavior you see is an emergent property of that small set of parts.

Frequently asked questions

Does Claude Code plan the whole task before acting?

No. It is fundamentally reactive at the architectural level — it decides the next tool call based on the current context, executes it, observes the real result, and decides again. It can choose to write out a plan as text, but the loop never locks itself into that plan; each iteration is a fresh decision informed by what actually happened.

What stops the agent loop from running forever?

The loop ends when the model returns a response with no tool calls, which it does when it judges the task complete. Harness-level guardrails — iteration limits, token budgets, and hooks — provide additional stopping points so a confused trajectory cannot spin indefinitely.

When should I use subagents instead of one agent?

Use subagents when subtasks are independent and you want isolation or parallelism: searching multiple areas of a codebase at once, or keeping a noisy exploration out of the main context. Because each subagent re-pays for its own context, prefer a single agent for tightly coupled, sequential work.

How do MCP and skills differ architecturally?

MCP expands what the agent can do by adding tools to its callable surface; skills expand what the agent knows by adding instructions loaded on demand. They compose: an MCP server provides the database tools, and a skill explains the safe query patterns for that database.

Bringing agentic AI to your phone lines

The same loop-and-tools architecture that powers Claude Code is what CallSphere runs on the phone — voice and chat agents that assemble context per call, invoke tools mid-conversation, and hand off to specialized subagents to book work around the clock. See the architecture in action at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.