Claude Code Subagents Guide: Parallel Task Execution and Multi-Agent Workflows

What Are Claude Code Subagents and Why They Matter

When you ask Claude Code to perform a complex task, it typically works sequentially — reading files, making changes, running commands, one after another. For tasks with independent components, this is unnecessarily slow. If you need to update 5 test files, refactor 3 modules, and generate documentation for 4 APIs, these can happen simultaneously.

Subagents are separate Claude Code instances that run in parallel, each handling an independent piece of work. The main agent dispatches tasks to subagents, each subagent works independently (reading different files, making different changes), and the results are collected when they complete. This turns a 30-minute sequential session into a 10-minute parallel session.

The key constraint: subagents work best with tasks that do not share state. If two subagents try to modify the same file, you get conflicts. The art of subagent workflow design is decomposing work into independent, non-overlapping pieces.

When to Use Subagents vs. Sequential Execution

Use Subagents When:

• Tasks are independent (different files, different modules)
• No shared state between tasks
• Each task takes more than 2 minutes (overhead of launching subagents is not worth it for quick tasks)
• Total work would take 15+ minutes sequentially

Stay Sequential When:

• Tasks depend on each other (output of task A is input to task B)
• Tasks modify the same files
• The work is simple enough to complete in under 5 minutes
• You need tight control over execution order

Examples of Good Subagent Decomposition

Good (independent tasks):

Task 1: Write unit tests for src/services/userService.ts
Task 2: Write unit tests for src/services/orderService.ts
Task 3: Write unit tests for src/services/paymentService.ts
Task 4: Update API documentation for /api/users endpoints
Task 5: Update API documentation for /api/orders endpoints

Bad (interdependent tasks):

Task 1: Create the database schema
Task 2: Write the service layer (depends on schema from Task 1)
Task 3: Write the API routes (depends on service from Task 2)

How Subagents Work in Claude Code

Launching Subagents

In Claude Code, you can dispatch subagents using the Agent tool. Each subagent gets:

• A clear task description
• Specific files or directories to work on
• Context about the project (from CLAUDE.md)
• Its own independent execution environment

Subagent Communication Model

Subagents operate independently:

• They read files from the shared filesystem
• They make changes to their designated files
• They do not communicate with each other during execution
• The main agent collects results after completion

Foreground vs. Background Execution

• Foreground subagents: the main agent waits for completion before proceeding. Use when you need the result before the next step.
• Background subagents: the main agent continues working while the subagent runs. Use for truly independent tasks.

Workflow Patterns

Pattern 1: Fan-Out / Fan-In

The most common pattern: dispatch multiple subagents, wait for all to complete, then integrate.

Step 1 (Main): Analyze the codebase and identify independent tasks
Step 2 (Fan-out): Launch 4 subagents in parallel
  - Subagent A: Refactor module X
  - Subagent B: Refactor module Y
  - Subagent C: Write tests for module Z
  - Subagent D: Update documentation
Step 3 (Fan-in): Collect results from all 4 subagents
Step 4 (Main): Run full test suite to verify integration
Step 5 (Main): Fix any cross-module issues

Pattern 2: Explore and Execute

Use subagents for research, then execute based on findings.

Step 1 (Fan-out): Launch exploration subagents
  - Subagent A: Find all deprecated API usage
  - Subagent B: Analyze test coverage gaps
  - Subagent C: Check for security vulnerabilities
Step 2 (Fan-in): Collect findings
Step 3 (Main): Prioritize issues
Step 4 (Fan-out): Launch fix subagents for top priorities
  - Subagent D: Fix deprecated APIs in module X
  - Subagent E: Add missing tests for module Y
Step 5 (Main): Verify all fixes

Pattern 3: Pipeline with Parallel Stages

Some stages of a pipeline can run in parallel even when the overall pipeline is sequential.

Stage 1 (Sequential): Create database migration
Stage 2 (Parallel):
  - Subagent A: Create service layer
  - Subagent B: Create type definitions
  - Subagent C: Create validation schemas
