For the past year, I have used Claude Code as my primary AI development partner across Laravel backends, Vue.js frontends, and AWS infrastructure. Single-session workflows transformed how I build software. But there was always a friction point: context switching. When a task required coordinated changes across multiple layers of a stack, one Claude Code instance had to jump between concerns, burning through context and losing focus with each pivot.

Agent Teams, released with Opus 4.6 on February 5, 2026, solves this problem by letting you coordinate multiple Claude Code instances working together in parallel. One session acts as the team lead, orchestrating work and synthesizing results, while teammates operate independently in their own context windows and communicate directly with each other.

After spending time with the feature, I can say it changes the dynamics of AI-assisted development in ways that subagents---which I have used extensively---never could. This post covers what Agent Teams is, how it fits into a full-stack development workflow, and practical guidance for getting started.

What Agent Teams Actually Is

At its core, Agent Teams lets you spin up multiple Claude Code instances that work as a coordinated unit. The architecture consists of four components:

Team lead: your main Claude Code session that creates the team, spawns teammates, and coordinates work
Teammates: separate Claude Code instances, each with their own context window and full tool access
Task list: a shared list of work items that teammates claim and complete, with file locking to prevent race conditions
Mailbox: a messaging system for direct communication between agents

The key distinction from running multiple terminal tabs manually is the coordination layer. Teammates share a task list, send each other messages, and the lead synthesizes their work. It is structured collaboration, not just parallel execution.

Teams and their configuration are stored locally in ~/.claude/teams/{team-name}/config.json, with tasks tracked in ~/.claude/tasks/{team-name}/. Everything runs on your machine---there is no cloud orchestration service involved.

How It Differs from Subagents

If you have been using Claude Code for a while, you are probably familiar with subagents. I use them regularly for focused tasks like code reviews and research within a session. The distinction matters because Agent Teams and subagents serve fundamentally different purposes.

Subagents run within your current session. They spin up, do focused work, and return results to the main agent. The main agent manages everything. Think of subagents as delegating a quick task to an assistant who reports back.

Agent Teams are fully independent sessions. Each teammate has its own context window, can message other teammates directly, and self-coordinates through the shared task list. The lead orchestrates but does not micromanage. Think of Agent Teams as assembling a project team where each member owns a domain.

Here is the practical difference in a table:

Aspect	Subagents	Agent Teams
Context	Own context; results return to caller	Own context; fully independent
Communication	Report results to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best for	Focused tasks where only the result matters	Complex work requiring discussion and collaboration
Token cost	Lower	Higher (each teammate is a separate instance)

The token cost difference is real and worth planning for. I covered strategies for managing Claude Code token consumption in my token management guide, and those principles become even more important when running multiple parallel instances.

Real-World Workflow: Full-Stack Feature Development

As a full-stack developer working across Laravel, Vue.js, and AWS, the cross-layer coordination use case resonated with me immediately. Here is how I see Agent Teams fitting into a typical feature build.

Scenario: Adding a New API Endpoint with Frontend Integration

Consider a common task: building a new resource endpoint in a Laravel API, creating the corresponding Vue.js frontend components, and writing tests for both layers. In a single-session workflow, Claude Code would context-switch between backend models, API controllers, frontend components, and test files. By the time it finishes the frontend, it has lost some context about the backend decisions it made earlier.

With Agent Teams, the prompt might look like this:

Create an agent team to build the project milestones feature:
- One teammate owns the Laravel backend: migration, model, controller,
  form request, and API resource at src/app/
- One teammate owns the Vue.js frontend: components, composables,
  and route registration at resources/js/
- One teammate writes tests for both layers: PHPUnit feature tests
  and Vitest component tests
Require plan approval before implementation.

Each teammate works within their own context, fully focused on their domain. The backend teammate can design the API contract and broadcast that to the others. The frontend teammate builds components against that contract. The test teammate writes comprehensive coverage for both layers. The lead coordinates task dependencies---ensuring the API contract is defined before frontend work begins---and synthesizes everything at the end.

