Agent teams are a Claude Code feature where, instead of a single assistant, several work for you — in parallel, with one shared task list and the ability to talk to one another. Let me start with two terms, because they'll come back throughout. An agent is a program built on a language model that's given a task and carries it out on its own: reads files, writes code, checks the result. Claude Code is the tool in which such an agent works on coding and operational tasks — it runs in the terminal (the command window) or as an editor extension, reads files, and executes steps one after another.
What follows is a practical overview: how an agent team differs from a single helper agent, how to switch it on, how to brief it so the result is good, and — importantly — when not to use it at all.
What it looks like in practice
The easiest way to show it is with an example. A single instruction can ask for a team of three agents to be created: a front-end developer (the part visible in the browser), a back-end developer (the part running on the server side), and a QA agent — quality control. Claude Code starts all three in parallel. Each is a separate agent, but they share one task list and work alongside the main session — the one you're typing in.
Things get interesting at the quality-check stage. The front-end and back-end developers hand their work to the QA agent. It can find serious bugs and send the task back — at which point the main agent distributes the fixes between the first two, and on the next pass QA gives the green light once everything is repaired. From a single instruction along the lines of "build a website for a fictional AI startup," a complete site emerges: copy, color scheme, animations. Not perfect, and it'll need touch-ups, but coherent and ready to work on further.
How it differs from a single helper agent
This is the source of the biggest misunderstanding, so it's worth clearing up. A helper agent (a sub-agent) works on its own and sends its result back to the main agent. It operates solo and reports at the end.
An agent team works differently. It has something like a leader — the equivalent of a project manager — that creates the individual agents and one shared task list. The key difference: team members can talk directly to one another. When one needs something from another, it simply sends it a message, without going through the main session. This is what creates the useful loops — like the one with the QA agent that says "this isn't good enough yet" and sends the work back. The main agent watches throughout, making sure tasks close out and the quality stays high.
In short: a sub-agent is a single doer with a report at the end. A team is several doers working at the same time and communicating the whole way through.
How to switch it on
The feature is experimental for now and off by default. You turn it on with a single setting (a variable) in the project's configuration file — settings.json. The official Claude Code documentation has a ready snippet to copy; you can simply ask Claude Code to drop it into the project's local settings.
There's one more thing worth doing before the first run: teach the project how agent teams work. The simplest way is to take the documentation URL and ask for a local guide to be made from it — a Markdown file in the docs folder. From then on, whenever Claude Code needs something about teams, it reaches for that file instead of reading the online documentation every time. It's the same trick worth using for any lengthy documentation the model returns to often.
How to word the instruction
You summon a team in plain language, with no special syntax. A good template looks like this:
- Start with the goal. When the agents "wake up," they have no context — they know only what the main session gives them. If you say up front what the whole team is aiming for, each one understands not just its own task but also why the others are there beside it.
- Set the lineup: "create a team of three agents on model X" (the choices are the Haiku, Sonnet, and Opus models — from the fastest and cheapest to the most powerful).
- Describe each role: what a given agent is to do, what it's to produce, and whom it should contact when it's done ("when you're ready, send the result to the front-end agent").
- Name the end deliverable. The main agent will collect a great deal of information from everyone — say outright what you want at the end: a working app, a test report, a short document describing what was built and how to run it onward.
To which add a few rules that make the difference between a team that works and one that gets tangled up:
- Each agent has its own files. If several agents edit the same file, they can overwrite each other's work. Give each one its own turf.
- Define the deliverable precisely. Vague instructions give vague results.
- Name the recipients explicitly. Don't assume an agent will work out on its own who to write to, and why.
- Stick to three to five agents. A swarm of ten or more isn't just chaos — it's a cost that climbs in step with the headcount.
- Give the full context up front. Agents can read all the files in the project, but at the start they get nothing beyond what you tell them.
What agents know when they "wake up"
Since they don't get the conversation history, it's worth knowing what they do have. First, they inherit the permissions of the main session — if you approved certain commands, they have them too. Second, they have access to all the project files, as well as to the connected tools and skills — everything the main session has at its disposal.
There's also a useful plan-approval mode. Before an agent does anything, it must first present a plan and have it approved — by the main agent or by you. It's the same habit as working in planning mode in a single session: plan first, then act. It's usually more convenient to have the main agent approve the plans; you can also designate one team member as the plan reviewer.
The most common problems, and what to do about them
- The agents keep asking for permission and stalling the work → approve selected commands up front in the project settings.
- The result doesn't come together as a whole → the agents are probably overwriting each other's files; assign file owners.
- One agent is sitting idle → make sure each one has work assigned in the instruction, or a dependency on the others.
- Token usage climbs too fast → use fewer agents (a token is a portion of text the model processes, and the unit of billing; three parallel sessions are roughly triple the cost).
- The agents lose their work → ask them to save everything to temporary files they can return to.
When to use a team, and when not to
Agent teams are slower and more expensive than a single agent. That's not a flaw — it's the price of higher quality on complex tasks. Reach for them when a task has several distinct areas (each agent takes one), when those parts can be produced in parallel, when the agents have to react to one another and hand tasks back and forth, and when you care about high quality policed by many steps of review.
On the other hand, it's easy to over-reach with this feature. Don't use a team when:
- the process is sequential — the steps run in order (1, 2, 3) and each depends on the one before; that's more a job for sub-agents,
- everything is meant to fit in one context window (that is, in a single conversation and its history),
- the agents would end up working on the same files anyway,
- the task is simply simple — then a team is overkill.
It's the same honest caveat worth repeating for every AI tool: someone else's use case is not your use case. A more powerful feature isn't automatically better for what you happen to be doing.
Finally: close the team down properly
When the work is done, the main agent sends the team members a request to close — the equivalent of "finish up and save your work." An agent can reply "I'm not done yet, don't close me" and finish saving. The point is that everything ends up cleanly saved at the end, not cut off halfway. It's a small thing that decides whether you're left with an orderly result after the session, or a mess to clean up.
Agent teams are one of the more powerful tools in Claude Code — but that's exactly why it's worth knowing when not to reach for them. On a complex task with several areas that have to be built in parallel and talk to each other, they deliver a quality that's hard to achieve any other way. For anything simpler, a single agent or a sub-agent is usually enough — cheaper and faster.