Table of contents
- What are Claude agent teams
- Advantages of agent teams
- How do agent teams actually work
- How to set up Claude Code agent teams
- Side-by-side comparison: subagents vs agent teams
- Real use cases for agent teams
- Dos and don'ts for designing your agent team
- Another paradigm: Build your multi-agent team in Kimi Agent Swarm
- FAQ
Relying on a single AI session for complex, multi-domain workflows is inherently slow. Claude agent teams solve this by executing specialized agents in parallel, delivering deeper outputs at much higher speeds. This guide covers how Claude Code agent teams work, how to set them up, and best practices for maximizing their value.
What are Claude agent teams
Claude Code agent teams are a multi-instance coordination system where multiple Claude sessions work in parallel on the same codebase. One session is designated as the lead agent, receives the overall task, decomposes it into subtasks, and synthesizes the final output. The other sub-agents are teammates, each running in their own isolated context window, own a discrete piece of work, and communicate with other teammates directly.
Advantages of agent teams
Agent teams differ from typical AI assistants in that they process tasks sequentially, one at a time. Agent teams break that constraint: when work can be genuinely parallelized, the wall-clock time drops accordingly.
Meanwhile, agent teams are more than multiple sessions, for the coordination layer adds three capabilities that manual multi-session work lacks:
- Peer-to-peer messaging: Teammates can send messages directly to each other without routing through you or the lead. For example, an agent team with a security reviewer can flag a finding to the performance reviewer mid-run without stalling the whole team.
- File locking: When a teammate writes to a file, it acquires a lock that prevents concurrent writes from other agents. This blocks the silent-overwrite class of merge conflicts.
- Dependency tracking: The lead encodes task dependencies during decomposition. The coordination layer enforces them, so no agent starts before its prerequisites are met, without manual polling.
How do agent teams actually work
An agent team consists of the following components, each with a specific role:
The team lead is the main Claude Code session. It creates the team, spawns teammates, coordinates work across them, and synthesizes the final result. This is the session you interact with directly.
Teammates are separate Claude Code instances, each working independently on their assigned tasks within their own context window. They don't share context with the lead or with each other; their communication happens explicitly, through the task list and the mailbox.
The shared task list and the mailbox enable coordination**.** The shared task list is a live queue that the agent group reads from and writes to. The lead populates it at decomposition time, and teammates claim tasks, work through them, and mark them complete. Dependencies are enforced automatically; when a teammate completes a task, any tasks that were blocked on it unblock without manual intervention. The mailbox is the messaging system for direct agent-to-agent communication. Messages flow automatically between teammates and the lead.
Both the team config and the task list are stored locally (~/.claude/teams/ and ~/.claude/tasks/). Claude Code generates and maintains these files automatically. Do not edit them by hand, as any changes will be overwritten during the next state update.
How to set up Claude Code agent teams
Claude agent teams are disabled by default in Claude Code. They're labeled experimental and require an explicit opt-in. Here's the complete setup path. Before enabling agent teams, you should confirm that your Claude Code version is v2.1.32 or later**.** You can run claude --version in the terminal to check.
Step 1: Enable the feature flag
Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1. Three ways to do this:
Option A: ~/.claude/settings.json (recommended)
Option B: Shell profile (~/.bashrc or ~/.zshrc)
Option C: Inline, for a single session
If you edited settings.json or your shell profile, restart Claude Code for the flag to take effect.
Step 2: Install tmux (recommended, not required)
Agent teams display in two modes: In-process (all teammates run inside the main terminal) and split panes (each teammate has its own pane, which requires tmux or iTerm2). Running each teammate in its own terminal pane makes it significantly easier to monitor the team in real time.
To make sure to stay in split panes mode, setteammateMode in ~/.claude/settings.json:
To override the default "auto" setting, set teammateMode in ~/.claude/settings.json as in-process. To force in-process mode for a single session, pass it as a flag: claude --teammate-mode in-process.
Step 3: Prompting to start your agent team
After enabling the agent team, simply tell Claude in natural language what tasks, deliverable, and team structure you want the agent team to do. You can specify each role in the prompt, and Claude will create the team, spawn teammates, and schedule tasks accordingly.
Example prompt:
You can specify what model your agent teams use, such as "Use Sonnet for every teammate". Teammates don't inherit the lead agent's model. Users must specify the model in the role file frontmatter or set a default teammate model via /config.
Step 4: Ask for plan approval for complex tasks (optional)
For tasks of high risk and complexity, you can require the team to draw up a plan before execution. The teammates in the agent group will work in read-only mode, and the lead will review, revise, and finally pass the plan. Only when the plan is approved by the lead will the teammates start implementing.
Note that the lead agent will make decisions, so you can also provide some criteria for decision-making.
Example prompt:
Step 5: Set up git worktrees for file isolation (optional, recommended)
If any teammate writes files, Claude Code worktrees are strongly recommended. A git worktree is a separate working directory on its own branch, sharing the same .git history as your main checkout. Each agent gets isolated file access, and edits from one worktree never touch another agent's in-progress work.
To enable this per-agent, simply add isolation: worktree to the agent's YAML frontmatter. Claude Code provisions a fresh worktree for each parallel agent invocation and cleans it up automatically when the agent finishes.
For CLI usage: claude --worktree or claude -w starts a session in its own worktree. The desktop app automatically creates a Claude Code worktree per session.
Step 6: Monitor at regular intervals
Agent teams are not set-and-forget, and long-running teams may drift. Agents might get stuck on permission prompts, mark tasks done prematurely, or lose track of scope. You can check in every 10–15 minutes and review the shared task list for stuck or unclaimed tasks. If a task hasn't moved in 20–30 minutes, it might be due to a permission block or a mis-specified role that requires manual intervention.
Side-by-side comparison: subagents vs agent teams
Subagents are a delegation pattern. Agent teams are a collaboration pattern. The difference shapes everything from how context is managed to how much a run costs.
| Subagents | Agent teams | |
|---|---|---|
| Communication | One-way: lead dispatches, subagents report back | Peer-to-peer + lead coordination |
| Shared state | None | Shared task list with dependency tracking |
| Context windows | Own context window; results return to the lead | Each teammate has its own (up to 1M tokens) |
| File conflict prevention | Not built-in | File locking included |
| Token cost | Lower | Higher (every teammate is a single instance) |
| Session resumption | Supported | /resume and /rewind don't restore in-process teammates |
| Nested agents | Supported | Not supported; only the lead can spawn teammates |
| Best for | Focused delegation, repeatable workflows | Parallelizable, inter-dependent, multi-domain work |
Subagents are a one-way delegation pattern: the lead sends a task, the subagent executes it within its own context window, and the result is returned. There's no shared state, no direct communication between sibling agents, and no coordination layer, just a clean dispatch-and-return loop.
Agent teams work on a shared task list with automatic dependency enforcement, and message peer-to-peer between teammates via the mailbox.
In short, agent teams pay off when the work is divided into genuinely independent parallel tracks that need to share findings and coordinate with each other. For quick results, sequential tasks, single-file edits, or anything where cost predictability matters more than speed, subagents are the better call.
When to choose agent teams and when subagents
Use agent teams when:
- Teammates need to communicate directly with each other
- The work requires a shared task list with dependency tracking across parallel workstreams
- The task is too large for a single session, and each worker needs their own fully independent context
Use subagents when:
- You only need the final summary, not the full intermediate output
- The work is self-contained enough to return a clean result
- You want to restrict tools or route to a cheaper model
- You need parallel research paths that don't depend on each other
If you can't identify at least three genuinely independent parallel workstreams, a single session or subagents will likely outperform an agent team at lower cost.
Real use cases for agent teams
When the work naturally divides into scoped, bounded workstreams, those workstreams can proceed without waiting for one another (or their dependencies can be encoded explicitly), and the overhead of coordination is small relative to the time saved by running in parallel. Here are five use cases where agent teams outperform a single session.
Parallel code review
Assign three reviewers to a pull request simultaneously, including a security agent, a performance agent, and a test coverage agent. The lead synthesizes three parallel reports into one prioritized action list. This pattern also works for architecture review (scalability agent, security agent, maintainability agent) or compliance checks across different regulatory frameworks.
Competing-hypothesis debugging
Spawn five agents, each with a single hypothesis, to test specific files or logs to examine a production bug. The first agent to confirm its hypothesis surfaces the fix, and the others can be stopped. This is a more efficient way than investigating each theory sequentially and spending hours of debugging one path, backtracking, and starting the next.
Cross-layer refactors
A cross-layer refactor task contains both sequential and parallel steps. For instance, a breaking API change needs updates in backend endpoints, frontend components consuming those endpoints, and the test suite covering both. The backend work must be completed before the frontend can begin. Once the backend task is underway, the test suite agent can start scaffolding the new test structure in parallel. In an agent team, the lead uses the shared task list's dependency tracking to encode this ordering.
Research sweep without context contamination
A technical decision may require surveying multiple independent bodies of evidence, such as choosing a database engine, evaluating three third-party APIs, and assessing build tooling. Assign each agent a non-overlapping domain, and each posts a structured summary. The lead aggregates into a comparison document. The isolation preserves an independent perspective, improving the quality of the results.
Large codebase migration
Upgrading a major dependency across a large codebase typically involves touching multiple modules. If those modules have clean boundaries and can migrate simultaneously, agent teams help. Assign one agent per independent module; each agent migrates its module, runs its own test suite, and reports back with a migration summary that includes any changed interfaces. The lead reviews interface changes before declaring the migration complete and coordinates the merge sequence.
Dos and don'ts for designing your agent team
Building a parallel agent system with Claude Code is straightforward to set up, but easy to get wrong. These are the design principles that determine whether your agent team performs or wastes time.
Pro tips when building your parallel agent system
- Pre-approve permissions: Teammates start with the lead's permission settings. If the lead runs with --dangerously-skip-permissions, all teammates inherit that too. You can adjust individual teammate modes after spawning, but per-teammate modes cannot be configured at spawn time. Plan your permission posture through the lead before launching the team.
- Write tight role prompts: Each role prompt should specify four things: what to do, which files or domains to work in, what to focus on and what to exclude, and what the deliverable looks like. When spawning teammates, you can refer to subagent types from any subagent scope: project, user, plugin, or CLI-defined. This lets you define a role once, such as a security reviewer or test runner, and reuse it both as a delegated subagent and as an agent team teammate.
- Enforce file isolation: For any agent that writes to disk, use isolation. Two agents modifying the same file simultaneously is one of the most reliable ways to produce corrupted output.
- Check in on a schedule: Every 10–15 minutes for active agent teams. Look at the shared task list for tasks that haven't moved. A task stuck for more than 20–30 minutes might be due to a permission issue, a mis-specified role, or a circular dependency, which may require manual resolution.
- Encode dependencies explicitly: If Task B logically follows Task A, write that dependency into the task list at decomposition time, not as an instruction in a role prompt. The coordination layer enforces dependencies automatically; instructions in prompts can be misread or ignored.
- Define ownership boundaries in your md file: For multi-session projects, write a rule that each module or directory has exactly one owning agent. This prevents overlap before the team is even launched.
- Always clean up through the lead, not through a teammate: The lead checks for active teammates before clearing resources. Teammates lack the full team context to clean up safely; doing so risks leaving the session in an inconsistent state.
Common mistakes you can avoid for your agent team
- Don't spawn a team for a task that one session handles cleanly: Before writing a single role file or sending a single swarm prompt, draw the task graph. Which subtasks are genuinely independent? Which have dependencies? Is it a sequentially dependent work? If you can't articulate three parallel tracks with clean boundaries, a single session will outperform the team.
- Don't assign two agents to the same file. This is the most common source of merge conflicts and silent overwrites. If your task decomposition produces two agents that need to touch the same component, that component's work should be sequential — assign it to one agent after the other completes.
- Don't skip permission pre-approval in Claude Code. Permission prompts that fire mid-run stall parallel execution and require manual intervention. The overhead eliminates much of the benefit. Pre-approve file writes and shell commands for the working directory before launching.
- Don't expect to restore your Claude Code team. If a session is cleaned, /resume and /rewind do not restore in-process teammates. Save important intermediate outputs before long runs.
- Don't run a team past five without a clear reason. Token costs scale linearly, but coordination overhead grows faster. Three focused agents with tight roles consistently outperform five agents with vague ones. Add teammates only when there's an explicit parallel workstream waiting — not because more feels like more.
Another paradigm: Build your multi-agent team in Kimi Agent Swarm
Claude Code agent teams excel in developer-native scenarios, integrating deeply with terminal workflows and the Git ecosystem. However, the paradigm of multi-agent collaboration extends far beyond the command line. Kimi Agent Swarm is where that paradigm becomes accessible to everyone.
Kimi Agent Swarm is Kimi's multi-agent collaboration system built for complex, large-scale tasks. It breaks a broad goal into discrete subtasks and schedules different agents and skills to handle search, reading, analysis, writing, coding, spreadsheet generation, slide creation, and web page building simultaneously. No env flags. No git config required.
Key features of Kimi Agent Swarm
- Parallel collaboration across up to 300 sub-agents: Kimi Agent Swarm decomposes a complex task and schedules multiple sub-agents to handle subtasks simultaneously. The system can coordinate up to 300 sub-agents to execute more than 4,000 tool calls in a single run.
- Multi-skill compound execution: The Swarm can combine multiple specialized skills in a single run, including deep research, pptx, report writing, vibe-coding, website building, paper writing, and outperforming a single agent in output depth and format coverage.
- Large-scale document processing: Agent Swarm can batch-process files across 20+ formats (PDF, Word, Excel, PPT, images, etc.), reading, extracting information, and summarizing content in parallel across the full document set, able to reference libraries, competitive intelligence files, or multi-source data ingestion.
- Proactive broad research: For tasks that require information across wide surface areas, Agent Swarm dispatches sub-agents to search the web, locate sources, download content, categorize findings, and generate structured summaries in parallel.
- Multi-perspective reasoning: Agent Swarm can run multiple expert viewpoints on the same problem simultaneously. This produces a more complete analysis than a single-viewpoint pass and surfaces blind spots that sequential review misses.
- Deep content delivery: Agent Swarm's parallel architecture is built for sustained-depth outputs, such as multi-hundred-page research reports, long-form industry analyses, academic literature reviews, structured learning guides, and extended narrative content.
- Multi-format output in a single run: Agent Swarm can produce multiple deliverable types simultaneously on the same task, such as a PDF report, a PPT deck, a web page, an Excel dataset, and a code project.
How to run an agent team in Kimi Agent Swarm
Step 1: Open Kimi Agent Swarm and enter your prompt
Open the Agent Swarm page and describe your task in the input box. For best results, be specific about the scope, the deliverables you expect, and any constraints such as time range, sources, or format requirements.
Example prompt:
Step 2: Let Kimi Agent Swarm work
After sending your prompt, Agent Swarm will break the task into subtasks and dispatch subagents to work in parallel. You can watch real-time progress, including task planning, sub-agent spawning, and parallel execution.
Step 3: Receive, preview, and download or share the results
Once the run is complete, your deliverables are ready to preview directly in the interface. Depending on your task, outputs may include research reports, data analyses, PPT decks, web pages, code projects, or a combination of these. You can download the files and share them directly.
Use cases where Kimi Agent Swarm shines
- Tender and proposal writing: Assign parallel agents to technical specs, compliance requirements, pricing models, and case studies simultaneously; the orchestrator integrates them into a cohesive proposal.
- Financial analysis: Assign parallel agents to deal with market data, competitor filings, macro indicators, and internal models; the orchestrator synthesizes them into a unified analysis.
- Business research: Assign parallel agents for competitive landscapes, customer interviews, industry reports, and regulatory context from different sources; the orchestrator produces a structured output.
- Security testing: Run parallel agents for reconnaissance, vulnerability scanning, dependency auditing, and privilege escalation checks; the orchestrator aggregates the findings into a final report.
- Full-stack development: Build parallel agents for frontend components, backend endpoints, database schema, and test suites; the orchestrator coordinates integration across the full stack.
Conclusion
Claude Code agent teams are purpose-built for engineering workflows, bringing parallel execution to complex codebases directly from the terminal. If your work extends beyond code, Kimi Agent Swarm brings the same multi-agent paradigm to research, analysis, content, and more. Simply describe your task and let the swarm handle the rest.