Claude Code Parallel Tasks in Practice: A Complete Guide to Subagents, Agent Teams, and Git Worktrees

As development tasks grow increasingly complex, a single Claude instance often struggles to keep up — context gets too long, responses slow down, and interleaved tasks become impossible to untangle. The "context getting too long" issue touches on a core limitation of large language models: the Context Window. Every model can only process a limited number of tokens in a single conversation. When development tasks involve numerous code files, test cases, and documentation, a single conversation's context fills up quickly, causing the model to "forget" earlier information or degrade in response quality. The essence of parallelization is splitting a massive task across multiple independent contexts, where each instance only needs to focus on its own subtask, thereby sidestepping this bottleneck.

To address this pain point, Claude Code offers three parallelization approaches: Subagents, Agent Teams, and Git Worktrees. Used effectively, they enable multiple Claude instances to work for you simultaneously, significantly boosting development efficiency. This article systematically covers the use cases, configuration methods, and practical tips for all three mechanisms.

How to Choose Among the Three Parallel Mechanisms

Before diving into the details, let's establish a clear selection framework. These three approaches essentially correspond to three different levels of collaboration complexity:

• Subagents: Best for focused tasks where you only care about results, using one-way reporting (results returned to the main agent), with the lowest complexity.
• Agent Teams: Best for complex work requiring discussion and collaboration, where teammates can send messages directly to each other — multi-directional communication with moderate complexity.
• Git Worktrees: Used when multiple tasks need isolated code environments, with each task having a completely independent working directory, at moderate complexity.

The selection advice is actually straightforward: Use subagents for parallel processing of independent subtasks; use agent teams when multiple agents need to discuss and coordinate; use Git worktrees when multiple tasks need to operate on different branches of the same repository.

This complexity ladder from low to high covers the vast majority of scenarios from simple parallelism to deep collaboration. Understanding their differences is key to using Claude Code efficiently.

Subagents: Focused Task Executors

A subagent is an independently running Claude instance with its own context and task focus. The main Claude can create multiple subagents, each responsible for a specific subtask, with up to 49 running in parallel — more than enough for most parallel processing needs.

Built-in Subagents Overview

Claude Code comes with several ready-to-use built-in subagents, each with its own role:

• Explore: Uses the Haiku model + read-only tools for file discovery and codebase exploration.
• Plan: Inherits the main conversation model + read-only tools for codebase research in planning mode.
• General Purpose: Inherits the main conversation model + has access to all tools for complex research and code modifications.
• Status Line Setup: Configures the status bar.
• Claude Code Guide: Answers feature-related questions.

What's interesting is the model pairing strategy for built-in subagents — exploration tasks use the lightweight Haiku model to control costs, while modification tasks inherit the main conversation model to ensure capability. It's worth elaborating on Anthropic's model tier system here: Haiku is a lightweight model with fast inference speed and low token cost, suitable for simple file retrieval and information extraction; Sonnet is a mid-tier model balancing performance and cost; Opus is the flagship model for complex reasoning. Claude Code's approach here reflects the industry-common concept of "Model Routing" — dynamically selecting models based on task complexity to accomplish work at minimal cost. In production environments, this tiered strategy is very common — for example, using a lightweight model for intent recognition first, then forwarding complex requests to a high-capability model. This is a textbook example of fine-grained token cost control.

How to Create and Invoke Subagents

There are two ways to create subagents: first, using the /agents slash command — run it, select "create new agent," choose a save location, describe the functionality, and let Claude generate the configuration; second, manually creating a subagent file configured with a YAML frontmatter followed by a system prompt in Markdown format.

