Battle-tested patterns for Claude Code Agent Teams. Context-rich spawn prompts, right-sized tasks, file ownership, delegate mode, and v2.1.33-v2.1.45 fixes.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Problem: Your Claude Code agent team spins up and immediately starts burning tokens without producing usable output. Teammates overwrite each other's files. The lead rolls up its sleeves instead of coordinating. Tasks sit in "in progress" forever. These are fixable, and the patterns below were forged from community reports and months of real iteration since the feature shipped.
Quick Win: Flip on delegate mode (Shift+Tab) and hand every teammate explicit file boundaries in the spawn prompt. Those two tweaks alone kill the most common team failures.
Note: This is a sibling guide to the Agent Teams overview. Head there first if you have not set up a team yet. For the knobs and dials, see Advanced Controls.
Load task-specific detail into the spawn prompt. Project context (CLAUDE.md, MCP servers, skills) arrives automatically, but the lead's conversation history does not travel with the teammate. Point at specific files, acceptance criteria, and constraints. A tight spawn prompt cuts the back-and-forth dramatically.
A floppy prompt like "review the auth module" makes the teammate hunt through the codebase, figure out what matters, and guess at priorities. That exploration burns tokens and clock time. A specific prompt removes the ambiguity:
The shape is simple: what to do, where to do it, what to focus on, and what the deliverable should look like. Teammates that know their scope upfront finish faster and ship better work. If you are coming from subagent patterns, the rule is identical, but the stakes are higher. Each teammate is now a full context window.
Too small and the coordination tax eats the gain. Too large and teammates grind away with no check-ins, risking lost effort. The sweet spot is a self-contained unit with a clean deliverable: a function, a test file, a review doc.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Aim for 5-6 tasks per teammate. That keeps everyone moving and lets the lead reassign work when someone stalls. If the lead is not slicing work finely enough, tell it to break the pieces smaller. A teammate carrying one giant task has no natural checkpoint. A teammate with 5-6 focused tasks reports in after each one, giving you room to steer.
Two teammates editing the same file means silent overwrites. This is the single biggest rule for implementation work. Split tasks so each teammate owns a distinct set of files. Spell out directory boundaries in the spawn prompt.
If the repo does not split naturally into independent directories, create the split in your decomposition. Rather than "refactor the API layer" across three teammates, assign "refactor the user endpoints in src/api/users/" to one and "refactor the billing endpoints in src/api/billing/" to another. Explicit ownership prevents the silent overwrites that torch entire teammate sessions.
For projects where shared files cannot be avoided, mark them as "coordinate before editing" in your CLAUDE.md and let the lead sequence access through the task list.
Turn delegate mode on (Shift+Tab) the moment a team starts. Without it, the lead sometimes snatches tasks meant for teammates, muddying who owns what. Delegate mode restricts the lead to coordination-only tools, so it stays on orchestration instead of implementation. For the full walkthrough and config options, see the delegate mode guide.
New to agent teams? Begin with tasks that have clean boundaries and no code writing: PR reviews, library research, bug investigation, or module audits against a specific checklist. These show the payoff of parallel exploration without the coordination headaches of parallel implementation.
Research tasks are also forgiving. When a teammate wanders down an unproductive path, you lose tokens, not code. Implementation mistakes are harder to undo, especially once multiple teammates have layered changes on top of each other.
Once team dynamics feel natural, graduate to implementation tasks. Same patterns apply, but the stakes climb and file ownership boundaries matter much more.
Use Ctrl+T to peek at progress and redirect approaches that are not landing. Leaving a team running unattended too long stacks up the wasted-effort risk, especially if one teammate locks onto a dead end.
Treat agent teams like a supervised workflow. You are the project manager. The lead coordinates, but you make the strategic calls: when to redirect, when to spawn a replacement, and when to shut down a stuck teammate. Think of it as managing a distributed crew of contractors. Regular check-ins catch problems before they compound.
In practice, 3-5 teammates is the real sweet spot. More teammates equals more coordination tax, more token spend, and more chances for crossed wires. The lead's context fills faster tracking 8 teammates than 3. Communication cost scales with team size, because every broadcast lands in every teammate's window.
If the task genuinely demands more than 5 parallel workers, break it into phases instead. Run a 3-teammate team for phase one, clean up, then run another 3-teammate team for phase two. Sequential phases with smaller teams produce cleaner results than one giant team wrestling with everything at once.
Plan mode inside agent teams has two important behaviors that are not obvious from the docs.
Plan mode is re-evaluated every turn, not just once. When a teammate runs in plan mode, it stays there for its entire lifetime. Every action it takes is filtered through the read-only constraint. That makes plan mode great for design-only roles and initial task shaping, but bad for execution.
A teammate's mode is fixed at spawn time. Once launched, you cannot flip a teammate from plan to default. If you need a transition from planning to execution, spawn a fresh teammate in default mode and hand off the plan. Do not try to "switch" an existing teammate out of plan mode.
This shapes team design. Use plan-mode teammates for architecture and review roles where a read-only perspective is the whole point. Use default-mode teammates for any role that needs to write code or modify files. For a plan-then-implement flow, reach for the plan approval feature instead. That lets a default-mode teammate plan first and build after approval.
With solid rules in CLAUDE.md, teammates self-report exactly what they did without the lead stepping in. A teammate finishing a cleanup task against a well-written CLAUDE.md returns something like: "Removed 27 console.log across 3 files. Kept all 12 console.error and 2 console.warn in component-page.js. Verified zero console.log remaining in my assigned files."
No lead intervention needed. Clear rules in, clear reports out.
This pattern falls out naturally when your CLAUDE.md lists specific verification criteria. Instead of "clean up logging," the teammate already knows "verified" means running grep for leftover instances and confirming error-level logging survived. For more on shaping CLAUDE.md for teams, see CLAUDE.md mastery and the CLAUDE.md optimization section in Advanced Controls.
Common issues and their fixes, drawn from community reports and release notes:
| Issue | Solution |
|---|---|
| Teammates not appearing | Use Shift+Down to cycle through active teammates. Confirm the task is complex enough for a team. For split-pane mode, verify your tmux or iTerm2 setup. |
| Too many permission prompts | Pre-approve common operations in your permission settings before spawning teammates. Each teammate inherits the lead's permissions, so configuring once covers the whole team. |
| Teammates stopping on errors | Give instructions directly (Shift+Up/Down to select, then type). Or spawn a replacement to continue the work. |
| Lead shuts down before work is done | Tell the lead to keep going. Say "Wait for your teammates to complete their tasks before proceeding." |
| Orphaned tmux sessions | Run tmux ls to list sessions, then tmux kill-session -t <session-name> to clean up. |
| Teammates stepping on each other's files | Define explicit file boundaries in the spawn prompt. Use directory-level ownership. See the "Avoid File Conflicts" section above. |
| Task status looks stuck | Teammates sometimes forget to mark tasks complete. Check manually with Ctrl+T and prompt the teammate to update status. |
| Teammates on Bedrock/Vertex/Foundry fail | Update to v2.1.45+. Earlier versions had trouble with model identifiers and missing API provider environment variables for tmux teammates. |
| Crash when toggling agent teams setting | Update to v2.1.34+. Fixed a crash when the agent teams setting changed between renders. |
| tmux teammates can't send/receive messages | Update to v2.1.33+. Fixed agent teammate sessions in tmux to send and receive messages correctly. |
If your issue is not on this list, check which Claude Code version you are running. Many early pain points were resolved across the v2.1.33 through v2.1.45 releases.
Agent Teams is experimental. These constraints are worth knowing before you commit to a team-based workflow:
/resume or /rewind. After resuming, the lead may try to message teammates that no longer exist. Tell it to spawn replacements.Being straight about these rough edges matters. Agent Teams is a powerful feature with visible seams. Developers who learn the workarounds now are the ones ready when Anthropic sands them down.
Since the initial Agent Teams launch in v2.1.32, Anthropic has shipped several important fixes. If you tried agent teams early and got burned, check whether your issue was resolved:
v2.1.33:
Task(agent_type) spawn restrictions to control which subagent types can be spawnedmemory field for agents with user, project, and local scopesv2.1.34:
v2.1.41:
speed attribute to OTel events for fast mode observabilityv2.1.45:
Hitting issues? Update Claude Code to the latest version. The team ships fixes on a fast cadence and agent teams is under active development.
This guide is the operational playbook. For the rest of the picture: