Claude Code Parallel Agents: 3 Key Differences Between Sessions, Subagents, and Teams

By /

Table of Contents

Working with Claude Code in a monorepo where 10 CI/CD pipelines run simultaneously, a single session creates bottlenecks. Modifying infrastructure code while running API tests and updating documentation in parallel is a daily occurrence. Claude Code provides three distinct parallel processing approaches for this problem. Without a clear understanding of the Claude Code parallel agent differences, unnecessary token consumption and Git conflicts are inevitable.

This article breaks down the architecture of desktop parallel sessions, subagents, and Agent Teams, analyzing which workflows each approach fits best with evidence-based reasoning.

Why Parallel Work Matters and Problem Definition

![parallel-work-problem-definition]({{image:parallel-work-problem-definition|Technical diagram style illustration of a single pipeline splitting into three diverging tracks, one track blocked by a red collision symbol representing Git conflict, another track showing tangled context threads overlapping, third track showing idle waiting with a clock icon, muted gray and red warning palette on white background, landscape orientation, no text, no letters, no words, no characters}})

A single Claude Code session processes tasks sequentially within one context window. When infrastructure changes, application code modifications, and test automation need to happen simultaneously in a monorepo, three problems emerge.

First, context contamination. Handling Terraform HCL files and React components in the same session causes the model to bleed context from previous tasks into current ones. Second, Git conflict risk. Modifying multiple areas on the same branch simultaneously tangles commit history. Third, wasted wait time. If one task must complete before another can start, total processing time adds up linearly.

Claude Code addresses these three problems at different abstraction levels. Desktop parallel sessions provide project-level isolation, subagents handle task-level delegation, and Agent Teams manage collaboration-level coordination. The core of Claude Code parallel agent differences lies in this abstraction layer distinction.

Abstraction Levels of the Three Approaches
Desktop parallel sessions physically separate projects using independent Git worktrees. Subagents spawn child processes within a single session with access to specific tools only. Agent Teams enable multiple Claude Code instances to exchange messages and collaborate on shared work.

How Desktop Parallel Sessions Work

![desktop-parallel-session-worktree]({{image:desktop-parallel-session-worktree|Minimalist line art of a project root directory branching into three isolated worktree containers side by side, each container holding a distinct branch symbol with its own commit nodes, thin connecting lines to a common origin node above, clean white background with teal accent lines, landscape orientation, no text, no letters, no words, no characters}})

The Claude Code desktop app offers parallel sessions, automatic Git worktree isolation, drag-and-drop layouts, an integrated terminal/file editor, side chat, visual diff review, and live app preview. Clicking + New session in the sidebar or pressing Cmd+N (macOS) / Ctrl+N (Windows) enables parallel work, with each session isolated via Git worktrees so they don’t affect each other until commit time.

Worktree Storage Path and Configuration

Desktop app worktrees are stored by default at <project-root>/.claude/worktrees/. Custom directories and branch prefixes can be configured in Settings → Claude Code. Worktrees are removed when sessions are archived, and an auto-archive option (Auto-archive after PR merge or close) is also supported.

The CLI achieves the same isolation with the --worktree (-w) flag. According to the Claude Code workflow guide, usage looks like this:

# Start Claude in a worktree named "feature-auth"
claude --worktree feature-auth

# Start another session in a separate worktree
claude --worktree bugfix-123

# Auto-generates a name like "bright-running-fox"
claude --worktree

This command creates a new branch in .claude/worktrees/feature-auth/, forked from origin/HEAD. Omitting the name auto-generates one. When a session ends, worktrees with no changes are automatically cleaned up; worktrees with changes offer a keep/delete choice.

Parallel Sessions from a DevOps Perspective

Parallel sessions are fundamentally a structure where humans manually switch context. Session A modifies Terraform modules, session B updates Helm charts, but there’s no automatic coordination between the two. Since each session works on an independent branch, Git conflicts are resolved at the PR stage.

