Claude Code Multi-Agent Patterns

Quick Answer

Multi-agent in Claude Code means spawning subagents with the Agent tool. Each subagent runs in isolated context, so the main session stays clean. You pick the model per subagent, optionally drop it in a fresh git worktree, and dispatch several at once. TLDR: use subagents for anything you would otherwise copy-paste across five sessions, and use worktrees when a subagent needs to modify files without fighting the main session.

Summary of the 6 key patterns

1. Single subagent for a self-contained task
2. Parallel dispatch of 3 or more independent subagents
3. Orchestrator and worker pattern for structured workflows
4. Worktree isolation via the Agent tool isolation parameter
5. SendMessage continuation for long-running named agents
6. Implementer plus spec reviewer plus code reviewer trio

What a subagent actually is

A subagent is a fresh Claude Code instance spawned by the main session. It has its own context window, its own tool budget, and its own model selection. The main session passes a prompt and optional configuration, waits for the subagent to finish, and then consumes the result as a single message.

The benefit is context isolation. Your main session might have 60k tokens of history about a failed migration and a flaky test. You do not want that noise bleeding into a one-shot task like running pnpm lint --fix on a fresh branch. Dispatching that work to a subagent means the subagent sees only the prompt you give it.

The Agent tool parameters

The Agent tool accepts a small set of parameters. description is a one-line summary shown in logs. prompt is the actual instruction the subagent receives. subagent_type picks a preset like general-purpose or a custom type configured in settings. isolation controls workspace sharing: omit for shared filesystem, set to worktree to create a clean git worktree, or sandbox for an ephemeral copy. model overrides the default model for that subagent only.

Each parameter has a sensible default. The 4 you will touch most often are prompt, subagent_type, isolation, and model. The description field matters mostly for observability and cost reports.

Worktree isolation

Git worktrees let you check out a second branch of the same repo into a different folder. Claude Code wraps this with the isolation: worktree option. When you set it, the subagent starts in a fresh worktree on a new branch, runs its task, and the main session sees the results as a diff you can merge.

This matters for 2 reasons. First, the subagent cannot accidentally corrupt your current working tree. Second, two subagents can operate on the same repo in parallel without stepping on each other. Without worktrees, a parallel pair might both edit the same file and produce merge conflicts inside a single session.

A concrete example: dispatching 3 subagents, one to update dependencies, one to refactor a module, one to add a new feature, each in its own worktree. They run in parallel. When each finishes, you review the branch and merge the clean ones.

The SendMessage pattern

Subagents can be named and re-addressed with the SendMessage tool. The first Agent call spawns the subagent and returns a handle. Subsequent SendMessage calls continue the same subagent with new instructions. This is useful when the work is long-lived: a research subagent that you feed new queries as you go, or a test-running subagent that you ping with follow-ups.

The naming pattern is simple. You pick a name when you dispatch, and you pass that same name to SendMessage to continue. The subagent keeps its context, so you do not resend the setup. This saves tokens on repeated work.

Parallel vs sequential

Parallel dispatch is the default when you call the Agent tool multiple times in one assistant turn. All 3 subagents start at roughly the same time and run concurrently. The main session blocks until all of them return.

Sequential dispatch is what you get when each Agent call depends on the result of the previous one. The main session starts subagent A, waits for it to finish, inspects the result, and then starts subagent B. This is slower but necessary when B needs information from A.

A rough rule: if the tasks are independent, dispatch 3 to 5 in parallel. If the tasks form a pipeline, go sequential and plan for roughly 2x the single-agent runtime.

Orchestrator and worker pattern

The orchestrator is the main session. It plans the work, breaks it into independent tasks, dispatches workers (subagents) to handle each task, and integrates their outputs. Workers do the actual file editing, test running, and command execution.

A good orchestrator prompt looks like this. Describe the end goal. List the 3 to 5 subtasks. For each subtask, specify the inputs, the expected output format, and the success criteria. The orchestrator then dispatches and checks each result against the criteria before moving on.