Stage 3 (Sequential): Create API routes (depends on Stage 2)
Stage 4 (Parallel):
  - Subagent D: Write unit tests
  - Subagent E: Write API documentation
  - Subagent F: Create frontend components

Best Practices for Subagent Task Design

1. Define Clear Boundaries

Each subagent should know exactly which files it owns:

Subagent A: "Work only on files in src/services/user/.
Do not modify any files outside this directory."

Subagent B: "Work only on files in src/services/order/.
Do not modify any files outside this directory."

2. Provide Sufficient Context

Subagents start with a fresh context. Include:

• The specific task to perform
• File paths to read for reference
• Patterns to follow (reference existing code)
• Constraints and conventions

3. Avoid Shared File Modification

If two subagents need to modify the same file (e.g., adding exports to an index.ts), have the main agent handle the integration file after subagents complete.

4. Set Appropriate Timeouts

Complex subagent tasks may take 5-15 minutes. Set expectations:

• Simple search/analysis: 1-3 minutes
• Code generation for one module: 3-8 minutes
• Refactoring with tests: 5-15 minutes

5. Verify After Integration

Always run the full test suite after collecting subagent results. Subagents verify their own work, but cross-module interactions may reveal issues.

Real-World Example: Feature Implementation

Scenario: Add Notification System

A new notification system requires:

1. Database schema (notifications table)
2. Service layer (create, read, mark-as-read, delete)
3. API routes (CRUD endpoints)
4. WebSocket handler (real-time delivery)
5. Frontend components (notification bell, dropdown, list)
6. Unit tests for service and API
7. Integration tests

Sequential Approach: ~45 minutes

Steps 1-7 in order, each depending on the previous.

Subagent Approach: ~20 minutes

Stage 1 (Main, 5 min): Create database schema and types

Stage 2 (Parallel, 10 min):
  - Subagent A: Service layer + unit tests
  - Subagent B: API routes + API tests
  - Subagent C: WebSocket handler
  - Subagent D: Frontend components

Stage 3 (Main, 5 min): Integration, verify, fix issues

Stage 2 tasks can run in parallel because:

• Each touches different files
• They all depend on Stage 1 (schema/types) but not on each other
• The main agent handles integration in Stage 3

Troubleshooting Common Issues

Subagent Modifies Wrong Files

The subagent did not respect its file boundary. Fix: be more explicit in the task description: “Only modify files matching src/services/user/**. Do NOT touch any other files.”

Results Are Inconsistent

Two subagents made different assumptions about shared types. Fix: create shared types in Stage 1 before dispatching subagents. Pass the type definitions as context to each subagent.

Subagent Takes Too Long

The task was too large for a single subagent. Fix: break it into smaller pieces. A subagent that refactors 10 files will take longer than two subagents that each refactor 5 files.

Integration Fails After Collecting Results

Cross-module imports or type mismatches. Fix: run typecheck and tests after integration. Use the main agent to fix any issues that the subagents could not anticipate.

Frequently Asked Questions

How many subagents can run simultaneously?

The practical limit depends on your system resources and API rate limits. 2-5 concurrent subagents is typical. More than 5 rarely provides additional speedup due to API throttling.

Do subagents share conversation context with the main agent?

No. Each subagent starts with a fresh context. You must include all necessary information in the task description. They do share the filesystem (CLAUDE.md, project files).

Can subagents launch their own subagents?

Technically possible but not recommended. Deeply nested subagent hierarchies are hard to manage and debug. Keep the hierarchy flat: main agent → subagents.

Do subagents cost more than sequential execution?

Subagents use the same per-token pricing as sequential execution. The total token cost is similar — you are parallelizing the work, not duplicating it. Wall-clock time decreases while API cost stays roughly the same.

Can I use subagents for non-coding tasks?

Yes. Subagents work for any task Claude Code can perform: research, documentation, analysis, file organization. The parallel benefit applies whenever you have independent tasks.