Agent teams: Multi-session Collaboration

📚 Series Navigation: The previous post [28 Using skill-creator] taught you how to build a skill that can be accurately triggered. This post introduces "multi-agent collaboration"—organizing several Claude Code sessions into a team. You act as the foreman to assign tasks, and they each take a part and work in parallel. Once they are done, you review and accept the work.

⚠️ Experimental, subject to change: Agent teams is an experimental feature explicitly marked by the official documentation, disabled by default, and requires Claude Code v2.1.32 or higher. The commands and default values in this post are based on the official documentation at the time of writing, but the interface, shortcuts, and behaviors may be adjusted later. Before following the steps, use claude --version to check the version.

"Why do you have three Claudes open on your screen? And they are all running."

"One is modifying the frontend, one is modifying the backend, and one is dedicated to writing tests. I oversee and assign tasks."

"Isn't that chaotic? How can you oversee three by yourself?"

"I don't need to stare at them constantly. They do their own things. Whoever gets stuck or needs me to make a decision will bubble up to find me—I spend most of my time doing other things."

The person in this conversation with three Claudes open is me. When I first ran multiple sessions on the same screen, the reaction of the colleague next to me was exactly the same—first surprise, then "can you oversee them?" To put it plainly, the surprising part is all about "how can one person simultaneously direct multiple AIs", and this is exactly what we will unpack in this post—Agent teams, making multiple Claude Code sessions collaborate like a team, where you are only responsible for assigning tasks and reviewing.

After reading this post, you will get:

• What Agent teams exactly are, and what ceiling of a single session they break through, explained in one sentence
• The difference between them and the subagent learned in the previous wave—a comparison table to clarify "when to use which"
• What the four key components of a team (leader, teammates, shared task list, mailbox) each do
• How to use claude agents (agent view), this "master control screen", to manage multiple sessions, and use Shift+Down to switch teammates in a team
• A practical exercise that you can run with expected outputs: enable the feature → start a three-person team → watch them work in parallel

---

01 Understand First: Where is the Ceiling of a Single Session

Conclusion first: Agent teams are designed to break through the two walls of a single Claude Code session: "limited context + strictly serial execution".

In the previous dozen posts, we have been tossing around in "one session"—opening one Claude, giving it instructions, and letting it work step by step. This pattern is sufficient for 90% of tasks. But there are two situations that will hit the ceiling:

The first is running out of context. A single session only has one context window (which can be understood as its "working memory"). If you ask it to simultaneously read the frontend, backend, and test codebases and coordinate modifications, the memory will quickly fill up, and it will "forget things" more easily as it goes on.

The second is doing things one by one. A single session is inherently serial—it only reads B after reading A, and only takes a turn for the backend after modifying the frontend. For three completely unrelated tasks, it still has to queue them up.

Analogy: In a large project, you act as the electrician, the bricklayer, and the carpenter, taking on all trades yourself. First, your brain cannot remember so many parallel things; while focusing on plumbing, you forget the progress of the bricklayer. Second, you only have one pair of hands; while wiring, you cannot lay tiles, and you can only switch to the next trade after finishing one. The smart approach at this time is not to shoulder everything yourself, but to act as a foreman—hire a few masters, let the electrician, bricklayer, and carpenter each take a part and start working simultaneously, while you are responsible for assigning tasks and reviewing.

Agent teams transform you from a "worker on the field" to a "foreman directing with composure". It is suitable for four types of tasks (the "strongest use cases" named by the official documentation):

• Research and review: Several teammates simultaneously investigate different aspects of a problem, and then challenge each other's findings.
• New modules / new features: Each teammate monopolizes an independent part without interfering with each other.
• Debugging with competing hypotheses: Several teammates test different theories in parallel, falsify each other, and converge to the root cause faster.
• Cross-layer changes: Frontend, backend, and tests span multiple layers, and a teammate is assigned to oversee each layer.

💡 One-sentence summary: A single session has two walls: "memory cannot hold enough, and work can only be serial"; Agent teams upgrade you from carrying it all alone to being a foreman leading a team working in parallel.

---

02 What exactly is the difference between it and subagent

This is the pair that is easiest to confuse, so we must clarify it first—otherwise, you won't know which one to use after learning both features.

The subagent we learned in the previous wave (Post 23) is a specialized assistant outsourced within a single session: it has an independent context, and only returns the conclusion to the main conversation after finishing. Teammates do not talk to each other, nor are they directly managed by you. Agent teams are completely different—they are multiple peer, complete Claude Code sessions collaborating. Teammates can send messages directly to each other, and you can also bypass the leader to chat directly with a specific teammate.

