Split big Claude Code jobs across scouts, planners, worktree implementers and reviewers, with a config pack you can drop in.
This guide is for people who already use subagents now and then and want a repeatable way to run several of them on one job without losing control of context, cost or the git tree. By the end you will have a team of six agents, a skill that runs them in a fixed order, and a clear rule for when to reach for something bigger.
What you will have at the end
A decision map that tells you, in under a minute, whether a job needs one session, subagents, an agent team or a dynamic workflow.
Six project subagents (scout, planner, implementer, reviewer, verifier, test-runner) with tool, model and isolation boundaries that match their jobs.
An /orchestrate skill that runs scout, plan, implement, review and verify in order, with a stop for your approval after the plan.
Settings for spawn depth, cache lifetime and worktree base, plus a hook that logs every finished subagent.
A short list of the failure modes that waste the most tokens, and how to avoid them.
Before you start
Claude Code 2.1.296 or newer. Several fields used here have version floors: autoCompactWindow needs v2.1.296 or later, and fork mode has been on by default since v2.1.302. Run claude --version to check. At the time of writing the changelog lists 2.1.318 as the newest release.
A git repository. Worktree isolation requires git.
jq on your PATH for the logging hook.
You have read our free guide on subagents, or you know what a subagent file looks like.
Step 1: pick the right parallel tool before you build anything
Most multi-agent setups fail at the first decision: they use a heavier tool than the job needs. Claude Code currently gives you five ways to work on several tasks at once: subagents, agent view, agent teams, dynamic workflows and projects. They differ in one main thing, which is who holds the plan.
Here is the map we use. Read it top to bottom and stop at the first row that fits.
If the job looks like this
Use
Why
One change, a few files, lots of back and forth
The main session
No handoff cost, full context
A side task that would flood your context (search, logs, test output)
One subagent
It works in its own window and returns a summary
Several independent investigations or edits you want inside one conversation
Several subagents, in parallel
Claude delegates and collects results
Separate tasks you want to hand off and check on later
Agent view (claude agents)
Each task is its own background session
Workers that must talk to each other and share a task list
An agent team
Teammates message each other directly
Dozens to hundreds of agents, or results that must be cross-checked
A dynamic workflow
A script holds the loop, not Claude's context
The docs put the difference between the last two rows clearly: with subagents, skills and agent teams, Claude decides turn by turn what runs next, while in a workflow "the script" decides. That is the line to watch. As long as Claude can keep the plan in its head, subagents are cheaper and easier to steer.
Three facts from the docs shape the rest of this playbook:
Each subagent runs in its own context window with its own prompt, tools and permissions, and its requests count toward the same usage limits as your main conversation. Parallel work is not free work.
Subagents report back to the caller. Teammates in an agent team talk to each other. If your workers do not need to talk, you do not need a team.
When tasks touch the same files, isolate them with worktrees. Agent teams do not put teammates in worktrees, so there you must split file ownership yourself.
Try this now, before installing anything. Pick a real task from your backlog and write one line under each heading: what files it touches, whether the parts depend on each other, and whether the workers need to talk. If the answers are "few", "yes" and "no", stay in one session. If they are "many", "no" and "no", you want parallel subagents, and the rest of this guide is for you.
A quick test you can run in any repo right away, with no setup:
Research the authentication, database, and API modules in parallel using separate subagents
That prompt comes straight from the subagents page. Watch the subagent panel below the prompt input while it runs, then look at how short the final answer is compared with what each subagent read. That gap is the context you just saved.