Claude Agent Teams: How to Build an AI Engineering Squad for Your Projects

With Claude Agent Teams, you can now coordinate multiple Claude Code instances working simultaneously on your codebase — one on the API, another on the UI, a third on security review — all within a single orchestrated session.

Released alongside Claude Opus 4.6, it marks a shift from prompting a tool to managing a squad. This blog covers what Agent Teams is, how it differs from subagents, how context and sessions work across the team, and how to integrate it into a real project.

What Is Claude Agent Teams?

Agent Teams is an experimental Claude Code feature that coordinates multiple independent Claude Code instances on the same project. Each has its own context window and role, connected through a shared coordination layer. There are three building blocks:

The Team Lead is your primary Claude Code session — the orchestrator that decomposes tasks, delegates to teammates, monitors progress, and synthesizes results.

Teammates are independent sessions spawned by the lead, each with a defined role and its own context window running in parallel. Unlike subagents, you can interact with individual teammates directly without going through the lead.

The Shared Task List and Mailbox System is the coordination backbone. Tasks are tracked in a file-backed board with states (pending, in_progress, completed) and dependencies. Agents communicate by appending structured JSON messages to each other's inbox files — genuine peer-to-peer coordination, not just parallel execution.

__Quick Enable:__ Add `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to your `settings.json` or environment. Disabled by default.

Subagents vs. Agent Teams — What's the Real Difference?

Subagents are roles Claude temporarily adopts within a single session — one context window, one session, Claude wearing different hats sequentially. Useful for role-based specialization, but fundamentally one agent doing different things, not multiple agents running at once.

Agent Teams are structurally different. Each teammate is a fully independent Claude Code instance with its own context window, running in parallel and communicating via structured messages. The line that sums it up best: "Subagents are function calls. Agent Teams are organizations."

Dimension	Subagents	Agent Teams
Structure	Single session; Claude adopts a role	Multiple independent Claude Code instances
Context	Shared within one context window	Each teammate has their own isolated context window
Communication	Reports back to the main agent only	Peer-to-peer; teammates can message each other and the lead
You interact with	Only the main session	The lead AND individual teammates directly
Token cost	Base cost	3–10x more tokens than a single-agent approach
Best for	Sequential tasks, role specialization	Parallel, independent workstreams
Analogy	One developer wearing different hats	A real engineering squad with defined roles

Agent Teams add real overhead — more tokens, more setup, more coordination. That cost is only worth it when your task genuinely benefits from true parallelism and independent context windows.

How Context and Sessions Are Managed

Teammates start fresh. When the lead spawns a teammate, it does not inherit the lead's conversation history. This is intentional — isolated context windows prevent one agent's assumptions from polluting another's reasoning.

What teammates inherit automatically: your project's CLAUDE.md, configured MCP servers, and installed Claude Code skills.

What they don't inherit: the lead's conversation history, session context, or results from other teammates — unless you explicitly include them in the spawn prompt. This makes your spawn prompt critically important: include everything a teammate needs to do their job.

Communication happens via file-backed inboxes. Teammates append structured JSON messages to each other's inbox files. The lead periodically reads these to synthesize results and update the shared task list, which tracks status (pending, in_progress, completed), ownership, and blocked dependencies. File locking prevents race conditions when multiple teammates try to claim the same task simultaneously.

Two key limitations to keep in mind: there is currently no session resumption (an interrupted session cannot be resumed), and nested teams are not supported (a teammate cannot spawn its own sub-team).

Always shut down via the lead. The lead issues graceful shutdown requests to each teammate, then runs cleanup. Cleaning up through a teammate instead can leave shared resources in an inconsistent state.

When to Use Agent Teams (And When Not To)

Agent Teams add real overhead — Anthropic has seen teams spend months on multi-agent architectures only to find better prompting on a single agent achieved the same result. Use them only when the task genuinely benefits.

Use Agent Teams for: parallel independent workstreams (frontend, backend, tests with no shared files), competing hypothesis debugging (multiple agents test different root causes simultaneously), and large features spanning multiple distinct modules.

Avoid them when: tasks must run sequentially, agents would edit the same files, the work fits in a single context window, or the token budget is tight (teams cost 3–10x more).

⚠️ __Known Limitations:__ No session resumption, no nested teams, significantly higher token cost.

Step-by-Step Guide — Integrating Agent Teams Into Your Project

Step 1: Enable the Feature

Add the following to your Claude Code settings.json or set it as an environment variable:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teams is disabled by default. Without this flag, TeammateTool operations will not be available.

Step 2: Map Your Task Into Independent Workstreams

Before spawning any agents, think carefully about how to divide your work. The most important design decision in Agent Teams is how you split tasks. Anthropic's research identifies a critical distinction here:

Problem-centric decomposition (often counterproductive) divides by type of work: one agent writes features, another writes tests, and a third reviews code. Every handoff loses context. The test-writing agent doesn't know why certain implementation decisions were made.

Context-centric decomposition (usually effective) divides by context boundaries. An agent handling a feature should also handle its tests, because it already possesses the necessary context. Split your work where the natural boundaries of the problem lie — not where the types of work differ.

Ask yourself: can teammate A do its entire job without needing to know what teammate B is doing right now? If yes, they can work in parallel.

Step 3: Write Your Spawn Prompts Carefully

Because teammates start with a clean context window, your spawn prompt must contain everything the teammate needs. Be explicit about:

• The teammate's specific role and scope
• Any interfaces or contracts it must respect (e.g., API shapes agreed with other teammates)
• Where it should send results (e.g., "report findings to team-lead inbox")
• Constraints: what it should not touch

Here is an example spawn prompt structure for an auth system build:

Spawn 4 teammates for a user authentication system:

Teammate 1 (backend): Build Express.js routes for login, signup, and
token refresh. Use JWT. Document the request/response shapes in
auth-api-contract.md before implementing.

Teammate 2 (frontend): Build React login and signup forms with
validation. Consume the API contract defined in auth-api-contract.md.
Do not start implementation until that file exists.

Teammate 3 (testing): Write integration tests for all auth endpoints.
Once the backend routes are complete. Check backend-done.txt as your
trigger to begin.

Teammate 4 (review): After all three teammates signal completion,
Review all produced code for security vulnerabilities -- focus on the token handling, input sanitization, and session management. Send a summary to the team-lead's inbox.

Step 4: Configure Standing Teams in CLAUDE.md

For projects where you use Agent Teams regularly, define your team structure in CLAUDE.md, so teammates automatically load the right context and conventions:

## Agent Team Configuration

When spawning agent teams for this project:
- Backend agents: work in /src/api, follow REST conventions in CONVENTIONS.md
- Frontend agents: work in /src/components, use the design system in /design
- Test agents: mirror the structure of the module they are testing
- All agents: report completion status to the team lead's inbox

Step 5: Monitor Your Team

Use split-pane mode to watch teammates in real time. Claude Code supports tmux and iTerm2 for side-by-side visibility. You can set the spawn backend explicitly:

# For visible panes with tmux
export CLAUDE_CODE_SPAWN_BACKEND=tmux

# For fastest execution (no visibility)
export CLAUDE_CODE_SPAWN_BACKEND=in-process

The lead's task board shows task states at a glance. Check agent inboxes periodically to see interim findings and catch any coordination issues early.

Step 6: Synthesize and Shut Down Cleanly

Once teammates complete their work, the lead reads all inbox messages, synthesizes the findings or produced code, and resolves any conflicts at the system level.

To shut down:

# Request a graceful shutdown for each teammate via the lead
# Then run cleanup via the lead session -- never via a teammate

The lead checks for active teammates before cleanup completes and will fail if any are still running — a deliberate safeguard to prevent resource leaks.

A Real-World Example

Scenario: Building a user authentication system.

Role	Responsibility	Works in
Lead	Orchestrates, resolves conflicts, synthesizes	Full project
Teammate 1 — Backend	Express.js auth routes, JWT, API contract	/src/api/auth
Teammate 2 — Frontend	React auth forms, validation	/src/components/auth
Teammate 3 — Testing	Integration tests for all auth endpoints	/tests/auth
Teammate 4 — Review	Security review of all produced code	Reads all output

The lead spawns all four. Teammate 1 writes auth-api-contract.md first, define request/response shapes before touching any code. Teammate 2 waits for that file, then builds forms against the spec while Teammate 1 implements routes in parallel. Teammate 3 triggers once the backend signals completion, then runs integration tests. Teammate 4 begins its security pass only after all three finish, then reports findings to the team-lead inbox.

The lead synthesizes all inbox messages, resolves any interface conflicts, and issues graceful shutdown requests before cleanup.

Four sequential workstreams compressed into one coordinated session — each agent with deep, focused context over its own domain.

Conclusion

The question is no longer "what should I prompt?" — it is "how should I structure my team?"

Agent Teams is still experimental and comes with real costs: token overhead, coordination complexity, and no session resumption. But the architecture is clean, the use cases are well-defined, and this pattern is clearly where AI-assisted development is heading.

Start with a task where parallelism genuinely helps. Divide by context boundaries, not work types. Write precise spawn prompts. And always clean up through the lead.

Official docs: Claude Code Agent Teams