Analogy: A subagent is a temp worker you dispatch to run an errand, while an agent team is a crew you assemble to start work. For the errand temp worker, you give a single instruction "go pick out the errors in these thousand lines of logs", and he handles it himself and comes back with a note. He doesn't know your other temp workers, and only reports to you, this one superior, throughout the process. However, workers in a crew can discuss with each other "Have you modified the API on your side? I'm ready to integrate here," and as the foreman, you can walk up to any worker at any time to give specific instructions individually.

The differences fall into place in this table—if you can't remember anything else, remember this:

Dimension	Subagent	Agent teams
Context	Independent context, results passed back to caller	Independent context, completely independent
Who coordinates	Main agent manages all tasks	Leader coordinates, but has a shared task list for self-coordination
Between teammates	No communication, only report results to the main agent	Directly send messages to each other
Can you manage directly	No, only through the main conversation	Can converse directly with any teammate
Token cost	Lower, results aggregated back to the main context	Higher, each teammate is an independent Claude instance
Best suited for	Focused tasks needing only results and no discussion	Complex collaboration requiring discussion and mutual questioning

The most important official judgment criteria to remember:

Use subagents when you need fast, focused workers to report results. Use agent teams when teammates need to share findings, challenge each other, and self-coordinate.

There is also a more straightforward, earthy method: Do these "workers" need to communicate with each other? If not (each checks on their own, summarizes after checking), use a subagent, which is cheap; if yes (communicating while working, nitpicking each other), then use agent teams.

💡 One-sentence summary: A subagent is a temp runner—works independently, reports only to you; agent teams are a crew—teammates talk to each other, you can directly manage every one of them; whether they need to communicate with each other is the watershed for choosing which to use.

---

03 How the team is built: Four key components

For an agent team to run, there are just four parts behind it. Recognize them, and you will understand what is happening on the screen.

Analogy: A real construction crew. There is a foreman (leader), several workers doing the labor (teammates), a task board full of jobs stuck on the wall (task list), and workers can also pass notes to communicate with each other (mailbox). With these four things gathered, the crew can operate.

The architecture table given officially comprises exactly these four pieces:

Component	Role
Team lead	The main session that creates the team, spawns teammates, and coordinates task assignment—this is the one you open first
Teammates	Independent Claude Code instances each taking tasks and working, each with its own context
Task list	A shared work checklist for teammates to claim and complete, with three states: pending / in progress / completed
Mailbox	A system for agents to send messages to each other; teammate messages are automatically delivered to the leader without you needing to poll

A few operational details that beginners most need to know:

Once the leader is set, it cannot be changed. The session that creates the team is the leader for its entire life—you cannot "promote" a teammate to a leader, nor can you transfer leadership. So the session you open first is the true form of your "foreman".

There are two ways for teammates to take tasks. The leader can explicitly assign "this task goes to A"; a teammate can also pick the next unclaimed, unstuck task from the task board to continue working on after finishing their current job (officially called "self-claim"). To prevent two teammates from fighting for the same task simultaneously, the system uses a file lock as a safety net, so they won't collide.

There can be dependencies between tasks. For example, "write tests" has to wait until "implement feature" is completed first. Tasks with uncompleted dependencies cannot be claimed until the dependencies are finished; once dependencies are completed, the stuck task will automatically unlock.

Teammates do not inherit your conversation history. This is where beginners are most likely to stumble—assuming that what the leader knows, the teammates will naturally know, but ending up giving no background when spawning a teammate, leaving it completely confused. The official documentation clearly states: when a teammate is spawned, it loads the same project context as a regular session (CLAUDE.md, MCP, skills), but the conversation history of the leader will not be inherited. So when assigning tasks, the necessary background must be clearly written in the instructions.

💡 One-sentence summary: A team = foreman (leader, set and unchangeable) + workers (teammates, each with independent context) + task board (shared list, supports dependencies, supports self-claim) + mailbox (inter-messaging); remember to provide full background when assigning tasks, teammates don't read your history.

This diagram clarifies the four parts of an agent team: in the middle is you, the leader (foreman), spawning several independent teammates (workers) downwards, each taking a piece of work; below is a shared task board allowing everyone to claim tasks and automatically handle dependencies; there is also direct mailbox connection between teammates—whether messages bypass the leader, and who claims the task, is clear at a glance.

---

04 Using agent view as the "master control screen" to manage multiple sessions

The team is up, but here comes the problem: With several sessions running simultaneously, where do I look?

The answer is agent view—a "master control screen" that lays out all background sessions on one screen, and the command is claude agents.

⚠️ agent view is a research preview version, requiring Claude Code v2.1.139 or higher, and the interface and shortcuts may change with versions.

Analogy: The project progress board on the wall at a construction site. You don't have to go to every workstation to ask "how far along are you", you just look up at the board—which process is underway, which one is stuck waiting for your decision, which one has already been reviewed, it's clear at a glance. claude agents is this board for Claude Code: each session takes up one line, and an icon at the beginning of the line tells you its status using color and animation.

Official status reference, picking the most commonly used ones:

Status	Icon Display	Meaning
Working	Animation	Claude is running a tool or generating a reply
Needs input	Yellow	Waiting for you to answer a question or approve a permission
Completed	Green	The task has been successfully finished
Failed	Red	The task ended with an error

On this board, you can do three things for any line, from light to heavy:

• Peek: Press Space to open a small panel to see the recent output of this session, or what problem it is currently stuck on—most of the time this is enough, you don't need to actually go in. Typing a reply directly in the peek panel and pressing Enter to send it also doesn't require going in.
• Reply: You can reply right in the peek panel. If it throws a multiple-choice question, you can just press number keys to select.
• Attach: Press Enter or → to drill down into the full conversation of this session, which is exactly the same as opening a Claude session standalone normally. Press ← on an empty input box to exit back to the board.

There is a particularly convenient design: These background sessions keep running without any terminal being kept open. An independent supervisor process hosts them in the background—even if you close the agent view, close this shell, or even open a new session, they all continue working. When you come back and open claude agents, they are still there.

You can entirely use claude agents as the main entry point instead of claude: come in and throw a few independent tasks into the input box at the bottom of the board first (pressing Enter after typing each prompt spawns a new session running in parallel), then go do whatever you need to do, and come back to process when a line turns yellow (needs you) or green (finished). This is so much cleaner than opening seven or eight terminal windows and switching back and forth.

💡 One-sentence summary: claude agents is the "master control screen" for managing multiple sessions—one line per session, check color to know status; Space to peek, Enter to drill in, ← to exit out; sessions keep running in the background, no need to keep the terminal open constantly to monitor.

---

05 Commanding teammates in the team: Assign tasks, switch people, ask for plans

The above is the general management method for "multi-sessions". Back to agent teams themselves, how do you specifically command this bunch of teammates as a leader? The core is just one sentence: tell the leader what you want in plain language, and it handles coordination, task division, and delegation for you.

To start a team, you don't need to remember any commands, just describe the task and team structure in natural language. The official example that works very well (three roles independent of each other, no need to wait for each other):

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.

Translated to Chinese, you can also say directly: "帮我建一个 agent team 从不同角度探索这个问题：一个负责 UX、一个负责技术架构、一个专门唱反调。" Claude will create the team, spawn teammates according to the angles, let them explore independently, and finally synthesize the findings.

Switching teammates, instructing individually. In in-process (within the same terminal) mode, press Shift+Down to cycle between teammates. Once you switch to a certain teammate, you can directly type to send messages to him—add an instruction, follow up with a question, or ask him to change his approach. Press Enter to enter his session to see details, Escape to interrupt his current turn, and Ctrl+T to toggle the task list. Pressing Shift+Down again after switching to the last teammate will wrap back to the leader.

Note, don't confuse the shortcuts here with the previous section: use ↑/↓ to switch rows in the master control screen for background sessions, while in agent team use Shift+Down to switch teammates. Two sets of shortcuts for two scenarios.

Let teammates produce a plan before taking action. When a task carries risks, you can require a teammate to plan first in a read-only plan mode, and only implement it after you (the leader) approve:

Generate an architect teammate to refactor the authentication module.
Before he changes anything, he must get plan approval first.

After planning, the teammate will send a "plan approval request" to the leader. He will only exit plan mode and start working once you approve it; if you reject it, he will revise based on the feedback and resubmit.

Specify teammate count and model. You can also explicitly state how many you want and what model to use:

Create a team with 4 teammates to refactor these modules in parallel.
Each teammate should use Sonnet.

A key point for saving money that shouldn't be ignored: teammates by default do not follow the leader's /model choice. To change their models uniformly, either specify it in the prompt like above, or go to /config to set the "default teammate model".

