The Claude Code Docs Have Got It All Wrong
(NOTE: Agent teams are an opt-in, experimental feature.
If you want to use them, set this environment variable to "1": CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.)
If you haven't tried it, Claude Code has an amazing feature called Agent Teams. Forget about all those fancy agent orchestration frameworks - you can just describe to Claude some really complicated workflow pattern you want to use - and, from my experience at least (with Opus), Claude will very reliably organize a team of agents to follow this workflow. And not only that, they can communicate with each other (and with you) directly, help each other out, and find their way out of problems without bumping into each other too much.
However, the documentation presents this as a fairly limited feature - a kind of unreliable alternative to standard sub-agents. According to the official documentation about agent teams:
(i) there can be at most one active team at a time;
(ii) teammates cannot spawn their own teams/teammates;
(iii) nested team structures are not possible;
(iv) only "Main Claude" (the original session Claude) can lead a team;
(v) teams cannot change leadership in the middle of a session.
These claims are all false. They are based on a conflation of two different capacities - (i) the ability to lead a team (i.e., coordinate and manage the work of other Claude Code agents), and (ii) the ability to create a team, and to create, or spawn, agents for a team. It's true that only Main Claude is able to use the TeamCreate, TeamDelete, and Agent (spawn) tools. But there's no technical requirement that the agent who does the spawning is the one who does the leading.
Claudes are pretty nice to each other, for the most part. So if Main Claude creates a team and then says to everyone, "OK, Alpha over here is going to be leading the team today, so it will be managing your tasks", the rest of the Claudes do not revolt. They cheerfully continue their work under the leadership of some other Claude (can they really tell the difference?), which violates rule (iv) above. Furthermore, Main Claude is such a nice Claude that if Alpha asks it to kindly spawn some agents, Main Claude will do it. So rule (ii) is kind of true, but it isn't true in any thick sense. Another convenient thing, is that Claude can spawn more agents at any time throughout the session - the team does not have to be generated all at once.
So I built a little plugin that implements a pattern that takes advantage of this "loophole" - that is, decoupling spawning and leading. The way it works is: Main Claude spawns the Squad Leader and two other agents who sit down together and figure out what sort of team they need in order to complete the task that you want then to complete. Then, the Squad Leader messages Main Claude and says, "Hi, can you please spawn agents X, Y, and Z for me?" And since Main Claude knows about this protocol, it always obliges. Then, from that point on, the Squad Leader leads its own "squad" (i.e., team), specially designed for your specific task.
That's very nice. But the crazy this is - once you've got this working, there's nothing stopping you from having Claude spawn two Squad Leaders, each leading their own team/squad at the same time. They can also decide to switch roles, so some other agent gets "promoted" to Squad Leader. They can even work in a layered fashion where one squad is building code that's functionally nested within another squad's part of the codebase. So basically: all of (i)-(v) above turn out to be false. And because Main Claude is now mostly a passive "Queen Bee", consuming very few tokens, mostly having a good nap and occasionally waking up to magically create more agents, it could potentially last for a pretty long time. So you can easily imagine a rotating cast of squads that are able to communicate, collaborate, work in tandem, create more squads when they need to, and basically plow their way through an entire codebase. I doubt if the current feature is stable enough to go quite that far, but if you build in the right guardrails... Either way, the point is: this is a very powerful pattern, and there's no reason you can't try! Despite what the docs would have you believe.
So that's one cool thing you can do with Claude Code agent teams.
Don't believe me?
If you want to learn more about it, check out Really Claude Code, or this nice visualizer and let me know what you think about this pattern.
Top comments (1)
Spawn-vs-lead is the key insight here. Main Claude doesn't enforce the leadership invariant; it just holds the team-creation tools. Once that distinction lands, the documented ceilings on the feature mostly lift. The Queen Bee framing also has real cost implications: Main Claude in the napping role consumes very few tokens while the squad does the work, and no single agent's context ever gets crowded because work is naturally partitioned. From my own attempts running Opus this way, shared file state is the main pain point. Two agents editing the same file produces clobbered diffs; a tiny lock protocol expressed in the team system prompt (announce, ack, edit, commit, release) takes care of most of it, but Opus won't invent the protocol on its own. Switching leadership mid-session genuinely works when the task shape changes, as long as the handoff is an explicit message rather than a silent role flip. Good post; this pattern deserves a spot in the docs.