Claude Code Agent Architecture: Single-Threaded Master Loop for Autonomous Coding

anthropic · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.5 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Autonomous coding agents and developer tooling

Claude Code needed to perform autonomous code search, editing, testing, and response generation while staying debuggable, steerable, reviewable, and safe enough for production developer workflows.

Constraints:

Architecture

Claude Code uses a deliberately simple single-threaded master loop (nO) connected to a real-time steering queue (h2A), a ToolEngine/Scheduler, sandboxed developer tools, TodoWrite planning, at-most-one sub-agent branch, permission gates, diff-based editing, and context compression into project memory.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  user-interaction-layer["user interaction layer"] --> h2a-async-queue["h2A async queue"]
  h2a-async-queue --> no-master-loop["nO master loop"]
  no-master-loop --> flat-message-history["flat message history"]
  no-master-loop --> toolengine-scheduler["ToolEngine Scheduler"]
  no-master-loop --> todowrite-planner["TodoWrite planner"]
  no-master-loop --> sub-agent-branch["sub-agent branch"]
  toolengine-scheduler --> developer-tools["developer tools"]
  toolengine-scheduler --> permission-system["permission system"]
  permission-system --> developer-tools
  developer-tools --> diff-workflow["diff workflow"]
  diff-workflow --> user-interaction-layer
  flat-message-history --> compressor-wu2["Compressor wU2"]
  compressor-wu2 --> claude-md-project-memory["CLAUDE.md project memory"]
Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component Role Interacts with
user interaction layer CLI, VS Code plugin, or web UI where developers communicate with Claude Code. h2A async queue
h2A async queue Handles asynchronous events, pause/resume, and user interjections during work. user interaction layer, nO master loop
nO master loop Single-threaded agent loop that asks the model for tool calls, executes them, and repeats until a final answer. h2A async queue, flat message history, ToolEngine Scheduler, TodoWrite planner, sub-agent branch
flat message history Stores the conversation and tool results without complex threading. nO master loop, Compressor wU2
ToolEngine Scheduler Orchestrates tool invocations and queued model queries. nO master loop, developer tools, permission system
developer tools View, Grep, Edit, Bash, WebFetch, and BatchTool operations used to inspect and modify code. ToolEngine Scheduler, diff workflow
TodoWrite planner Maintains structured task lists with statuses and priorities for multi-step work. nO master loop, user interaction layer
sub-agent branch Controlled one-level parallel exploration for searches or alternative approaches. nO master loop
permission system Requires allow/deny decisions for writes, risky Bash commands, MCP, and web access. ToolEngine Scheduler, developer tools
diff workflow Shows reviewable diffs and supports small, reversible code changes. developer tools, user interaction layer
Compressor wU2 Summarizes conversations near context limits and writes important information to project memory. flat message history, CLAUDE.md project memory
CLAUDE.md project memory Markdown long-term memory file for project context. Compressor wU2

Data flow

User input enters through the CLI/editor/web UI, h2A queues live steering events, the nO master loop asks the model what to do, ToolEngine executes JSON tool calls in sandboxed tools, results return as plain text into the flat message history, TODO reminders keep the plan visible, Compressor wU2 summarizes near context limits into CLAUDE.md memory, and the loop terminates when the model returns a plain text answer.

3 supporting quotes
“user input arrives → the model analyzes and decides on actions → if tools are needed, they're called → results feed back to the model”article, stated
“The loop continues as long as the model's response includes tool usage; when Claude produces a plain text response without tool calls, the loop naturally terminates”article, stated
“JSON tool calls flow to sandboxed execution environments, which return results as plain text. This uniformity makes the system predictable and secure while giving Claude access to a developer's full toolkit. Reading and discovery tools form the foundation.”article, stated

Why this architecture

The architecture favors a constrained single-loop design over swarms because debuggability, transparent audit trails, real-time steering, and reviewable diffs matter more for coding work than unconstrained parallel autonomy.