Wrap up when done. When the work is finished, ask the leader to clean up the team:

Clean up this team

⚠️ The official documentation repeatedly emphasizes: Cleaning up must be done through the leader, do not let teammates clean up—the team context of teammates might parse incorrectly, leading to resources falling into an inconsistent state. Also, before cleaning up, you must first shut down teammates that are still running, otherwise the leader will fail to clean up if it detects active teammates.

💡 One-sentence summary: Start a team, assign tasks, switch teammates (Shift+Down), ask for plan approval, wrap up and clean up, all command the leader in plain language; remember three rules—teammate models must be specified separately, background must be provided fully in instructions, clean up only goes through the leader.

---

06 Should you use a team: Don't break it down just for the sake of it

Learning up to this point, you might be eager to break everything down to run as a team. Hold on—this is exactly the continuation of the counter-intuitive iron rule when talking about subagent in Post 23: more tasks doesn't mean it's better to break them down.

Agent teams have tangible costs, and they are heavier than a subagent:

First, it burns a lot of tokens. Each teammate is a complete, independent Claude instance with its own context. Several teammates mean several sets of tokens burning. The official documentation states plainly: for daily tasks, a single session is more cost-effective; only tasks like research, review, and new features that can truly benefit from parallelism are worth the extra tokens.

Second, coordination itself has overhead. The more teammates there are, the more inter-communication, task coordination, and potential conflicts there will be. Past a certain point, adding more people will not proportionally speed things up—three focused teammates can often outperform five scattered teammates.

I have organized "whether it's worth breaking down" into a comparison chart, follow it to see where you fit:

Scenario	Break into team or not
Modifying frontend / backend / testing three layers in parallel, independent of each other	✅ Break it, each taking a layer is perfect
A bug with unknown root cause, want to use several competing hypotheses to investigate in parallel	✅ Break it, teammates falsifying each other converges faster
Multiple people reviewing a PR in parallel (security / performance / test coverage one person each)	✅ Break it, each using a set of non-overlapping filters
A sequence of steps with sequential dependencies (B can only be done after A is finished)	❌ Don't break, serial work is smoother in a single session
Several teammates need to modify the same file	❌ Don't break, two people editing the same file will overwrite each other
Just a casual small task	❌ Don't break, coordination overhead costs more time than saved

The official documentation also provided two very practical pieces of advice for getting started, allowing beginners to avoid pitfalls by following them:

Start with tasks that don't write code, like "research / review". Review a PR, investigate a library, debug an issue—these tasks have clear boundaries and don't involve writing code. They let you experience the value of parallel exploration without bringing about the bunch of coordination troubles from parallel code writing. My own first time using agent teams was to review a PR: three teammates focused on security, performance, and test coverage respectively. No one modified files throughout the process, naturally there were no conflicts, and it felt great watching the findings pop up one by one—only after the experience went smoothly did I dare push towards "parallel code modification". Don't do what I did later, acting on impulse and directly telling three teammates to modify three adjacent files in parallel. As a result, the changes fought with each other, and just sorting out the conflicts was slower than honestly working serially in a single session.

Start team size from 3-5. This range works well for all kinds of tasks—parallelism is there, and coordination doesn't spiral out of control. If you really need to expand, only do so when "the work can truly benefit from more people doing it simultaneously".

💡 One-sentence summary: Agent teams burn more tokens and have heavier coordination than subagent, break them down only when you can "truly benefit from parallelism"; absolutely don't break down mutual dependencies, modifying the same file, or casual small tasks; for beginners, starting with "non-coding research / review" + "3-5 people" is the safest.

---

07 Hands-on: Enable the feature, start a three-person team running

Just watching and not practicing is empty talk. Next, I will guide you from scratch to enable Agent teams, and start a three-person team to work in parallel on the simplest task. The entire process does not depend on any complex project.

Prerequisite: Take a look with claude --version, it must be v2.1.32 or higher; if not enough, do claude update first.

Step 1: Enable experimental feature

