Claude Code Subagents | Triple Your Coding Speed with Parallel Execution

What Are Subagents?

A subagent is a dedicated Claude instance that is completely separate from the main session's Claude. It has its own context window, system prompt, toolset, and permission mode. It receives a task, processes it, and returns only the result to the main session.

The official blog describes subagents as being "like tabs in a browser." Even if a subagent reads dozens of files during a side investigation, that noise never enters the main context — only the result comes back.

Note that this is a different concept from Agent Teams, where multiple sessions communicate with each other (subagents operate within a single session).

Why Use Subagents?

One cause of accuracy degradation in Claude Code on large tasks is context pollution. The logs from 50 files read while investigating an authentication module linger as inference overhead throughout the subsequent implementation phase. Subagents structurally solve this problem.

The main benefits of subagents cited in the official documentation are as follows:

• Context protection — Isolate exploration and research from the main conversation
• Constraint enforcement — Set role-appropriate permissions, such as restricting available tools to read-only
• Configuration reuse — Call the same custom subagent across multiple projects
• Cost optimization — Route simple research tasks to lightweight models like Haiku

How to Use the Three Built-In Subagents

Claude Code comes with built-in subagents that require no configuration to use.

Explore (Exploration Only)

• Model: Haiku (prioritizes low latency)
• Tools: Read-only (Write and Edit are disabled)
• Use case: File exploration, code search, understanding the entire codebase

When Claude needs to understand code without making changes, it automatically delegates to Explore. Search result logs do not accumulate in the main context.

Plan (Planning Assistance)

• Model: Inherits from the main session
• Tools: Read-only
• Use case: Codebase research during Plan mode

When Claude performs research before planning in /plan mode, this agent is used to collect context while preventing infinite nesting (subagents spawning further subagents).

General-purpose

• Model: Inherits from the main session
• Tools: All tools
• Use case: Complex tasks mixing exploration and implementation, multi-step operations

How to Create Custom Subagents: Using the /agents Command

The easiest way to create a custom subagent is with the /agents command.

1. Run /agents in Claude Code

2. Go to the Library tab → "Create new agent" → select "Personal" (saved to ~/.claude/agents/)

3. Enter a prompt in "Generate with Claude"

   A subagent that reviews code and suggests improvements.
   Review along three axes — readability, performance, and best practices —
   and present the current code alongside the improved version.
   

4. Tool selection — For read-only reviews, restrict to Read-type tools only

5. Model selection — For code pattern analysis, Sonnet offers a good balance of speed and cost

6. Memory settings — Selecting "User scope" allows the subagent to accumulate learning results in ~/.claude/agent-memory/

The subagent is available for use immediately after configuration.

Use the code-improver agent to suggest improvements in this project

How to Create Custom Subagents: Manual File Creation

You can define a subagent using a Markdown file with YAML frontmatter.

---
name: security-scanner
description: Detects security vulnerabilities. Focuses on SQL injection, XSS, and authentication bypass. Called automatically after code review.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---
You are a security-specialized code reviewer.
Based on the OWASP Top 10, identify vulnerabilities and report each one with its risk level, reproduction steps, and a suggested fix.

Place this file at .claude/agents/security-scanner.md to make it available across the entire project.

The main frontmatter fields are as follows:

Subagent Placement Locations and Scope

You can place files in the following locations, listed in order of priority (highest first):

Project subagents (.claude/agents/) can be shared across the entire team by committing them to Git. The best practice is to cultivate subagents tailored to your team's development workflow over time.

Practical Patterns for Accelerating Development with Parallel Execution

The true power of subagents lies in parallel execution. Here are the representative patterns introduced in the official blog.

Note that the "3x" figure mentioned in the title and summary is a rough estimate based on the premise that running three independent tasks simultaneously can theoretically yield up to approximately 3x the throughput compared to sequential execution. The actual time savings will vary depending on task granularity and dependencies, but many developers have noticed a significant reduction in wait time during investigation phases that span multiple files.

Pattern 1: Parallelize Pre-Implementation Research

Please use subagents to simultaneously investigate the authentication module,
database schema, and frontend components.

Three independent investigations run in parallel, and only organized summaries are returned to the main context.

Pattern 2: Bulk Fixes Across the Codebase

When applying the same refactoring to multiple modules simultaneously, assigning each to an independent subagent can dramatically reduce time compared to sequential execution.

Pattern 3: Independent Code Review

Useful when you want "fresh eyes" to review implemented code. You get objective feedback free from the biases held by the main session.

Pattern 4: Pipeline Workflow

Process design → implementation → testing sequentially with clear handoff points between each phase. Delegating each phase to a subagent prevents context pollution between phases.

When to Use Subagents — and When to Avoid Them

The official blog lists the following "signals to delegate":

Tasks well-suited for delegation

• Research involving reading 10 or more files
• Situations where 3 or more independent tasks can run in parallel
• Situations requiring unbiased third-party review
• Pipeline-style workflows with clear inputs and outputs

Tasks not well-suited for delegation

• Sequential work where the output of one step is directly the input for the next
• Multiple edits to the same file (prone to conflicts)
• Quick fixes involving only 1 file
• Work requiring tight coordination between subagents

Model Selection Strategy to Control Costs

By choosing different models for each subagent, you can optimize for both cost and speed.

• Haiku: Tasks requiring little reasoning, such as file exploration, log searching, and simple string replacement
• Sonnet: Code pattern analysis, reviews, and medium-scale refactoring
• Opus: Complex architectural decisions, design reviews, and difficult bug investigations

Running the main session on Opus while routing routine research like Explore to Haiku is particularly effective from a cost-performance perspective.

Claude Code subagents are not merely a "parallelization mechanism" — they embody a design philosophy that integrates context management, permission control, and team sharing into one. Start by creating a single custom subagent with the /agents command and delegating your most repetitive research tasks to it.

Sources & Reference Links

• Create custom subagents — Claude Code Docs — Official documentation
• How and when to use subagents in Claude Code — Anthropic Blog — Explanation of the design philosophy
• Introduction to subagents — Anthropic Courses — Introductory course