Claude Code: Behind-the-Scenes of the Master Agent Loop
A detailed reverse-engineering of Claude Code's agent architecture, revealing how a single-threaded master loop with flat message history, structured tool interfaces, async steering, and TODO-based planning delivers controllable autonomy without multi-agent complexity.
Overview
This article dissects the internal architecture of Claude Code, Anthropic’s AI coding agent that became so popular the company had to impose weekly usage limits. Rather than building a complex multi-agent swarm, Anthropic chose radical simplicity: a single-threaded master loop that thinks, acts, observes, and repeats. The article walks through every layer of the system — from the core loop to tool design, planning mechanisms, and safety guardrails — offering a blueprint for how production-grade agents can be built with minimal architectural complexity.
The Master Agent Loop
At the heart of Claude Code is a deceptively simple pattern: while(tool_call) → execute tool → feed results → repeat. The loop terminates when Claude produces plain text without requesting a tool call. Key design choices include:
- A single main thread with one flat message list — no complex threading or competing agent personas
- At most one sub-agent branch at a time, preventing uncontrolled agent proliferation while still enabling problem decomposition
- A transparent audit trail where each step (grep, read, edit, test) is visible to the user
A typical execution chain: receive request → Grep for code search → View to read files → Edit for modifications → Bash for testing → formulate answer.
Async Steering with h2A
The h2A async dual-buffer queue enables real-time human-in-the-loop control without restarting the agent. Users can pause, resume, or inject new instructions mid-task. This allows Claude to seamlessly adjust its plan on the fly, turning what could be a batch process into a genuinely interactive streaming conversation.
Tool Design Philosophy
Tools follow a consistent interface — JSON tool calls in, sandboxed execution, plain text results out. The article highlights a key design decision: Anthropic chose regex-based search (GrepTool) over vector databases, reasoning that Claude can craft sophisticated regex patterns without the overhead of embeddings. Tools are categorized into reading/discovery (View, Glob, Grep), code editing (Edit, Write), execution (Bash with risk classification), and specialized operations (WebFetch, NotebookEdit, BatchTool).
Planning and Sub-Agents
Multi-step tasks begin with TodoWrite, creating structured JSON task lists with IDs, status tracking, and priority levels. System reminders inject the current TODO state after each tool use, preventing the model from losing track during long conversations. Sub-agents enable exploration and parallel solution attempts but are depth-limited — they cannot spawn their own sub-agents, maintaining a controlled hierarchy.
Safety and Memory
The permission system requires explicit user approval for write operations and risky commands. A context compressor triggers at ~92% window usage, summarizing conversations into Markdown-based project memory (CLAUDE.md). The diffs-first workflow promotes minimal changes with easy review and revert cycles.
Key Takeaway
The strongest agent architecture isn’t necessarily the most complex one. Claude Code proves that a single-threaded loop doing one thing obsessively well — think, act, observe, repeat — combined with disciplined tool design and transparent planning, can outperform elaborate multi-agent systems while remaining controllable and predictable.