Master Agent Teams in Opus 4.6: A Developer’s Playbook
TL;DR
- Agent teams let you run multiple Claude Code agents in parallel, each with a distinct role.
- The main agent creates a shared task list, automatically assigns tasks, and shuts down teammates when done.
- Enabling agent teams is a single line in settings.json and a few keyboard shortcuts.
- You can specify a different model per teammate and lock the lead in delegation mode (Shift+Tab).
- Troubleshooting tips cover subagent limits, token overhead, and shutdown quirks.
Table of Contents
Why this matters
When I first dove into Opus 4.6, the promise of agent teams felt like a game-changer, but the pain points were real. Sub-agents ran in the background and could only report back to the main agent, so I was stuck with one-way feedback loops and a lack of coordination. Each agent kept its own context window, which meant I had to keep flipping between windows just to read results. Manual shutdown was a chore, and switching models for each teammate added a configuration headache. These friction points broke the flow of complex projects.
Agent teams solve all of that. They let you spawn five specialized agents—UX/UI designer, back-end developer, technical architect, database expert, devil’s advocate—each in its own Claude Code instance. The main agent becomes the team lead, automatically creates a task list, assigns work, and can switch between teammates via the chat interface. Peer-to-peer messaging is a built-in feature, so teammates can talk to each other directly without routing through the lead. The lead also automatically shuts down every teammate when the job is finished, freeing you from manual cleanup. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Core concepts
Think of an agent team as a micro-software company. The main agent is the CEO who writes the executive plan and tracks progress. The five specialists are the engineers who get their work done in isolated sandbox environments—this isolation gives each agent a clean context and keeps their models from bleeding into one another. The shared task list is the project board that every member can see and update. When a task is assigned, the lead spawns the appropriate specialist, who then runs in its own context window and reports only to the lead. The UI designer can be interrupted with escape without affecting the others, and the devil’s advocate throws counter-arguments that force the team to refine the plan. These mental models map directly onto how human teams operate, making the agent flow intuitive.
How to apply it
Enable agent teams Edit settings.json and add the property:
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Create a team In Claude Code, type a natural-language request such as: “Create an agent team to build a fitness tracker app called Claude Fit with a UX designer, a back-end developer, a technical architect, a database expert, and a devil’s advocate.” The main agent will spawn the five specialists automatically. Claude Code Swarms — Agent Teams (2026)
Specify models per teammate The team prompt can include model hints, e.g., “Use Sonnet for the back-end dev, and Haiku for the database expert.” Each agent runs in its own instance, so you pay per-agent token usage. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Use delegation mode Press Shift+Tab to lock the main agent into coordination-only mode, preventing accidental code writes. Shift+Arrow keys cycle between teammates. Claude Code Docs — Keybindings (2026)
Manage tasks The task list lives in the right-hand panel. You can add, assign, and track status. When a teammate completes a task, it updates the list automatically. The lead can request plan approval before making changes, which helps guard against accidental destructive edits. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Shutdown On completion, the main agent automatically shuts down all teammates. If the lead stalls, use /shutdown in the main chat. Manual shutdown is rarely needed, but it’s available for edge cases. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Pitfalls & edge cases
| Parameter | Use Case | Limitation |
|---|---|---|
| Subagents | Quick, focused tasks that report to main agent | No intercommunication, one-way reporting |
| Agent Teams | Complex, parallel work with peer-to-peer messaging | Higher token cost, coordination overhead |
| Main Agent | Team lead, creates task list, manages shutdown | Must be carefully monitored, single point of failure |
- Sub-agents still exist for one-off jobs. They can’t talk to each other, so use them when you only need a single tool-heavy routine.
- Token overhead grows linearly with the number of agents; keep an eye on your quota when you spin up large teams.
- Manual shutdown is rarely required, but if the lead becomes unresponsive, you’ll have to intervene.
- Model changes after initialization aren’t possible; you’ll have to recreate the team if you need a different model.
- Keyboard shortcuts may clash with your terminal; tweak the keybinding file if necessary.
Quick FAQ
Q: How does the system handle conflicting changes from sub-agents?
A: Sub-agents never talk to each other, so conflicts are isolated to the main agent. The lead resolves any overlaps in the shared task list. Claude Code Docs — Create custom subagents (2026)
Q: What exact format is required for the settings.json property?
A: Add an “env” block with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to “1”. The property is a simple key-value pair, no extra formatting. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Q: When does the team lead shut down agents automatically?
A: When the shared task list is empty and the lead’s “done” flag is set, the lead triggers a shutdown of all teammates. Manual shutdown is only needed if the lead stalls. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Q: Can I change the model for a teammate after the team is created?
A: No. Each agent starts with the model specified at spawn time. To change a model, you must recreate the team or manually shut down the team and spawn a new one with the desired models. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Q: How is peer-to-peer messaging routed between agents?
A: The underlying message broker routes messages directly between the agents’ instances via the shared task list infrastructure, bypassing the main agent unless the message is a task assignment or a status update. Claude Code Docs — Orchestrate teams of Claude Code sessions (2026)
Conclusion
Agent teams in Opus 4.6 and Cloud Code bring a level of orchestration that feels like a full-stack engineering team inside a single terminal. If you’re tackling a complex, multi-layer project—think authentication, analytics, or a new feature that spans UI, backend, and database—agent teams will save you time and reduce context switching. On the flip side, if you’re writing a small script or a quick prototype, the overhead of five separate instances may be overkill. Give agent teams a try on a non-critical project first, then scale up as you see the benefits.
Happy coding, and let the agents do the heavy lifting!