Agent teams are disabled by default. First, turn on the switch in user-level settings. Edit ~/.claude/settings.json (create it if it doesn't exist), and add this env section:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Expected: This env configuration is in the file. This is the official specified method to enable it—setting the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1.

Step 2: Create a toy directory and enter it to start Claude (Mac / Linux)

mkdir team-demo
cd team-demo
claude

Windows users: just type mkdir, cd identically, then claude.

Expected: The Claude Code welcome screen appears, with an input box at the bottom.

Step 3: Start a three-person team in plain language

Type in the input box (this is "describe task + team structure" to let the leader assemble the team itself):

Help me create an agent team to research "whether a personal blog should choose a static site or a dynamic site" from three different angles:
One teammate only argues for "choosing a static site", one only argues for "choosing a dynamic site",
and one plays devil's advocate specifically to nitpick the first two solutions. Let them each provide their conclusions.

Expected: Claude will first tell you it is going to create a team, spawn three teammates (one for each angle), and ask for your confirmation. It won't create a team without saying hello—the official documentation explicitly states "teams will not be created without your approval". After confirmation, the three teammates will spin up one after another, each starting to work in their own context.

Step 4: Use Shift+Down to switch to a teammate and take a look

Once the team is running, the leader's terminal will list all teammates and the work they are doing. Press Shift+Down to cycle switch to a teammate, and you can directly send messages to him. For example, switch to the "devil's advocate" one and add:

Also help me nitpick from the angle of "maintenance cost"

Expected: This message goes straight to that teammate (without being relayed through the leader), and he will incorporate "maintenance cost" and continue nitpicking. Pressing Shift+Down again after switching to the last teammate will wrap back to the leader—back to the leader, you can coordinate the big picture again.

Step 5: Wrap up and clean up

After the research is done, go back to the leader and let it wrap up:

Help me clean up this team

Expected: The leader will first confirm that teammates have stopped, and then delete the shared team resources. If there are still running teammates, the cleanup will fail—at this time, first ask the leader to shut down the teammates ("let those teammates shut down") before cleaning up. Remember that official rule: Cleanup always goes through the leader, don't let teammates clean up.

By running through these five steps, you have personally walked the complete chain of "enable → assemble team → work in parallel → switch teammate to direct chat → wrap up". Any subsequent usage of agent teams is essentially just swapping tasks and teammate roles on this chain.

💡 One-sentence summary: Turn on the switch in env inside settings.json → ask leader to assemble team in plain language → Shift+Down switch teammate for direct chat → leader wraps up and cleans up; personally running through this chain is more useful than memorizing ten shortcuts.

---

08 Summary

In this post, we smoothed out Claude Code's "multi-agent collaboration" from start to finish—you upgraded from a worker personally on the field to a foreman directing a crew.

Reviewing the core points strung together:

What you want to do	What to use	Key points
Break through single session memory + serial ceiling	Agent teams	Multiple peer sessions in parallel, you act as leader to assign tasks
Distinguish from subagent	See "if you need to communicate"	Use team if communication and mutual questioning are needed, otherwise subagent is cheaper
Manage multiple parallel sessions	claude agents (agent view)	One line per session, check color for status, Space to peek
Switch teammates for direct chat in a team	Shift+Down	Wrap around back to leader; don't confuse with ↑/↓ for switching rows on board
Judge whether to break it down	A "whether it's worth it" comparison table	Mutual dependencies, modifying the same file, small tasks absolutely don't break down

You should now be able to: Clearly state what Agent teams solves, how it differs from a subagent, use claude agents, this master control screen, to monitor multiple parallel sessions, command the leader to assemble teams and assign tasks in plain language, and be clear on "when is it worth breaking down, and when shouldn't you break down just for the sake of it". This set of "acting as a foreman" abilities is your confidence in truly parallelizing large tasks without letting costs run out of control.

But honestly speaking—it is still experimental after all, the interface and shortcuts change with versions, and a single session is still sufficient for 90% of daily tasks. Keep it in your toolbox as an "accelerator artifact for big jobs", and don't force small tasks to break down right away.

---

Next up 30 "How to choose features: CLAUDE.md vs Skill vs Hook vs MCP vs Subagent"—Up to this post, you have learned a huge stack of Claude Code moves: CLAUDE.md, Skill, Hook, MCP, Subagent, Agent teams. But learning a lot doesn't mean using them correctly. The real difficulty is when facing a specific requirement, which one should you pull out? In the next post, I will give you a decision table that lays out the "applicable boundaries" of these features on one page—after reading it, you will never suffer from the choice difficulty of "what should I use" when facing a requirement again.

---

Recommended Reading

• CLAUDE.md Usage Guide: Write Project Rules into Its Memory
• CLI Reference Manual: Commands and All Flags
• Agent SDK: Bring Claude Code's Capabilities into Your Own Programs