Claude Code Subagents: Complete Guide to Parallel AI Agents (2026)

Claude Code Subagents: Complete Guide to Parallel AI Agents (2026)

Claude Code subagents are specialized AI agents that run inside a single Claude Code session, each with its own system prompt, tool access, and context window. Instead of asking one Claude instance to do everything -- research, write code, run tests, review changes -- you delegate each task to a dedicated subagent that works in parallel and reports back with structured output. This cuts task completion time by 40-60% compared to sequential prompting.

Subagents are Claude Code's answer to the multi-agent problem: how do you get specialized AI agents to collaborate without manually copy-pasting context between tools? For developers already using Claude Code, subagents are the fastest way to build a mini development team inside your terminal.

In this guide:

• What are Claude Code subagents?
• How subagents work
• Setting up your first subagent
• Real-world subagent workflows
• Cost and performance analysis
• Limitations and workarounds
• Scaling beyond subagents: cross-provider squads

Related guides: How to Use Claude Code (Beginner Guide) · Claude Code vs Cursor · Claude Code vs OpenCode · Claude Code Task Management · MCP Servers Guide · AI Coding Assistant Pricing · How to Use Cursor AI · Best Claude Code Alternatives · All Tutorials

What Are Claude Code Subagents?

A subagent is a delegated AI agent within Claude Code that operates with:

• Its own system prompt -- defining its role and behavior
• Scoped tool access -- restricting which tools it can use (file read, file write, bash, web search)
• Isolated context -- maintaining its own conversation history separate from the main session
• Structured output -- returning results in a defined format that the orchestrator can use

Think of subagents as hiring specialists for a project. Instead of one generalist doing everything sequentially, you assign a researcher to gather requirements, a coder to implement, and a reviewer to check -- all running concurrently.

Subagents vs Regular Claude Code

For a deeper comparison of Claude Code itself versus other tools, see our Claude Code vs Cursor benchmark.

How Subagents Work

Claude Code subagents follow a delegation pattern:

1. Orchestrator (main Claude Code session) receives a complex task
2. Orchestrator decomposes the task into subtasks
3. Orchestrator spawns subagents, each with a specific role and scoped tools
4. Subagents execute independently, each working in its own context
5. Subagents return structured results to the orchestrator
6. Orchestrator combines results and produces the final output

This pattern is similar to how multi-agent frameworks like CrewAI and LangGraph work, but built directly into Claude Code's CLI without requiring Python or external orchestration code.

Key Configuration Options

Each subagent can be configured with:

• systemPrompt: Instructions defining the agent's role (e.g., "You are a code reviewer focused on security vulnerabilities")
• tools: Which tools the agent can access (e.g., ["Read", "Grep"] for a research agent, ["Read", "Write", "Bash"] for a coding agent)
• model: Which Claude model to use (e.g., claude-sonnet-4-20250514 for speed, claude-opus-4-20250514 for complex reasoning)
• maxTokens: Maximum output tokens per subagent invocation

Setting Up Your First Subagent

Prerequisites

• Claude Code installed (see our Claude Code beginner guide for setup)
• Anthropic API key configured
• Node.js 18+

Example: Research + Code Subagent Workflow

Here is a practical example. You want to add a new API endpoint to your app. Instead of doing it all yourself, you set up two subagents:

Subagent 1 -- Researcher:

Role: Analyze existing codebase patterns
Tools: Read, Grep, Glob
Task: Find how existing API endpoints are structured, what middleware is used, and what response format is standard.
Output: Structured summary of patterns to follow.

Subagent 2 -- Implementer:

Role: Write the new endpoint code
Tools: Read, Write, Bash
Task: Based on the research summary, implement the new endpoint following existing patterns.
Output: List of files created/modified.

The orchestrator runs Subagent 1 first, feeds its output to Subagent 2, then optionally spawns a third subagent to review the implementation.

Configuration File Example

You can define subagents in a configuration file:

{
  "subagents": [
    {
      "name": "researcher",
      "systemPrompt": "You are a code researcher. Analyze the codebase and return structured findings about patterns, conventions, and dependencies. Never write code.",
      "tools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-20250514"
    },
    {
      "name": "coder",
      "systemPrompt": "You are a senior developer. Write clean, tested code following the project's existing patterns. Always run tests after changes.",
      "tools": ["Read", "Write", "Bash", "Grep"],
      "model": "claude-sonnet-4-20250514"
    },
    {
      "name": "reviewer",
      "systemPrompt": "You are a code reviewer. Check for security issues, performance problems, and edge cases. Return a prioritized list of issues.",
      "tools": ["Read", "Grep", "Bash"],
      "model": "claude-opus-4-20250514"
    }
  ]
}

This config creates a three-agent team: a fast researcher, a coding agent, and an Opus-powered reviewer for quality control.

Real-World Subagent Workflows

Workflow 1: Bug Investigation + Fix

When a user reports a bug, spawn two subagents:

• Investigator: Searches logs, reads error messages, identifies root cause
• Fixer: Implements the fix based on the investigator's findings

This cuts debugging time from 20-30 minutes to 5-8 minutes for common bugs.

Workflow 2: Feature Research + Implementation

Before building a feature:

