Running Claude Code Agent Teams Parallel Tasks Safely

Decide which Agent Team tasks can safely run at once in a shared codebase, remove dependencies with stubs, and weigh the token cost.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Parallelizing independent work is the part of running an Agent Team where you decide which tasks can safely run at the same time in one shared codebase, and which must wait. For background on the feature itself, see the Claude Code Agent Teams method page. This page covers the practical call: given a task list, what you release concurrently, what you hold back, and what running it in parallel costs.

The starting point is Anthropic's own positioning. The launch announcement describes agent teams as best for tasks that split into independent, read-heavy work, such as codebase reviews. A practitioner guide reaches the same conclusion from the other side: agent teams excel at read-heavy tasks but struggle with write-heavy tasks where multiple agents modify the same files. That boundary matters because teammates share a working tree. The Claude Code documentation notes that teammates do not receive isolated worktrees, so two sessions editing one file really are editing the same file.

Three decisions make up the skill. First, classify each task as parallel-safe or risky, based on whether it reads or writes, which files it touches, and whether it depends on a decision nobody has made yet. Second, when tasks must interoperate, fix the contract first: agree function signatures or API schemas, commit shared type stubs, and let each teammate build against mocks until integration, as one practitioner guide recommends. Third, weigh the token bill. Each teammate runs its own context window, and Anthropic states that token costs scale linearly with the number of teammates.

The cost question does not settle in your favor by default. A practitioner who ran 52 controlled benchmarks reported Agent Teams costing 73-124% more than sequential execution with zero quality gain, attributing the gap to each agent loading the full codebase context. That is a community report, not an Anthropic evaluation, but it is the most specific cost evidence available, and it argues for parallelizing only when the work is genuinely independent and the wall-clock savings are worth paying for.

Done well, this skill produces a task list where every concurrent task owns distinct files, every dependency is sequenced, and every teammate has enough independent work to justify its context window. Done badly, it produces merge conflicts, rework, and a large token bill for output one session could have produced alone.

How It Works

Parallel safety comes down to two properties of a task: what it writes and what it waits on. Reading is easy to parallelize because readers cannot collide. Writing is safe only when write sets do not overlap, and waiting is safe only when the thing being waited on is sequenced first.

Write sets. Because teammates share one working tree, with no isolated worktrees per teammate, file ownership is your main conflict control. Good boundaries follow non-overlapping file sets, and one guide gives the example of backend API endpoints, frontend components and database migrations going to separate agents. Where possible, split by directory or module, because distinct file ownership reduces merge conflicts. If the repository does not divide that way naturally, create separation through the task decomposition instead of letting two teammates share an area.

Dependencies. A task that needs an interface, schema, migration or architectural decision from another task is not parallel with it. Treat that need as a sequencing constraint and keep the task blocked until the prerequisite is complete, while independent tasks run in parallel. The exception is a dependency you can remove by fixing a contract up front.

Contracts, stubs and mocks. When two tasks must interoperate, the practitioner guidance is to agree on function signatures or API schemas, create shared type or interface stubs, let agents use mocked boundaries initially, and coordinate integration afterward. Committed stubs turn a pending shared decision into a made one, which makes the dependent tasks parallel-safe. Commit them before spawning implementers: a stub that one teammate is still editing is a shared file, not a contract.

Token cost. Each teammate has its own context window and consumes tokens independently, and Anthropic also lists coordination overhead and diminishing returns as drawbacks, so adding teammates does not speed work up proportionally. The practitioner benchmark report traces its cost gap to redundant copies of the full codebase context across agents. Every extra teammate therefore needs enough distinct work to pay for its own context load.

Use this rating when you sort the task list:

A risky task has three fixes: sequence it after its prerequisite, fold it into one teammate's scope so a single session owns all the overlapping files, or resolve the shared decision first and turn it into a stub.

Step-by-Step Guide

Step 1: Map each task's read and write sets

Start from the decomposed task list and write down, for every task, the files and directories it will read and the ones it will change. Be concrete: a path or module name, not a phrase like the API layer. A practitioner guide warns against broad instructions such as refactor the API layer and splits that work into bounded areas like user endpoints and billing endpoints in separate directories. The output is a simple list you can compare pairwise for overlap.

If you cannot name a task's write set, the task is not ready to parallelize.

Pro tip: If you do not yet have a task list, build one first with the decomposing tasks for agent teams skill at https://tryhamster.com/skills/decomposing-tasks-for-agent-teams.

Step 2: Pull out the read-heavy work

Tasks that only read, such as reviewing modules, tracing call paths or auditing tests, are the safest parallel candidates. Anthropic positions agent teams as best for independent, read-heavy work like codebase reviews. Group these first and give each teammate a distinct slice of the codebase to read, so their findings do not duplicate each other. Ask for a structured report as the output, which keeps the lead's synthesis manageable.

Read-heavy tasks still cost tokens, so avoid spawning a reader for a slice small enough to scan in the lead session.

Pro tip: Split review slices by directory so each reader loads a different part of the codebase instead of the whole repository.

