Agent teams: working in parallel

Module: 8. An army of agents | Time: about 30 min theory + 45 min practice

The gist

A subagent is a freelancer: gets an assignment, does it, hands it in, leaves. An agent team is a department: everyone works at the same time, talks to each other, sees the shared goal and can hand work off to a colleague. It's not just faster. It's a different level of complexity in the tasks you can take on.

Key concepts

• The key difference between a team and subagents: team members talk to each other directly (the SendMessage tool)
• Status: agent teams are an experimental feature, off by default, turned on with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 variable
• An example team for building a landing page: Frontend + Backend + QA in parallel
• Permission inheritance: the team gets the permissions of the main session
• 4 pitfalls of teamwork and how to avoid them
• When to use teams and when to use subagents

Theory

Subagents vs teams: the key difference

🎨 Picture this: a subagent is a freelancer: took the job, did it, handed it in, left. An agent team is a construction crew on site: the electrician, the plumber and the finisher work at the same time, talk to each other and don't wait their turn.

Subagents (lesson Subagents):

• Work independently of each other
• Usually don't know about other subagents (named subagents can message each other, but that's more the exception)
• Mostly communicate with the main agent (up/down)
• Got the assignment → did it → returned the result → done

Teams:

• Know who their teammates are
• Can send messages to each other (the SendMessage tool)
• See a shared task list
• Can delegate tasks within the team
• Work in parallel and coordinate on their own

Subagents:
Main agent
    ↕           ↕           ↕
Agent A      Agent B     Agent C
(isolated from each other)

Team:
Main agent
    ↕
Agent A ←→ Agent B ←→ Agent C
(talk directly)

A live example: a team for building a landing page

🎨 Picture this: an agent team is like a restaurant kitchen working in parallel. The chef makes the sauce, the grill cook sears the meat, the pastry chef makes dessert, all at the same time. A single cook would do it one after another and take three times as long.

The task: build a landing page for a new product in one day.

Without a team (sequential):

1. Frontend Dev builds the UI → 4 hours
2. Backend Dev builds the API → 3 hours
3. QA tests → 2 hours
Total: 9 hours

With a team (parallel):

In parallel:
├── Frontend Dev: builds the UI components → 4 hours
├── Backend Dev: writes the API endpoints → 3 hours
└── QA: prepares test cases, tests finished parts as they come in → 2 hours

QA finds a bug → messages Frontend Dev → Frontend Dev fixes it
without waiting for the whole process to finish

Total: ~4.5 hours (including communication)

Almost twice as fast, with the same quality.

How to create a team

First, turn the feature on. Agent teams are experimental and off by default. Add this to settings.json:

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

Without this variable, Claude doesn't create or suggest teams. It only works in an interactive session (not in -p mode). The feature is experimental, so behavior and limitations may change: see the documentation.

A simple team is created with a single prompt:

Create a team of 3 agents to build a landing page:
- Agent 1 (Frontend Dev): builds React components, works with CSS/Tailwind
- Agent 2 (Backend Dev): writes FastAPI endpoints, works with PostgreSQL
- Agent 3 (QA): tests functionality, uses Playwright for automated tests

Use Sonnet for each member.
The agents can talk to each other directly.

A member's model is chosen in this order: first the one named in your prompt, then the model from the subagent definition, then CLAUDE_CODE_SUBAGENT_MODEL, then the leader's model. The model and fast mode are locked in at the moment the member is created.

Claude Code will create the team and hand each member:

What each agent gets:

1. A description of its role and task
2. A list of teammates (names + what they do)
3. The project's shared task list
4. Step-by-step instructions for its part
5. Access to SendMessage for communication

The leader's conversation history does not carry over to the members: they load the project's CLAUDE.md, MCP servers and skills and receive only the assignment from the leader. So put everything they need into the assignment.

How agents communicate: SendMessage

An example conversation inside a team:

QA Agent → Frontend Dev:
"Found a bug: the Submit button on the order form registers two clicks when pressed quickly.
This creates duplicate orders in the database. Priority: high.
Test case: test_double_click_submit.py in the tests/ folder"

Frontend Dev → QA Agent:
"Got it. Adding a debounce to the Submit button. The fix will be ready in 15 minutes.
You can rerun the test case after commit #a3f2c."

QA Agent → Backend Dev:
"Need help testing the POST /orders endpoint.
How do I reproduce idempotency with duplicate requests?"

The main agent doesn't manage every message: the team coordinates on its own. It sees the big picture and steps in only when needed.

Permission inheritance

🎨 Picture this: team permissions are like an office access badge. If you have a pass to every floor, your staff can go everywhere too while they're working with you. Be careful: bad instructions + full access = something can get broken.

Team members start with the leader's permission mode (except dontAsk mode, which they don't inherit). Permission requests from members pop up in the leader's session, and you approve them there:

• Members pick up MCP servers and skills from the project and user settings, just like a normal session
• If bash commands are allowed → members can run bash
• If file editing is allowed → members can edit
• If the leader was started with --dangerously-skip-permissions, all members run that way too

This is convenient: you don't have to configure each agent separately. But understand this: if an agent gets wrong instructions, it has full rights to break something.

Important: before starting a team, make sure permissions are set up correctly. Don't give the team permissions it doesn't need.

4 pitfalls of teamwork

Pitfall 1: Agents asking for permission

The situation: the team is created and starts working, and every 2 minutes an agent asks "May I run a bash command?"