• Researcher: Reads docs, searches for libraries, evaluates options
• Architect: Designs the implementation plan
• Coder: Writes the code

For a step-by-step guide on managing these workflows, see our Claude Code Task Management guide.

Workflow 3: Code Review Pipeline

After writing code:

• Security Reviewer: Checks for vulnerabilities (OWASP top 10)
• Performance Reviewer: Identifies N+1 queries, unnecessary allocations
• Style Reviewer: Ensures consistency with project conventions

Three parallel reviews catch more issues than a single pass.

Cost and Performance Analysis

Token Costs Per Subagent

A typical 3-subagent workflow (research + code + review) costs approximately $0.21 per task in API costs. For comparison, a single Claude Code session doing the same work sequentially costs ~$0.12 but takes 2-3x longer.

For detailed pricing across all AI coding tools, see our AI Coding Assistant Pricing comparison.

Speed Comparison

In our testing of 15 real development tasks:

Subagents excel at tasks with clear separation between research, implementation, and review phases.

Limitations and Workarounds

Limitation 1: Same Provider Only

Claude Code subagents only use Claude models. You cannot mix GPT-4, Gemini, or local models within subagents. If you need cross-provider teams, see Scaling Beyond Subagents below.

Limitation 2: Terminal-Only Interface

Subagents run in the terminal. There is no visual dashboard to monitor progress, reassign tasks, or view agent outputs side by side. This makes it hard to manage more than 3-4 subagents simultaneously.

Workaround: Use Ivern AI's unified task board to visually manage Claude Code subagents alongside agents from other providers. See how to connect Claude Code to Ivern.

Limitation 3: No Persistent State Between Sessions

Subagent context is lost when you close Claude Code. If you run the same workflow tomorrow, each subagent starts fresh with no memory of yesterday's work.

Workaround: Use a shared context layer or save subagent outputs to files that the next session can read.

Limitation 4: Token Costs Scale Linearly

Each subagent consumes tokens independently. Running 5 subagents costs 5x a single agent. For cost-sensitive workflows, use Sonnet 4 for most agents and reserve Opus 4 for the final review step.

Scaling Beyond Subagents

Claude Code subagents are powerful for single-provider, terminal-based workflows. But what if you need to:

• Mix Claude, GPT-4, and Gemini in the same squad?
• Monitor agents through a web dashboard?
• Run persistent agent teams across sessions?
• Share context between agents from different providers?

That is where Ivern AI comes in. Ivern connects Claude Code, Cursor, OpenAI, and other AI tools into coordinated squads with:

• Cross-provider orchestration: Mix Claude for coding, GPT-4 for research, Gemini for analysis
• Unified task board: Visual dashboard to monitor all agents in real time
• Persistent agent templates: Save squad configurations and reuse them across sessions
• BYOK pricing: No markup on API costs -- you pay exactly what the providers charge

For a full comparison of multi-agent orchestration approaches, see our Best AI Agent Platforms 2026 ranking and our Ivern vs LangGraph comparison.

<details> <summary><strong>FAQ: Claude Code Subagents</strong></summary>

Can subagents write to the same file simultaneously?

No. Subagents run in sequence within a single Claude Code session when they need to modify files. Parallel execution is safe for read-only tasks (research, analysis). For write operations, the orchestrator serializes access.

How many subagents can I run at once?

There is no hard limit, but we recommend 3-5 for practical use. More than 5 subagents becomes difficult to manage in the terminal and increases token costs significantly.

Do subagents work with MCP servers?

Yes. Subagents can use MCP servers as tools. You can give a research subagent access to a web search MCP server while restricting the coding subagent to local file tools only.

Can I use subagents with the Claude Code API?

Yes. The Claude Code API supports subagent configuration programmatically, which is useful for building CI/CD pipelines. For production deployment patterns, see our Claude Code workflow automation guide.

How do subagents compare to Cursor's Background Agents?

Cursor Background Agents are IDE-based and visual, while Claude Code subagents are terminal-based and scriptable. Cursor is better for interactive development; Claude Code subagents are better for automation. See our Claude Code vs Cursor comparison for the full breakdown.

</details>

Summary

Claude Code subagents transform a single-agent terminal tool into a multi-agent development system. By delegating research, coding, and review to specialized subagents, you can cut task completion time by 40-60% while improving output quality.

Key takeaways:

• Start with 2-3 subagents (researcher + coder + reviewer)
• Use Sonnet 4 for most agents, Opus 4 for the final review
• Cost is ~$0.21 per 3-agent task -- affordable for BYOK users
• For cross-provider teams, use Ivern AI to orchestrate Claude, GPT-4, and Gemini together

Ready to build your first multi-agent squad? Get started free with Ivern AI -- connect your Claude Code instance and other AI tools into coordinated teams in under 5 minutes.

More guides: Claude Code Beginner Guide · Claude Code vs Cursor · Claude Code vs OpenCode · Claude Code Task Management · MCP Servers Guide · AI Coding Assistant Pricing · Best Claude Code Alternatives · How to Use Cursor AI · Cursor Rules File Guide · Best AI Agent Platforms 2026 · Ivern vs LangGraph · Multi-Agent AI Teams Guide · All Tutorials