Module 3: Subagents & Agent Teams

Create Your First Subagent

A subagent is a specialised AI assistant that handles one specific kind of task, in its own context, and hands back only the result.

Each subagent runs with its own context window, a custom system prompt, and specific access to tools and permissions.

When Claude Code encounters a task that matches a subagent's description, it automatically delegates to that subagent.

Why Use a Subagent

According to Anthropic, subagents help you:

• Preserve context: keep exploration and implementation out of your main conversation.
• Enforce constraints: limit which tools a subagent can use.
• Reuse configurations across projects with user-level subagents.
• Specialise behaviour with focused system prompts for specific domains.
• Control costs: route tasks to faster, cheaper models like Haiku.

Define a custom subagent when you spawn the same kind of worker with the same instructions again and again.

Built-In Subagents

Claude Code ships with subagents already built in, so you do not have to define everything yourself.

Explore is a fast, read-only agent that searches and analyses a codebase. Use it when you must search or understand a codebase without a change to any file. It keeps those results out of your main conversation.

Claude Code also includes Plan and general-purpose, alongside any custom subagents you define. You can restrict or disable the built-in ones if you prefer that Claude reads and explores files directly.

Create Your First Subagent

Subagents are Markdown files with YAML frontmatter. Put them in .claude/agents/ for one project, or in ~/.claude/agents/ for every project on your machine.

You do not have to write one by hand. Describe what you want, and Claude writes the file for you.

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude writes the file with a name, a description, a tools list, a model, and a system prompt:

---
name: code-improver
description: Scans files and suggests improvements for readability,
performance, and best practices
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Open the file. Confirm that the frontmatter matches what you asked for. Then try it out:

Use the code-improver agent to suggest improvements in this project

Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions. In the transcript, the delegation appears as a tool call row: code-improver (Suggest code improvements).

You now have a subagent you can use in any project on your machine.

Restrict What a Subagent Can Do

The tools field acts as an allowlist.

A subagent may only need to read and search, and must never edit files. You can scope it down to exactly that:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

This subagent cannot edit files, write files, or use any MCP tools, no matter what its system prompt says.

Define a Subagent for One Session Only

File-based subagents persist on disk, and you get them every time you start Claude Code in that project.

When you only need a subagent for a script or a one-off automation run, define it inline at launch instead. Use the --agents flag:

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"
  }
}'

This subagent exists only for that session, and Claude Code does not save it to disk.

Use it to test a definition before you commit that definition to a file. Use it also for automation scripts that need a subagent and leave nothing behind.

Orchestration Patterns: Single vs. Multi-Agent vs. Pipelines

A split of work across agents is not one technique. It is a choice between several.

The right one depends on three things:

• Who coordinates the work.
• Whether the workers need to talk to each other.
• Whether they touch the same files.

Anthropic lays out four approaches side by side. Each one parallelizes work in a different way:

You already built a subagent in the last lesson.

The other three approaches all run whole Claude Code sessions in parallel, not just delegated workers.

Try It: Dispatch a Session with Agent View

Agent view is the middle ground between a subagent and a full agent team. You hand off a task and check back later, and you set up no coordination between multiple sessions.

Go through the core loop that Anthropic suggests.

Open agent view from your shell:

claude agents

Type a prompt that describes a task. Then press Enter.

A new background session starts on that task. It appears as a row that shows whether the session works, waits on you, or is done:

Needs input
* api client retries    Should the API client retry on 429, or surface the error to the caller?   12m

Working
* dark mode toggle      Editing src/components/Settings.tsx   3m

Completed
* flaky checkout test   github.com/acme/web-app/pull/142   40m

Select a row with the arrow keys. Then press Space to open the peek panel.

The panel shows the session's most recent output, or the question it waits on, rather than the full transcript.

Type a reply. Press Enter to send it, and you stay in agent view.

Press Enter or the right arrow on a row to attach and enter the full conversation. Press the left arrow on an empty prompt to detach and return to the table.

The session you dispatch continues after you close agent view. You can dispatch a task, close your laptop, and come back later to a finished result.

You do not have to start in agent view to use it.

Suppose you are already mid-conversation in a regular session, and you realise the session must continue in the background. Send it to agent view instead of a restart:

/bg