Step 3: Flag overlaps and pending decisions

Compare write sets pairwise and mark any pair that touches the same file as risky, since agent teams struggle when multiple agents modify the same files. Next, find tasks that depend on a choice nobody has made yet, such as a schema shape or an auth approach. Parallelizing those creates conflicts or forces rework, because each teammate guesses differently. For every flagged pair, decide whether to sequence it, merge it into one owner, or resolve the decision now.

Record the choice next to the task so the lead enforces it.

Step 4: Commit interface stubs and mocks

Where tasks must interoperate, fix the contract before any implementer starts. Following the practitioner pattern, agree on function signatures or API schemas and create shared type or interface stubs, then let each side build against mocked boundaries. Commit the stubs in the lead session or in a short sequential task, not inside a parallel one. Name the stub files as read-only for every implementer in their task descriptions.

Once the contract exists, the dependent tasks move from risky to parallel-safe.

Pro tip: Keep stubs minimal, for example types and signatures only, so the contract settles quickly and implementers own the real logic.

Step 5: Size the team against token cost

Count how many genuinely independent streams remain after the previous steps and spawn at most that many teammates. Anthropic states that token costs scale linearly with the number of teammates and warns of diminishing returns. A community benchmark report found teams 73-124% more expensive than sequential execution with zero quality gain, though that is practitioner evidence rather than an Anthropic evaluation. If only one or two streams are independent, a single session is often the cheaper choice.

Treat the team size as a decision you justify, not a default.

Pro tip: Before spawning, write one sentence per teammate stating what it will finish that no other teammate could; drop any teammate you cannot justify.

Step 6: Release independent tasks and hold dependents

Start the parallel-safe tasks together and leave every dependent task blocked. The guidance is to treat dependencies as sequencing constraints that stay blocked until the prerequisite is complete. Watch early output for teammates editing outside their write set, which is the first sign of a collision. When a prerequisite lands, release the tasks that were waiting on it.

Leave cross-module integration to a final phase once parallel work finishes.

Pro tip: Check the working tree for files touched by more than one teammate shortly after the first tasks start, while a collision is still cheap to undo.

Best Practices

• Assign each concurrent task a directory or module it alone may change. Distinct ownership is what reduces merge conflicts, and it gives you a quick check: any file outside the list is a scope breach.
• Favor read-heavy work when you first adopt teams. Both Anthropic's announcement and practitioner experience point to reviews and analysis as the strongest fit, so you learn the coordination mechanics where collisions cannot happen.
• Settle shared contracts before parallel implementation. Committed signatures, schemas and type stubs let teammates build against mocked boundaries and integrate afterward, which removes the most common reason two teammates end up in the same file.
• Create separation in the plan when the repository lacks it. If modules are tangled, split the work through decomposition rather than letting two teammates share an area, even if that means one teammate owns a larger slice.
• Justify each teammate against its token cost. Because each teammate consumes tokens independently, a teammate with thin work mostly adds a redundant context load, the effect the benchmark report blames for higher costs.
• Keep dependent tasks explicitly blocked. Releasing them early invites teammates to guess at interfaces, and treating dependencies as sequencing constraints is cheaper than untangling divergent guesses later.

Common Mistakes

• Handing out broad, overlapping instructions such as refactor the API layer to several teammates.: Split the area into bounded pieces in separate directories, as in the user endpoints and billing endpoints example. Each teammate then has a write set you can verify.
• Assuming each teammate works in its own copy of the repository.: Teammates do not receive isolated worktrees, so concurrent edits to one file collide. Partition file ownership explicitly before starting.
• Parallelizing tasks that depend on a decision nobody has made, like the shape of a shared schema.: Make the decision first and commit it as a stub, or sequence the tasks. Parallel guesses about a pending decision create conflicts or rework.
• Spawning as many teammates as possible on the assumption that more agents means faster results.: Anthropic notes diminishing returns and linear token scaling. Spawn only as many teammates as there are independent streams of meaningful size.
• Letting a teammate write the interface stubs while other teammates already build against them.: Commit stubs before implementers start, so the contract is fixed. A stub still in flux is a shared, changing file, which is exactly the same-file write pattern teams struggle with.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Claude Code Agent Teams

Related Skills

• Decomposing Tasks for Agent Teams
• Designing Agent Roles and Scopes
• Coordinating Inter-Agent Communication
• Reviewing and Synthesizing Teammate Outputs
• Choosing Agent Teams Versus Subagents
• Managing Shared Task State

Sources

• Claude Opus 4.6
• Orchestrate teams of Claude Code sessions - Claude Code Docs
• Agent Teams Workflow - claude-code-ultimate-guide - GitHub
• Run agents in parallel - Claude Code Docs
• Claude Code Agent Teams Best Practices & Troubleshooting
• We ran 52 controlled benchmarks on Claude Code. Agent Teams cost 73-124% more than sequential with zero quality gain.
• How to Orchestrate Multi-Agent Workflows in Claude Code | Fastio
• Claude Code Agent Teams: Advanced Multi-Agent Workflows

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.