Scenario: Debugging a Complex Cross-Layer Issue

Debugging is where the competing hypotheses pattern becomes valuable. When a bug spans multiple layers---say, data not appearing correctly in the frontend despite the API returning what looks like the right response---sequential debugging anchors on the first plausible theory. Agent Teams lets you investigate all theories in parallel:

Users report stale data appearing after updating a project milestone.
Spawn 4 teammates to investigate different hypotheses:
- Cache invalidation issue in the Laravel response cache
- Vue.js reactivity problem in the composable state management
- API resource transformation dropping updated fields
- Browser-side service worker caching stale responses
Have them challenge each other's findings.

The debate structure is the critical mechanism here. Each teammate is not just investigating their theory---they are actively trying to disprove the others. The theory that survives adversarial scrutiny is far more likely to be the actual root cause.

Scenario: Parallel Code Reviews

This is perhaps the most immediately practical use case, building on the AI-assisted code review workflow I already use. Instead of one reviewer trying to evaluate everything, assign specialized reviewers:

Create an agent team to review the authentication refactor PR.
Spawn three reviewers:
- Security reviewer: focus on token handling, CSRF protection,
  and input validation in the Laravel middleware
- Performance reviewer: check for N+1 queries, missing indexes,
  and unnecessary eager loading
- Architecture reviewer: evaluate adherence to Laravel conventions,
  single responsibility principle, and test coverage
Have them each report findings independently.

Each reviewer applies a different lens simultaneously, and the lead synthesizes findings across all three. This mirrors how effective human code review works on experienced teams---different reviewers catch different categories of issues.

Getting Started: Setup and Configuration

Agent Teams is an experimental feature, disabled by default. Here is how to enable and configure it.

Step 1: Enable the Feature

Add the experimental flag to your settings.json:

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

Alternatively, set it as an environment variable in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step 2: Choose a Display Mode

Agent Teams supports two display modes:

In-process mode runs all teammates inside your main terminal. Navigate between them with Shift+Up/Down and message any teammate directly. This works in any terminal with no extra setup.

Split-pane mode gives each teammate their own pane, letting you see everyone's output simultaneously. This requires tmux or iTerm2 with the it2 CLI.

Configure the display mode in settings.json:

{
  "teammateMode": "in-process"
}

The default is "auto", which uses split panes if you are running inside tmux and in-process mode otherwise. For a single session, you can override with:

claude --teammate-mode in-process

Step 3: Spawn Your First Team

Start Claude Code and describe the team you want in natural language. Be specific about roles and responsibilities:

Create an agent team with 3 teammates to research the best approach
for implementing real-time notifications in our Laravel + Vue.js stack.
One on Laravel broadcasting options, one on Vue.js WebSocket libraries,
one on AWS infrastructure requirements.

Claude creates the team, spawns teammates, and coordinates their work. You can interact with any teammate directly using Shift+Up/Down in in-process mode or by clicking into their pane in split-pane mode.

Step 4: Use Delegate Mode for Complex Orchestration

By default, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Press Shift+Tab to enable delegate mode, which restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.

This is particularly useful for large feature builds where you want the lead focused entirely on orchestration---breaking down work, managing dependencies, and synthesizing results.

Best Practices from the Documentation and Early Usage

After reviewing the official documentation and community experiences, here are the patterns that produce the best results.

Size Tasks Appropriately

Tasks that are too small create more coordination overhead than value. Tasks that are too large mean teammates work too long without check-ins. The sweet spot is self-contained units with clear deliverables. Aim for 5-6 tasks per teammate to keep everyone productive and give the lead enough granularity to reassign work if someone gets stuck.

Prevent File Conflicts Through Ownership

Two teammates editing the same file leads to overwrites. Break work so each teammate owns a different set of files. This mirrors how effective human teams operate---clear ownership boundaries reduce merge conflicts and communication overhead.

For a Laravel project, natural ownership boundaries might be:

Backend teammate: models, controllers, migrations, form requests
Frontend teammate: Vue components, composables, route definitions
Test teammate: PHPUnit tests, Vitest specs, factory definitions

Give Teammates Rich Context in Spawn Prompts

Teammates load your project's CLAUDE.md, MCP servers, and skills automatically, but they do not inherit the lead's conversation history. Include task-specific details in the spawn prompt. Explicit specifications produce better results than vague delegation.

If you have been following the Claude Code Laravel workflow approach of maintaining a detailed CLAUDE.md, your teammates automatically inherit that project context, which gives them a significant head start.

Start with Research Before Implementation

If you are new to Agent Teams, begin with tasks that have clear boundaries and do not require writing code: reviewing a PR from multiple angles, researching a library, or investigating a bug with competing theories. These tasks demonstrate the value of parallel exploration without the coordination challenges of parallel implementation.

Require Plan Approval for Risky Changes

For complex or high-risk tasks, require teammates to plan before implementing:

Spawn a teammate to refactor the payment processing module.
Require plan approval before they make any changes.
Only approve plans that include test coverage and rollback steps.

The teammate works in read-only plan mode until the lead approves their approach. If rejected, the teammate revises based on feedback and resubmits.

Limitations Worth Knowing

Agent Teams is experimental, and understanding its limitations upfront saves frustration.

No session resumption with in-process teammates. If you use /resume or /rewind, in-process teammates are not restored. The lead may try to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.

Task status can lag. Teammates sometimes fail to mark tasks as completed, blocking dependent tasks. If a task appears stuck, check whether the work is actually done and tell the lead to update the status or nudge the teammate.

One team per session. A lead can only manage one team at a time. Clean up the current team before starting a new one. Teammates cannot spawn their own teams, so there is no risk of nested teams spiraling token costs.

Token usage scales with teammates. Each teammate is a separate Claude instance with its own context window. For research, review, and new feature work, the extra tokens are usually justified. For routine single-file tasks, a focused single session remains more efficient.

Split panes require tmux or iTerm2. The in-process mode works in any terminal, but split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty. On Linux under WSL2---which is my development environment---tmux works well.

Shutdown can be slow. Teammates finish their current request or tool call before shutting down. Always clean up through the lead to avoid orphaned resources.

Where Agent Teams Fits in the AI Development Toolbox

Agent Teams does not replace the workflows I have built around single-session Claude Code and subagents. It adds a new tier for tasks where parallel exploration and cross-domain coordination genuinely add value.

My mental model for choosing the right approach:

Single session: most daily development tasks---writing features, fixing bugs, refactoring code
Subagents: focused parallel work where only the result matters---quick research, targeted code review, file-specific analysis
Agent Teams: complex multi-domain work requiring coordination---cross-layer features, adversarial debugging, comprehensive parallel reviews

The progression from single-session workflows to multi-agent collaboration to orchestrated Agent Teams reflects a broader trend in AI-assisted development. We are moving from AI as a tool to AI as a team, and the coordination patterns that make human development teams effective---specialization, clear ownership, structured communication---apply directly.

Key Takeaways

Agent Teams coordinates multiple Claude Code instances with a lead session, shared task list, and inter-agent messaging, enabling genuine parallel development
It differs fundamentally from subagents: teammates are independent sessions that communicate directly with each other, not just report back to a parent
Cross-layer development is the killer use case: separate teammates for backend, frontend, and tests eliminates context switching and keeps each instance focused
Start with research and review tasks before attempting parallel implementation to learn the coordination patterns
Size tasks and define file ownership carefully to avoid coordination overhead and file conflicts
Token costs scale with team size, so reserve Agent Teams for tasks where parallelization genuinely adds value over a focused single session

The feature is still experimental and comes with rough edges, but the core concept---AI instances that collaborate like a development team---is a meaningful step forward. For developers already comfortable with Claude Code in their daily workflow, Agent Teams is worth exploring for the right class of problems.

Claude Code Agent Teams: Parallel AI Development