This configuration paradigm is worth understanding: YAML (YAML Ain't Markup Language) is a human-friendly data serialization format widely used for configuration files. In subagent configuration, the YAML frontmatter defines structured metadata — technical parameters like model selection and tool permissions — while the Markdown body that follows serves as the System Prompt, injected at the start of each conversation to determine the agent's role, behavioral boundaries, and output style. This combination of "structured configuration + natural language instructions" gives developers precise control over technical parameters while allowing flexible natural language descriptions of how the agent should work.

Common configuration fields include:

Field	Description
name	Unique identifier using lowercase letters and hyphens
description	Describes when to delegate to this subagent
tools	List of available tools
disallowedTools	Tools the agent is not allowed to use
model	Specifies which model to use
permissionMode	Permission mode
maxTurns	Maximum interaction turns before stopping

Advanced configurations including Skills, MCP Servers, and Memory are also supported.

There are three ways to invoke subagents:

1. Natural language: Simply say "Use a subagent to fix the failing tests."
2. @ mention: Type @ followed by the subagent name.
3. Terminal launch: Specify the agent name as a Claude parameter.

Regarding execution modes, foreground subagents report to the main conversation until completion, while background subagents can run concurrently, and you can switch between them anytime using the Ctrl+B shortcut. Through tool restrictions and model selection, you have fine-grained control over each subagent's capabilities.

Agent Teams: Collaborative Project Groups of Equals

If subagents are like "workers reporting to a boss," then agent teams are like "collaborative project groups of equals." A main conversation acts as the team lead, coordinating multiple Claude instances working together, where each member has their own context and can communicate directly with one another.

The Core Difference Between Agent Teams and Subagents

This peer-to-peer communication is the fundamental difference between agent teams and subagents. Subagents can only report results one-way and cannot discuss with each other; agent team members can send messages directly to one another, making them suitable for complex work that requires iterative discussion and coordinated decision-making.

From a technical perspective, the multi-directional communication mechanism of agent teams is essentially a concrete implementation of Multi-Agent Systems (MAS) in the software development domain. In AI research, multi-agent systems are an important research area with core challenges including task allocation, conflict resolution, consensus building, and communication efficiency. Claude Code's agent teams adopt a task-list-based asynchronous collaboration model, similar to a Kanban system — each agent picks up tasks, updates status, publishes results, and other agents can read this information and adjust their own work accordingly. This design avoids the blocking issues of synchronous communication while maintaining sufficient coordination capability, representing a pragmatic engineering implementation of academic theory.

Enabling and Using Agent Teams

Agent teams are disabled by default and need to be enabled by adding an environment variable in the settings file or exporting the environment variable. Claude Code version 2.0.132 or above is also required.

Once enabled, simply describe the task and team structure in natural language to get started. Teammates collaborate through a task list, with tasks having three states:

• Pending
• In Progress
• Completed

This state machine makes the collaboration progress of multiple agents clear at a glance, and the team lead can monitor each member's work status in real time.

Git Worktrees: Isolated Sandboxes for Parallel Tasks

When multiple agents work simultaneously, a subtle but critical problem emerges — they might "fight" each other. For example, two tasks might both modify the same file: one saves a certain version, then the other overwrites it with a different version, ultimately causing conflicts or even data loss.

Git worktrees are designed precisely to solve this problem. They allow you to mount multiple independent working directories on the same repository, each with its own branch and staging area, but sharing the same Git database. This way, different tasks are physically isolated from each other, fundamentally preventing write conflicts.

To appreciate the value of worktrees, you need to understand their underlying mechanics. Git Worktree is a native feature introduced in Git 2.5 (released in 2015), solving a long-standing pain point in traditional Git workflows: a repository could only check out one branch at a time. The traditional workaround was cloning multiple repository copies, but this duplicated the entire .git directory (potentially several GB for large projects), wasting disk space and preventing shared references. The elegance of Git Worktree lies in multiple working directories sharing a single .git database (including object storage, references, and configuration), while each working directory maintains an independent HEAD pointer, index (staging area), and working files. Creating a new worktree is virtually zero-cost — it only needs to create a directory and check out files from the target branch without copying any Git objects. This feature is especially valuable in CI/CD pipelines and parallel development scenarios.

How to Use Git Worktrees

To use them, add the --worktree flag and specify a branch name when launching Claude from the terminal. The worktree will be created in the .claude/worktrees directory within the repository. On the desktop client, you can directly enable workspace mode from the code tab.

Taking it further, you can configure custom subagents to always run in their own worktrees, achieving a combination of subagents and isolated environments — a highly practical best practice in parallel development.

Summary: Getting Multiple Claudes to Work for You Simultaneously

Claude Code's three parallel task mechanisms cover different levels of collaboration needs from low to high:

Approach	Use Case	Communication Mode	Complexity
Subagents	Focused independent tasks	One-way reporting	Low
Agent Teams	Complex work requiring discussion and collaboration	Multi-directional communication	Medium
Git Worktrees	Parallel tasks needing isolated code environments	Environment isolation	Medium

The selection rule of thumb remains clear: Use subagents for independent subtasks, agent teams for coordination needs, and worktrees for environment isolation.

The three are not mutually exclusive — in real-world development, they can absolutely be combined. For example, you could run subagent teams in separate Git worktrees, stacking the triple advantages of parallelism, collaboration, and isolation. Mastering this set of mechanisms is how you truly upgrade Claude Code from a single-threaded assistant into a multi-threaded intelligent development team.