Claude Code Agent Teams: Parallel Multi-Agent Orchestration
By Tyler Cyert
Claude Code agent teams let you coordinate multiple Claude Code sessions working in parallel on the same codebase. One session acts as the team lead, assigning tasks and synthesizing results. The others are specialist agents defined in your .claude/agents/ directory.
Agent teams are the most powerful multi-agent feature in Claude Code. While subagents handle quick parallel tasks within a single session, agent teams coordinate sustained parallel work across multiple sessions — each with its own role, tools, and context.
How Agent Teams Work
- You define agent roles in
.claude/agents/— one markdown file per specialist - You enable agent teams via a setting in your settings.json
- The lead session spawns teammates based on the task at hand
- Teammates work in parallel with their own context and tools
- Results synchronize back to the lead for review and integration
The key difference from subagents: teammates can coordinate with each other through a shared task system. They are not just reporting back to a single parent — they are collaborating.
Defining Agent Roles
Each agent is a markdown file in .claude/agents/:
An agent definition includes a name, description, what the agent should focus on, which tools it uses, what directories it reads from and writes to, and rules about what it should avoid. For example, a code-reviewer.md agent might focus on security analysis, only use Read, Glob, and Grep tools, read from src/, and never modify files.
A test-writer.md agent might focus on writing comprehensive tests, use Read, Edit, Write, and Bash tools, read from src/ and write to tests/, and always run tests after writing them.
When to Use Agent Teams
| Scenario | Why Teams Help |
|---|---|
| Parallel feature development | Multiple agents build different modules simultaneously |
| Research and implementation | One agent researches while another implements |
| Code review pipeline | Security, performance, and style reviewers in parallel |
| Test writing | Test agent writes tests while feature agent writes code |
| Cross-layer work | Frontend agent and backend agent work simultaneously |
When NOT to Use Agent Teams
- Simple tasks. If one agent can handle it in a few minutes, teams add unnecessary coordination overhead.
- Tightly coupled work. If every change depends on the previous one, sequential work is faster than parallel.
- Small codebases. Teams shine when there are clear boundaries between modules.
Agent Team Patterns
The Review Pipeline
Lead assigns a feature to an implementation agent and a review agent. The implementation agent writes code. The review agent watches for completed files and reviews them. Feedback flows back through the task system.
The Research-Then-Build Pattern
Lead spawns a research agent to investigate the problem space while the lead plans the architecture. Once research is complete, the lead spawns implementation agents with the research context.
The Parallel Modules Pattern
For a feature that spans multiple modules, spawn one agent per module. Each agent has clear read and write boundaries defined in their agent file. The lead coordinates integration.
How Agent Teams Relate to Other Features
Agent teams sit at the top of the Claude Code configuration stack:
| Layer | Purpose |
|---|---|
| CLAUDE.md | Project context — loaded by every agent |
| Rules | File-specific conventions — activated per agent |
| Permissions | Tool access — enforced per agent |
| Skills | On-demand procedures — available to all agents |
| Hooks | Deterministic automation — runs for all agents |
| Agent Teams | Coordination — orchestrates all of the above |
Every layer below agents is inherited. When a teammate runs, it loads the same CLAUDE.md, respects the same permissions, and triggers the same hooks as a solo session.
Setting Up Agent Teams
To enable agent teams in your project, add the experimental flag to the env section of your settings.json:
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in the env object.
Then create your agent definitions in .claude/agents/. Each file becomes an available role that the lead can spawn.
Designing Effective Agent Roles
- Keep roles focused. An agent that does everything is just another solo session.
- Define clear boundaries. Specify which directories each agent reads from and writes to.
- Limit tools by role. A reviewer should not have write access. A test writer should not have deploy access.
- Write the agent like an onboarding doc. Include what to do, what to avoid, and where to find things.
Building Agent Teams with DotBox
Defining agent teams requires creating structured markdown files with the right sections, configuring settings.json correctly, and designing working directory boundaries that prevent agents from stepping on each other. DotBox lets you draw the team instead — templates for common roles, an editor for each agent's instructions, tools and model, and arrows for who hands work to whom. One setup prompt has Claude Code write the directory structure: the agents, settings.json, working directories, and the CLAUDE.md that ties them all into an orchestrated system.