The session moves into agent view and appears as a row alongside anything you dispatched directly.

Building an Agent Team: Orchestrator + Specialised Subagents

A single agent that works alone hits a ceiling on some tasks. There are too many independent angles to explore, and too much ground to cover one turn at a time.

The general fix is an orchestrator pattern: one coordinator splits the work, assigns it to specialized workers, and pulls the results back together.

Claude Code implements this as agent teams.

One session acts as the team lead. It coordinates work, assigns tasks, and synthesises results.

Teammates work independently, each in its own context window. They communicate directly with each other.

When an Agent Team Earns Its Place

Agent teams add coordination overhead and cost more than a single session. They repay that cost on tasks where parallel exploration adds real value:

• Research and review: multiple teammates can investigate different aspects of a problem at the same time, then share and challenge each other's findings.
• New modules or features: teammates can each own a separate piece, and they do not step on each other.
• Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster.
• Cross-layer coordination: changes that span frontend, backend, and tests, with a different teammate for each layer.

For sequential tasks, same-file edits, or work with many dependencies, a single session or the subagent you built earlier is more effective.

Agent Teams vs. Subagents

At the core of it, the difference comes down to communication and cost:

Enable Agent Teams

Agent teams are experimental, and they are off by default. To turn them on, set an environment variable in your settings.json:

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

Build Your First Agent Team

After you enable them, describe the task and the teammates you want in natural language. Claude spawns them and coordinates work from your prompt.

The source's own example works well, because the three roles are independent and do not wait on each other:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different
angles: one on UX, one on technical architecture, one playing devil's
advocate.

From there, Claude populates a shared task list and spawns a teammate for each perspective. Each teammate explores the problem, and Claude synthesizes the findings once they are done.

The lead's terminal lists teammates below the prompt input.

Use the up and down arrows to select a teammate. Press Enter to open its transcript and message it directly, or Escape to interrupt its current turn.

Avoid File Collisions

Subagents and sessions you run yourself can each use a separate git worktree. A worktree is a separate checkout with its own files and branch, so parallel edits never collide.

Start a session in a worktree directly:

claude --worktree feature-auth

Agent teams do not isolate teammates that way by default. Partition the work so that each teammate owns a different set of files.

The Claude Code Docs' Run parallel sessions with worktrees page frames it that way for any parallel session.

Reuse a Subagent as a Teammate Role

The subagent you defined earlier is not just for delegation inside one session.

Reference it by name when you spawn a teammate. The teammate then uses its tools and model, and the definition's body becomes additional instructions:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Define a role once, and reuse it both as a delegated subagent and as a teammate on a team.

Shut Down Teammates

To end a teammate's session gracefully, refer to it by name:

Ask the researcher teammate to shut down

The lead sends a shutdown request. The teammate can approve the request and exit gracefully, or reject it with an explanation.

Second-Opinion Review with a Fresh-Context Subagent

Before you treat a task as done, have a subagent review the diff in a fresh context. Tell it to report gaps.

Run the Bundled /code-review Skill

For a correctness check, run /code-review in any Claude Code session.

The skill reviews the current diff for bugs in a fresh subagent. It returns findings to the session, and you never leave your terminal.

Write Your Own Review Prompt

To check a diff against your plan instead of a general correctness pass, write the review prompt yourself. Name the work to check, the plan to check it against, and what counts as a finding:

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style
preferences.

Why You Must Have An Independent Code Reviewer

• A reviewer in a fresh context sees only the diff and your criteria, not the reasoning behind the change. It judges the result on its own terms.
• The same multi-agent pattern powers the GitHub-integrated /code-review: several agents each check for a different issue class, then a verification step filters false positives.
• The reviewer is a subagent, so the session that implements the change gets the gaps directly. That session can fix and re-review, and you never copy findings between windows.
• On longer autonomous runs, an agent team can continue this review loop while you spot-check the results.
• A reviewer that you ask to find gaps will usually find some, even when the work is sound. Tell it to flag only correctness or requirement gaps, not style. If you do not, you over-engineer the work to satisfy it.

You now have a full toolkit that takes you past a single agent alone. Delegate a side task, hand off independent work, and coordinate a team on a shared goal.

Then get an honest second opinion before you call anything done.