Work with an agent team without losing control

The one idea

Use an agent team when parallel discussion changes the quality of the answer. A team has one lead session, separate teammate sessions, a shared task list, and direct teammate messaging. This is heavier than a normal session or a subagent, so start with review, research, or competing hypotheses before asking multiple teammates to edit code.

Enable the feature

Put the environment variable in Claude Code settings when you want the feature available across sessions:

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

The default display mode is in-process, which keeps teammates inside the main terminal. Split panes are optional and require tmux or iTerm2 setup.

The control loop

The key move is naming teammates and giving each one a different lens. Names make follow-up prompts precise. Boundaries reduce overlap, file conflicts, and duplicated investigation.

Your first safe team

1. Start with read-only work

   Use a review or research task first. This teaches coordination without mixing parallel edits, permission prompts, and merge cleanup.

2. Spawn named teammates

   Give the lead the task, the teammate names, and the boundaries in one prompt:

   I want to evaluate whether this repository needs dependency cleanup.
   Spawn three teammates named mapper, risk, and verifier.
   
   mapper: inspect package structure, scripts, and dependency surfaces.
   risk: look for upgrade, security, or compatibility risks.
   verifier: find the safest commands to verify changes later.
   
   Do not edit files. Have teammates share findings with each other,
   challenge weak assumptions, and wait until all three are done.
   Then synthesize a short plan with clear next steps.

3. Watch the agent panel

   In in-process mode, use Up and Down to select a teammate and Enter to view its transcript. Press Esc to interrupt a selected teammate's current turn if it is going off track.

4. Steer by name

   Message one teammate directly when the correction is local: Ask verifier to include commands that do not require network access. Send one message per teammate when everyone needs the same new constraint.

5. Wait before acting

   If the lead starts implementing before teammates finish, tell it: Wait for your teammates to complete their tasks before proceeding. A team is only worth the overhead if you let the independent work land before synthesis.

6. Shut down cleanly

   When a named teammate is no longer needed, ask the lead to shut it down: Ask the risk teammate to shut down.

Use the right delegation tool

Safety rules

• Agent teams use more tokens because each teammate is a separate Claude instance with its own context window.
• Teammates do not inherit the lead's conversation history. Include task-specific details in the spawn prompt.
• Teammates start with the lead's permission settings, but they cannot approve permission prompts for you.
• For implementation work, assign separate files or modules. Two teammates editing the same file can overwrite each other.
• In-process teammates are not restored by /resume or /rewind. After resuming, spawn fresh teammates if needed.
• Only the lead can manage the team. A teammate cannot spawn its own nested team.

Practice: retrieve the control points

Type the missing command, setting, or phrase from memory. These checks focus on the parts that keep a team easy to steer.

Primary source

• Read the official page next: Orchestrate teams of Claude Code sessions. Focus on Enable agent teams, Start your first agent team, Control your agent team, Best practices, Troubleshooting, and Limitations.