Inside Claude's Agent System

Claude Code isn't a single agent -- it's a team. A main agent orchestrates the conversation and spawns specialized subagents for research, exploration, and planning. Each subagent runs in its own context window, so deep codebase exploration doesn't eat up the main agent's context.

This post breaks down the architecture: how the main agent decides what to delegate, how subagents run in parallel, and how context isolation keeps everything efficient.

1. High-Level Architecture

At the core of Claude Code's architecture sits the Main Agent - powered by Claude Opus or Sonnet. This agent acts as the central orchestrator, managing the conversation with the user, deciding which tools to invoke, and determining when to delegate work to specialized subagents.

The architecture follows a clear layered design:

• User Interface Layer: The CLI where developers interact with Claude Code through natural language prompts.
• Orchestration Layer: The main agent that analyzes tasks, manages context, and coordinates all tool usage and subagent dispatching.
• Subagent Pool: Specialized agents that can be spawned on-demand for specific types of work - exploration, planning, general-purpose research, and documentation lookups.
• Tool Layer: The actual capabilities - file reading, editing, writing, shell execution, searching, and web access.

2. The Main Agent Execution Loop

Every interaction with Claude Code follows a structured execution loop. When you submit a prompt, the main agent evaluates the task complexity and decides the optimal execution strategy.

Key behaviors in this loop:

• Simple tasks (reading a file, making a small edit) are handled directly by the main agent using tools like Read, Edit, or Bash.
• Complex multi-step tasks are decomposed into subtasks. The agent may use TodoWrite to track progress and execute each step sequentially or in parallel.
• Multiple independent tool calls can be made in parallel within a single turn, maximizing throughput. For example, reading three files simultaneously instead of one at a time.

3. Subagent Architecture: The Task Tool

The Task tool is the mechanism by which the main agent spawns subagents. Each subagent runs as an independent process with its own context window, preventing the main agent's context from being bloated with intermediate results from deep research or exploration.

Subagent Types:

• General Purpose Agent: Full access to all tools (Read, Edit, Write, Bash, Grep, Glob, WebSearch, etc.). Used for complex multi-step tasks that require autonomy.
• Explore Agent: Optimized for fast codebase exploration. Has access to search and read tools but cannot edit or write files. Supports thoroughness levels: quick, medium, and very thorough.
• Plan Agent: A software architect agent for designing implementation plans. Can read and search but cannot modify files. Returns step-by-step plans with architectural trade-offs.
• Code Guide Agent: Specialized for answering questions about Claude Code features, the Agent SDK, and the Claude API. Has web access for documentation lookups.

Critical aspects of the subagent lifecycle:

1. Spawning: The main agent calls the Task tool with a subagent type, a detailed prompt, and a short description. The subagent initializes with its own fresh context.
2. Execution: The subagent works autonomously, using its permitted tools to research, read files, search code, and synthesize findings.
3. Return: Once complete, the subagent returns a single consolidated message to the main agent, along with an agent ID.
4. Resumption: The main agent can later resume a subagent using its agent ID, and the subagent continues with its full prior context preserved.

4. Parallel Subagent Execution

One of the most powerful aspects of the agent team architecture is the ability to run multiple subagents concurrently. When the main agent identifies independent subtasks, it can spawn multiple subagents in a single turn, dramatically reducing total execution time.

Parallel execution is used when:

• Multiple independent research queries need to be performed
• Different parts of a codebase need to be explored simultaneously
• Planning and research can happen at the same time
• Background agents can work while the main agent continues responding to the user

Key Insight: Subagents that run in the background notify the main agent upon completion. The main agent does not poll or sleep-wait - it continues with other work and processes results when they arrive.

5. Subagent Decision Flow

The main agent doesn't always spawn subagents. It follows a decision tree to determine the most efficient approach for each task. Simple operations are handled directly, while complex or exploration-heavy tasks are delegated.

The decision heuristics include:

• Direct Grep/Glob for targeted searches (e.g., finding a specific class or function name).
• Explore Agent when a search requires multiple rounds across different naming conventions or locations.
• Plan Agent when the user requests implementation planning for a feature or refactoring.
• General Purpose Agent for research tasks that need autonomy and would bloat the main context window.
• Direct handling for simple file edits, single tool calls, or when the main agent already has all needed context.

6. End-to-End Workflow Example

Let's trace through a real-world example: a user asks Claude Code to "Add authentication to the app." This demonstrates how all the pieces work together across four phases.

The four phases illustrate the full agent team in action:

1. Research Phase: Multiple subagents explore the codebase and research best practices in parallel, delivering compressed findings back to the main agent.
2. Planning Phase: A Plan Agent designs the implementation strategy based on the research findings and existing architecture.
3. Implementation Phase: The main agent executes the plan step by step, using TodoWrite to track progress, and tools like Edit and Write to modify files.
4. Verification Phase: Tests and linters are run via Bash to ensure the changes work correctly.

7. Context Window Management

A fundamental challenge in agentic AI is managing the context window. Claude Code employs several strategies to maintain high-quality responses even in long sessions.

• Automatic Compression: As conversations approach context limits, older messages are automatically compressed, keeping the most relevant information available.
• Subagent Isolation: Each subagent runs in its own context window. Only the final synthesized result is returned to the main agent, preventing intermediate search results and file contents from consuming main context space.
• Selective Tool Use: The main agent prefers dedicated tools (Read, Edit, Grep) over generic Bash commands, as dedicated tools produce more structured, concise outputs.

8. Advanced Features

Worktree Isolation

Subagents can be spawned with isolation: "worktree", creating a temporary git worktree. This gives the subagent an isolated copy of the repository to work on, preventing conflicts with the main agent's changes. If the subagent makes changes, the worktree path and branch are returned; otherwise, it's automatically cleaned up.

Background Execution

Subagents can run in the background using the run_in_background parameter. The main agent is automatically notified when a background subagent completes - there's no polling or sleeping. This enables the main agent to continue interacting with the user or performing other tasks while research runs in parallel.

Agent Resumption

Every subagent returns an agentId upon completion. The main agent can resume any subagent later using this ID, and the subagent continues with its full prior context preserved. This is useful for follow-up questions or iterative refinement without re-doing prior work.

Permission Model

Tools are executed under a user-configured permission mode. When a subagent or main agent attempts a tool call that isn't automatically allowed, the user is prompted for approval. This ensures human oversight over file modifications, shell commands, and other potentially impactful operations.

9. Why This Architecture Matters

• Scalability: Complex tasks that would overwhelm a single agent's context window are distributed across multiple specialized subagents.
• Speed: Parallel subagent execution dramatically reduces the time needed for research-heavy tasks.
• Quality: Each subagent operates with a fresh, focused context window, producing higher-quality results than cramming everything into one conversation.
• Separation of Concerns: Read-only agents (Explore, Plan) cannot accidentally modify files, while the main agent retains full write access when needed.
• Human in the Loop: The permission model ensures that developers maintain control over what the agent team can do, especially for destructive or irreversible operations.

Conclusion

The architecture boils down to intelligent delegation. The main agent handles simple tasks directly, spawns subagents for research-heavy work, and runs multiple agents in parallel when subtasks are independent. Each subagent gets its own context window, so deep exploration doesn't crowd out the main conversation.

The result: Claude Code can tackle multi-file, multi-step engineering tasks without its context window becoming a bottleneck.