The fix: pre-authorize the operations you need before starting the team: add them to the allowed list through /permissions or in settings.json (see the lesson Permissions and security).

A prompt alone doesn't grant permissions: the phrase "don't ask for confirmation" doesn't cancel permission requests. A prompt can describe the boundaries of the work ("work only in the /src folder, commit to your own branch"), but the permissions themselves are set in the settings.

Pitfall 2: Conflicts when writing files

🎨 Picture this: two builders in one room with one can of paint will paint the same spot twice and mix the colors. The fix: separate areas of responsibility, separate files.

The situation: Frontend Dev and Backend Dev edit config.json at the same time → one overwrites the other's changes.

The fix: use temporary files with unique names:

Frontend Dev writes to: frontend-config-temp.json
Backend Dev writes to:  backend-config-temp.json
The main agent merges them into: config.json

Or spell out areas of responsibility in the prompt: "Frontend works only in /src/components/, Backend only in /api/, and they don't touch each other's files without explicit permission."

Pitfall 3: Confusion over access rights

The situation: QA Agent tries to use a tool that wasn't allowed → error → the agent is "stuck."

The fix: while you're learning, give full permissions and watch what gets used. Then restrict based on actual use. Don't try to guess permissions in advance: it's not productive.

Pitfall 4: A team for sequential tasks

The situation: you created a team of 3 agents for tasks that have to happen strictly one after another (agent B can't start until agent A finishes).

The result: agents B and C sit and wait, and there's no parallelism. The team spent twice the resources with no gain in speed.

The fix: for sequential tasks, use subagents, not a team. A team only pays off when the tasks are parallel.

A practical example: a team for market research

The task: research the online learning market to launch a new course

Create a team of 3 agents for market research:

Agent 1 (Industry Analyst):
- Analyzes the size of the English-language online education market in the US
- Studies trends over the last 2 years
- Finds growing niches

Agent 2 (Competitor Researcher):
- Researches the top 10 courses in the chosen niche
- Analyzes prices, formats, reviews
- Finds unmet needs

Agent 3 (Audience Researcher):
- Studies the target audience (forums, Reddit, Discord, Facebook groups)
- Identifies pain points and desires
- Finds where the audience spends its time

Use Sonnet for each member.
When done, each agent shares its results with the others.
Agent 1 coordinates the final report based on all the data.

While the Industry Analyst studies trends, the Competitor Researcher is already researching competitors and the Audience Researcher is reading forums. It all runs in parallel, so the research finishes noticeably faster than doing it sequentially (at the cost of more tokens: each member is a separate Claude session).

🎨 Picture this: Orchestrator-Worker is like a site foreman. The foreman doesn't lay bricks himself: he hands out tasks, tracks progress and collects results. The workers don't know about each other, only about their own sections.

Agent communication patterns

The most common pattern to start with: Orchestrator-Worker. One coordinator agent manages 3-5 worker agents (the documentation recommends starting with 3-5 members and not bloating the team: three focused members often work better than five scattered ones). Simple, predictable, effective.

When to use teams vs subagents

Use a team when:

• Tasks are parallel and independent of each other
• Agents need to communicate while they work
• The task is big enough to justify the coordination overhead and token spend (a team costs significantly more than a single session)
• Different parts of the task need different specializations

Use subagents when:

• Tasks are sequential (one depends on another)
• You need simple delegation without communication
• Tasks are short (under 10 minutes each)
• You just need to isolate context

Use neither when:

• The task takes less than 5 minutes
• No specialization is needed
• The task needs the full context of the current session

Practice

Assignment: Create a team of 3 agents to research a market

1. Pick a niche you want to research (for example: SaaS for small businesses, online courses on investing, fitness apps)
2. Create a team of 3 agents:
   • Industry Analyst: general market trends
   • Competitor Researcher: top 5 competitors with prices and reviews
   • Audience Researcher: pain points and desires of the target audience
3. Give the team a task: research the chosen niche
4. Watch the agents in the panel below the input box: the up and down arrows pick a member, Enter opens its conversation, Ctrl+T shows the task list
5. Evaluate the result: how is it different from a sequential approach (in quality and time)?
6. Bonus: add a fourth agent, "Report Writer," that puts together the final report based on data from the other three

Tools and resources

• SendMessage: the built-in tool for communication inside a team
• Display modes: in-process (the default, works in any terminal) and split panes (each member in its own pane, requires tmux or iTerm2); switched with the teammateMode setting
• Hooks for teams: TeammateIdle, TaskCreated, TaskCompleted (exit code 2 sends feedback back)
• Agent teams documentation: the official guide and list of limitations
• Subagents documentation
• /permissions: managing permissions before you start a team
• Git branches / worktrees: for working on code in parallel without conflicts

Key takeaways

The key difference between a team and subagents: team agents TALK to each other. QA finds a bug → tells Frontend Dev directly, without a middleman.

A team for parallel tasks can speed up the work noticeably. A team for sequential tasks = double the cost with no benefit. Know when to use it.

Pre-authorize tools before you start, or agents will keep asking for permission and break your working rhythm.

Related lessons

• ← Subagents: subagents work in isolation, teams add communication
• → Git and worktrees: worktrees let agents work on code in parallel without conflicts
• ← MCP in depth: team members load MCP servers from the project and user settings

What's next

→ Browser automation: Playwright and QA