Finding signal on Twitter is more difficult than it used to be. We curate the best tweets on topics like AI, startups, and product development every weekday so you can focus on what matters.
How to install and use Claude Code Agent Teams (Reverse-engineered)
Jason Zhou@jasonzhou1993 · February 7, 2026 · 5 min read
Before you dive in
• Claude Code's Agent Teams enable 3-5 independent instances to collaborate through shared tasks and messaging, fundamentally changing how AI agents work...
Best for builders who want practical takeaways. 5 min read.
Claude Code just shipped a massive upgrade to its agent system: Agent Teams.
This isn’t a small iteration on the old task + sub-agent model. It’s a fundamentally different execution model that allows 3–5 independent Claude Code instances to collaborate on the same project, share context, exchange messages, and coordinate through a shared task system.
I spent time digging into the logs, tracing model calls, and inspecting the filesystem changes behind the scenes. After a lot of back-and-forth investigation, I finally feel like I understand how Agent Teams actually work - and more importantly, when they’re worth using over traditional sub-agents.
This post walks through:
How to install and enable Agent Teams
How Agent Teams differ from sub-agents
The internal tools and lifecycle (Team Create, Task Create, messaging, shutdown)
How agents communicate with each other
A real debugging use case where Agent Teams clearly outperform sub-agents
How to install and enable Agent Teams
Before anything else, make sure you’re on the right version.
1. Update Claude Code to latest version
2. Enable the Experimental Flag
Agent Teams are still behind a feature flag. Run below to open settings.json
and in global setting file, add:
Save the file and restart your terminal.
3. Start a New Claude Code Session
Once enabled, They can be activated when your prompt explicitly instructs Claude Code to create an agent team.
For example:
“I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.”
Tasks can be delegated top-down by team-lead (which is the main agent), or Self-claim (as agent team can use taskList or getTask, updateTask tool to do so)
Tool 3: Task tool
The agents are still activated by Task tool, which is the same as sub agent, however it got some upgrades;
It got new params `name`, and `team_name`, when those 2 params are past, it will use agent team instead of simple sub agent subprocess
Tool 4: taskUpdate
Each agent is expected to call taskUpdate tool to claim task, update status
Tool 5: sendMessage
Agent Teams introduce a Send Message tool.
It supports:
Direct messages (agent → agent)
Broadcast messages (agent → all teammates)
Under the hood:
Messages are written to .claude/teams/<team_id>/inbox/
Each agent has its own inbox
Messages are injected as new user messages into the agent’s conversation history, e.g. <teammate-message teammate_id=“team-lead”>....</teammate-message>
--------
Meanwhile team-lead agent can send `shutdown_request` to team mate agent, where team-mate agent send `shutdown_response` to confirm, which likely use postToolCall hook to auto terminate the agent session
When Agent Teams Are Actually Better Than Sub-Agents
It's hard to tell whether anthropic will sunset sub-agent and just use agent teams, but this new structure open up loads of imagination as it offers a more sophisticated communication channel & context sharing
One example I liked from their official doc is for deep debug:
Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges.
I used this for @SuperDesignDev and it works great; But the trade-off is a lot more token consumption and speed; So i dont think agent team directly replace sub agents, yet;
I can imagine this agent team + some sort of ralph loop can put together structure for extremely long running agentic tasks completion;
Keen to see what use cases you guys come up with, comment below!
If you enjoy this and want to dive deeper, you can join @aibuilderclub_ where we share latest learnings on AI coding + agent building weekly.