Leveraging Worktree Auto-Cleanup
Enabling auto-archive after PR merge prevents the `.claude/worktrees/` directory from growing indefinitely. Unless working on long-lived branches, activating this option is beneficial for disk management.

Subagent Architecture and Claude Code Parallel Agent Differences

Subagents are child AI instances that operate within a single session. According to the Claude Code subagents documentation, subagents are specialized AI assistants with dedicated context windows, custom system prompts, specific tool access, and independent permissions. Benefits include context preservation, constraint enforcement, cross-project configuration reuse, specialized behavior, and cost savings through routing to lightweight models like Haiku.

Built-in Subagent Types

Claude Code includes three built-in subagents:

SubagentModelTool AccessPurpose
ExploreHaikuRead-onlyCodebase exploration, file search
PlanInherits main modelRead-onlyImplementation strategy design, architecture analysis
General-purposeInherits main modelAll toolsComplex multi-step tasks

The fact that the Explore agent routes to Haiku matters for cost management. Repetitive, simple tasks like codebase searches don’t need an expensive model.

Custom Subagent Definitions

Project-specific subagents are defined as markdown files in the .claude/agents/ directory.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Saving this file at .claude/agents/code-reviewer.md makes the code-reviewer subagent available in that project. User-level subagents go in ~/.claude/agents/, project-level in .claude/agents/.

Session-scoped subagents can also be defined via JSON using the --agents flag in the CLI:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Worktree Isolation and Subagents

Setting a subagent’s isolation field to worktree runs it independently in a temporary Git worktree, with automatic cleanup if no changes are made. This uses the same mechanism as desktop parallel session worktrees, but the key difference is that subagent results are automatically reported back to the main agent. Desktop parallel sessions require humans to manually check results and merge.

No Inter-Subagent Communication
Subagents report results only to the main agent — they don’t communicate with each other. If a workflow requires subagent B to reference subagent A’s results, the main agent must relay results in between.

Agent Teams Structure and Collaboration Mechanism

Agent Teams is an experimental feature where multiple Claude Code instances collaborate through a shared task list and mailbox. One session acts as team lead to coordinate work, while teammates operate in independent context windows and can exchange direct messages. As specified in the Claude Code Agent Teams documentation, activation requires an environment variable:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Four Core Components

Agent Teams architecture consists of four components.

Team Lead is the main session that creates the team and coordinates work. Teammates are independent Claude Code instances, each with its own context window. Task List is a shared work list visible to the entire team. Mailbox is an inter-agent messaging system — a channel for teammates to exchange direct messages.

Team configuration is stored at ~/.claude/teams/{team-name}/config.json, and tasks at ~/.claude/tasks/{team-name}/. Version 2.1.32 or later is required.

Display Modes: in-process vs split panes

Agent Teams supports two display modes: in-process (default, compatible with all terminals) and split panes (requires tmux or iTerm2). In in-process mode, Shift+Down switches between teammates. In split panes mode, each teammate gets its own pane.

{
  "teammateMode": "in-process"
}

This is configured in ~/.claude.json. In DevOps environments where SSH connections to remote servers are common, tmux is likely already installed, making split panes mode advantageous for visual monitoring.

Experimental Feature Status
Agent Teams is an experimental feature as of April 2026. It must be explicitly enabled with the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Limitations should be reviewed before adopting it in production workflows.

Comparative Analysis of All Three — Claude Code Parallel Agent Differences Summary

The three approaches diverge clearly in isolation unit, communication method, and coordination authority.

ComparisonDesktop Parallel SessionsSubagentsAgent Teams
Isolation UnitGit worktree (physical)Context window (logical)Independent instance (process)
CommunicationNone (manual review)Main→sub unidirectional reportingMailbox bidirectional messaging
Coordination AuthorityHumanMain agentTeam lead + shared task list
Model SelectionIndependent per sessionSpecified per agent (Haiku, etc.)Independent per instance
Git Conflict ResolutionPR stagePR stage (when using worktree)PR stage
State SharingNoneResults returned to main onlyTask list + messages
Minimum RequirementDesktop appCLI/desktop both supportedv2.1.32 or later
StabilityProduction featureProduction featureExperimental

Key Difference: Communication Topology

The core difference between subagents and Agent Teams lies in communication structure. Subagents report results only to the main agent within a single session and don’t communicate with each other. Agent Teams teammates coordinate autonomously through a shared task list and can exchange direct messages. Subagents suit focused tasks where only results matter; Agent Teams suit complex tasks requiring discussion and collaboration.

The communication structure of all three approaches, expressed in Mermaid:

flowchart TB
    subgraph Desktop["Desktop Parallel Sessions"]
        S1[Session A] ---|"Isolated"| S2[Session B]
        S1 ---|"Isolated"| S3[Session C]
        S2 ---|"Isolated"| S3
        U[User] --> S1
        U --> S2
        U --> S3
    end

    subgraph Sub["Subagents"]
        M[Main Agent] --> SA1[Sub A]
        M --> SA2[Sub B]
        M --> SA3[Sub C]
        SA1 -.->|"Result Report"| M
        SA2 -.->|"Result Report"| M
        SA3 -.->|"Result Report"| M
    end

    subgraph Team["Agent Teams"]
        TL[Team Lead] <-->|"Mailbox"| T1[Teammate A]
        TL <-->|"Mailbox"| T2[Teammate B]
        T1 <-->|"Mailbox"| T2
        TK[Shared Task List] --- TL
        TK --- T1
        TK --- T2
    end

Desktop parallel sessions resemble a hubless distributed structure, subagents follow a star topology, and Agent Teams approximate a mesh topology. In automation pipelines, this difference determines how inter-task dependencies are handled.

Workflow-Based Selection Criteria and Decision Framework

Which of the three to choose depends on the nature of the work. The following decision tree guides the selection.

Independent Parallel Tasks → Desktop Parallel Sessions

Tasks have no dependencies and each modifies different directories or modules. For example, running frontend refactoring and backend API additions simultaneously, then merging via PR after both complete.

Suitable scenarios:

  • Modifying different packages simultaneously in a monorepo
  • Running hotfixes and feature development in parallel
  • Independently changing configurations for multiple environments (staging, production)

Delegation Tasks Where Only Results Matter → Subagents

A specific subtask needs delegation during the main workflow, and only the result matters. Code review, codebase exploration, and test execution fall into this category. Subagents can route to lightweight models like Haiku, making them cost-efficient.

Suitable scenarios:

  • Automated review after code changes
  • Searching for specific patterns in large codebases
  • Analyzing change impact scope and summarizing results

Complex Tasks Requiring Coordination → Agent Teams

Multiple tasks must reference each other’s progress and coordinate. Teammate A changes the database schema, teammate B modifies API endpoints accordingly, and teammate C updates the frontend — a chain of dependent tasks.

Suitable scenarios:

  • Database migration + API changes + frontend modifications needed in sequence
  • Simultaneously changing interfaces across multiple microservices
  • Code writing and test writing by separate agents exchanging feedback in parallel

Subagents can reduce token costs through lightweight model routing. Agent Teams runs independent instances for each teammate, increasing token consumption. The official documentation doesn’t specify exact cost multipliers, so token usage should be monitored during actual use.

Practical Configuration Examples: DevOps Pipeline Automation

Here are practical configurations leveraging Claude Code parallel agent differences in CI/CD pipelines. Mixing all three approaches is the most realistic strategy in practice.

Subagent-Based Code Review Automation

Define a subagent that automatically runs code review after infrastructure code changes. Save the following in .claude/agents/infra-reviewer.md:

---
name: infra-reviewer
description: Reviews infrastructure code changes
tools: Read, Glob, Grep
model: sonnet
---

Terraform, Helm, Dockerfile

This subagent can only access Read, Glob, and Grep, so it doesn’t modify code. The read-only constraint ensures review safety.

Worktree + Subagent Combination in CLI

A workflow where infrastructure changes proceed in one worktree while a subagent analyzes change impact:

claude --worktree infra-update
claude --worktree monitoring-config

The two sessions are isolated, so Terraform modules can be modified in the infra-update worktree while Prometheus configuration changes independently in the monitoring-config worktree. Within each session, subagents handle delegated tasks like code review or exploration.

Multi-Service Updates with Agent Teams

Consider a scenario where API versions across multiple microservices need simultaneous upgrades. The team lead defines the change scope, and each teammate takes on a service.

Setting teammateMode to in-process enables switching between teammates with Shift+Down in a single terminal. In tmux environments, split panes mode is better for monitoring each teammate’s progress simultaneously.

Project structure example:
~/.claude/teams/api-upgrade/
├── config.json          ← Team configuration
└── ...
~/.claude/tasks/api-upgrade/
├── task-001.json        ← auth service API v2 migration
├── task-002.json        ← payment service API v2 migration
└── task-003.json        ← notification service API v2 migration

When teammate A changes the auth service’s API schema, the modified interface is communicated to teammate B via mailbox. Teammate B references this to update the payment service’s client code. This autonomous coordination is Agent Teams’ distinguishing feature.

Limitations, Caveats, and Practical Selection Guide

All three approaches have their own constraints. These limitations must be clearly understood before adopting them in production workflows.

Agent Teams Restrictions

Agent Teams is an experimental feature with the following limitations: in-process teammates cannot be restored with /resume. Task state updates may experience delays. Shutdown speed can be slow. Only one team per session is allowed — nested teams are not possible. The team lead cannot be changed. Teammate permissions can only be modified individually after creation. Split pane mode is not supported in VS Code integrated terminal, Windows Terminal, or Ghostty.

No Resume Support
In-process mode teammates cannot be restored with `/resume` if the session disconnects. For long-running work, use split panes mode or break tasks into smaller units for safety.

Areas Not Covered in Official Documentation

No official guide provides an integrated comparison of desktop parallel sessions, Agent Teams, and subagents. The specific token cost multiplier for Agent Teams isn’t documented either. There’s no documentation on managing Agent Teams via a GUI in the desktop app — only CLI-based explanations exist. Practical examples using .worktreeinclude files for environment variable copying patterns during parallel work are also lacking.

Subagent Scope Management

Subagents can be managed across multiple scopes: .claude/agents/ (project), ~/.claude/agents/ (user), plugins, and managed settings. This multi-layer scoping is flexible, but when subagents with the same name exist in multiple scopes, precedence rules matter. From a DevOps perspective, team-shared subagents should be centrally managed via managed settings, while personal experiments belong in user scope — this reduces operational complexity.

Isolation level and communication structure are the core criteria for choosing among the three approaches. Independent work maps to desktop parallel sessions, delegation to subagents, and collaborative work to Agent Teams. A hybrid structure delivers both token efficiency and operational safety in practice — isolate branches with worktrees, delegate repetitive tasks with subagents within each session, and activate Agent Teams only when cross-cutting changes are needed.

Once Agent Teams transitions from experimental to production status, the landscape of Claude Code multi-agent comparison may shift significantly. For now, building automation pipelines around subagents while validating Agent Teams in limited scope is the pragmatic approach. The next areas to explore are parallel code review automation using isolation: worktree in Claude Code subagent creation, and patterns for connecting Agent Teams task lists with CI pipeline triggers. The combination of --worktree flags and custom subagents alone covers a substantial portion of Claude Code parallel work workflows, making this combination the most realistic starting point for applying Claude Code parallel agent differences in practice.

Read next

Scroll to Top