3 supporting quotes
“a simple, single-threaded master loop combined with disciplined tools and planning delivers controllable autonomy.”article, stated
“This design maintains a single main thread with one flat list of messages—no swarms, no multiple agent personas competing for control.”article, stated
“with one flat list of messages—no swarms, no multiple agent personas competing for control. Anthropic explicitly chose this approach for debuggability and reliability. When complex problems arise that might benefit from parallelism, Claude Code allows at most one sub-agent branch at”article, stated

Models used: Claude Code model · Claude

Scale

Alternatives considered (roads not taken)

Complex multi-agent swarms

Rejected because: The architecture intentionally keeps one main thread and allows at most one sub-agent branch to avoid uncontrolled proliferation.

“power with predictability. The system's strength lies not in complex multi-agent swarms but in its simple, single-loop design that does one thing exceptionally well: help developers write better code faster. The power comes from its radical simplicity. While competitors chase multi-agent”article, stated
“Claude Code allows at most one sub-agent branch at a time, preventing the chaos of uncontrolled agent proliferation”article, stated

Batch-mode autonomous coding

Rejected because: h2A allows mid-task user interjections so users can redirect the agent without restarting the job.

“ability to incorporate user interjections mid-task without requiring a full restart. Imagine Claude Code working through a complex refactoring when you realize you need to add a constraint or redirect its approach. Instead of stopping everything and starting”article, stated
“this interactivity that transforms Claude Code from a batch processor into a genuine coding partner. ## Tools: the agent's hands Claude Code's tools follow a consistent interface pattern: JSON tool calls flow to sandboxed execution environments, which return”article, stated

Database-backed memory and semantic search everywhere

Rejected because: The source emphasizes simple Markdown memory and regex/search tools where simpler mechanisms suffice.

“threading), and always "do the simple thing first"—choosing regex over embeddings for search, Markdown files over databases for memory. (prompt source) ## The master agent loop (nO) At Claude Code's heart beats a classic”article, stated

Unmediated shell and write access

Rejected because: Claude Code uses permissions, risk classification, command sanitization, and confirmation prompts for dangerous operations.

“Write operations, risky Bash commands, and external tool usage (MCP/web) all require explicit allow/deny decisions.”article, stated
“The system classifies commands by risk level and appends safety notes to tool outputs, reminding both the model and user of potential dangers. This multi-layered approach catches both accidental mistakes and potential security issues. The diffs-first”article, stated

Patterns

tool-use-orchestration (agent-runtime)

The master loop repeatedly selects developer tools, executes them through the scheduler, and feeds results back until no more tool calls are needed.

“while(tool_call) → execute tool → feed results → repeat. The loop continues as long as the model's response includes tool usage;”article, stated
“ToolEngine & Scheduler orchestrates tool invocations and queues model queries”article, stated

context-compaction (memory)

Compressor wU2 summarizes conversations near context limits and stores important information in CLAUDE.md.

“summarize conversations and move important information to long-term storage.”article, stated
“This storage is in a simple Markdown document that serves as the project's long-term memory.”article, stated

agent-memory (memory)

Claude Code uses CLAUDE.md as persistent project memory alongside the compressed message history.

“For memory and context management, Claude Code uses the CLAUDE.md file as project memory, supplemented by the Compressor wU2 that summarizes conversations when approaching context limits.”article, stated
“All tool calls and messages are logged, creating a complete audit trail of the agent's actions and decisions.”article, stated

multi-agent-orchestration (controlled-parallelism)

Sub-agents can explore wide searches or alternate approaches, but they feed results back to the main loop and cannot recursively spawn more agents.

“These sub-agents operate with depth limitations—they cannot spawn their own sub-agents, preventing recursive explosion.”article, stated
“Results from sub-agents feed back into the main loop as regular tool outputs”article, stated

human-in-the-loop-gate (safety)

Permission prompts and diff review keep developers in control of writes, risky shell commands, external tools, and generated code changes.

“Write operations, risky Bash commands, and external tool usage (MCP/web) all require explicit allow/deny decisions. Users can configure whitelists or always-allow rules for trusted operations, balancing security with workflow efficiency.”article, stated
“Colorized diffs make changes immediately apparent, encouraging minimal modifications and easy review/revert cycles.”article, stated

Tradeoffs