The pattern shines on tasks that decompose cleanly. Building a feature with a UI change, an API change, a DB migration, and tests. Auditing a codebase for 5 different issues in parallel. Running 4 benchmark variations at once.

Context construction for subagents

The most common mistake with subagents is passing too much context. The main session has 40k tokens of history. You copy half of it into the subagent prompt because it feels relevant. The subagent spends the first 30 seconds sorting through your history instead of doing the task, and by the time it identifies the actual goal it has already spent 2000 tokens of its input budget on irrelevant background. A better approach is a tight brief: name the task, name the files or paths the subagent will touch, reference any rules in CLAUDE.md that apply, reference any project docs that matter, and stop there. If the subagent needs more, it can read files on demand via its own Read tool. A tight brief typically runs 200 to 500 words. The subagent starts faster, spends less on input tokens, and produces more focused output than a subagent drowning in copy-pasted history.

Model selection per subagent

Different subagents deserve different models. A mechanical task like rewriting imports or renaming variables runs fine on Haiku at about one third of the cost. An architecture decision or a tricky debug session wants Opus. Most day-to-day work sits on Sonnet.

A common setup: main session on Sonnet, implementer subagents on Sonnet, test-running subagent on Haiku, architecture reviewer subagent on Opus. The mix keeps total spend roughly 20 to 30 percent lower than running everything on Sonnet, with no loss in final quality.

When to use subagents vs stay in one session

Use a subagent when the task is self-contained and you do not want its context polluting the main session. Use a subagent when the task benefits from a different model. Use a subagent when you want to run several things in parallel.

Stay in the main session when you need the agent to keep track of ongoing context across multiple steps. Stay when the task is short enough that spawning overhead would dominate. Stay when you want to watch every step rather than consume a final report.

A useful cutoff: if the task will take fewer than 3 tool calls, stay in session. If it will take more than 5 and is mostly independent from your current work, dispatch a subagent.

Subagent-driven development

One high-value pattern is implementer plus spec reviewer plus code quality reviewer. You write a short spec in markdown. You dispatch an implementer subagent with the spec and the relevant files. You then dispatch a spec reviewer subagent to check that the implementation meets the spec, and a code quality reviewer to check for smells and standards violations.

The 3 reviewers run on different models tuned for their role. The spec reviewer is strict and short-context. The code quality reviewer is thorough and opinionated. The implementer is pragmatic.

The output is 3 critiques the main session integrates into a final diff. This adds about 40 percent to single-agent cost but cuts the rework rate roughly in half for features over 200 lines of code.

Real example: building a feature

Here is a concrete 3-subagent workflow for adding a new settings page.

Step 1. The main session reads the spec and creates a work plan. It identifies 3 independent tasks: UI component, API endpoint, and database migration.

Step 2. The main session dispatches 3 subagents in parallel, each in its own worktree. The UI subagent runs on Sonnet with isolation worktree. The API subagent also runs on Sonnet in a separate worktree. The migration subagent runs on Haiku because the task is mechanical.

Step 3. The subagents finish. The main session reviews each branch, pulls them together into a single integration branch, and runs the full test suite. Total wall time: roughly 8 minutes instead of 20. Total cost: roughly 15 percent less than a single-session equivalent because the Haiku migration work is cheap.

Limits and caveats

Subagents are not free.

Each one pays a startup cost of roughly 1000 input tokens for the system prompt and tool schemas. Dispatching 10 subagents for trivial tasks burns more than doing the work in session. Each one pays a startup cost of roughly 1000 input tokens for the system prompt and tool schemas. Dispatching 10 subagents for trivial tasks burns more than doing the work in session.

Subagents also do not share state. If subagent A edits a file in the shared workspace, subagent B running concurrently will see the change mid-flight and get confused. Worktree isolation prevents this, but only if you remember to enable it.

Finally, debugging a bad subagent is harder than debugging the main session. You see the final output but not every intermediate step. For unfamiliar tasks, run in-session first and only factor out to a subagent when you understand the shape of the work.