Use a single-threaded master loop.

Chose One flat main loop with simple tool-call repetition over A multi-agent swarm architecture.

Rationale: The article argues the single loop is easier to debug, audit, and steer while still delivering practical autonomy.

“The power comes from its radical simplicity. While competitors chase multi-agent swarms and complex orchestration, Anthropic built a single-threaded loop that does one thing obsessively well—think, act, observe, repeat.”article, stated
“Anthropic built a single-threaded loop that does one thing obsessively well—think, act, observe, repeat.”article, stated

Allow controlled sub-agents only for bounded exploration.

Chose At most one depth-limited sub-agent branch over Recursive or unconstrained parallel agents.

Rationale: The system still supports wide searches and alternative approaches but prevents recursive agent explosion.

“Common use cases include wide searches across the codebase or trying multiple solution approaches in parallel.”article, stated
“Results from sub-agents feed back into the main loop as regular tool outputs, maintaining the single-thread simplicity of the overall system. ## Safety, memory, and transparency Claude Code implements multiple layers of protection through its [permission system](https:”article, stated

Use diff-first editing.

Chose Surgical patches, minimal diffs, and reviewable changes over Opaque file rewrites or unreviewed code generation.

Rationale: Diffs make AI-generated changes transparent and easier to review, revert, and test.

“The CLI displays minimal diffs to keep output readable, but every change is tracked and reviewable.”article, stated
“This approach naturally promotes test-driven development—Claude can run tests, see failures, and iterate on fixes”article, stated

Gotchas (what bit them)

Multi-agent proliferation can reduce reliability and debuggability.

Root cause: Multiple personas and uncontrolled recursive branches make it harder to understand who is controlling the task.

Resolution: Use one main loop and at most one sub-agent branch with depth limitations.

“This design maintains a single main thread with one flat list of messages—no swarms, no multiple agent personas competing for control. Anthropic explicitly chose this approach for debuggability and reliability.”article, stated
“When complex problems arise that might benefit from parallelism, Claude Code allows at most one sub-agent branch at a time, preventing the chaos of uncontrolled agent proliferation while still enabling sophisticated problem decomposition.”article, stated

Long coding sessions can lose task state.

Root cause: The agent's context window fills and the model can forget objectives in long conversations.

Resolution: Use TODO reminders, flat message history, compression, and CLAUDE.md project memory.

“system messages inject the current TODO list state, preventing the model from losing track of its objectives in long conversations.”article, stated
“Compressor wU2 that summarizes conversations when approaching context limits.”article, stated

Developer tools can create security or damage risks.

Root cause: Bash, write operations, MCP/web calls, and command injection vectors can affect real projects and environments.

Resolution: Classify command risk, sanitize dangerous constructs, require permissions, and show diffs.

“complete with risk level classification and confirmation prompts for dangerous commands.”article, stated
“actively filters for injection attempts (blocking backticks and $() constructs)”article, stated

Evaluation

The case evaluates Claude Code qualitatively through architecture transparency, tool auditability, safety controls, and adoption signal from heavy usage that led to weekly limits.

Metrics: weekly usage limits after 24/7 use · tool-call audit trail · permission decisions · risk-classified Bash commands · diff reviewability · context-window usage threshold around 92%

3 supporting quotes
“reported that Anthropic had to add weekly limits after users ran Claude Code 24/7”article, stated
“All tool calls and messages are logged, creating a complete audit trail of the agent's actions and decisions.”article, stated
“complete with risk level classification and confirmation prompts for dangerous commands.”article, stated

Outcomes

Reported scale details include users running Claude Code 24/7, weekly usage limits, a 92% context-compression trigger, and file reads defaulting to about 2000 lines.

3 supporting quotes
“requiring Anthropic to implement weekly usage limits after users began running Claude Code continuously”summary, stated
“creates a controllable, transparent coding agent that balances power with predictability.”article, stated
“help developers write better code faster. The power comes from its radical simplicity. While competitors chase multi-agent swarms and complex orchestration, Anthropic built a single-threaded loop that does one thing obsessively well—think, act, observe, repeat.”article, stated