Claude Code Agent Teams

Appearance

SOP-002: Create Your First Team ​

ID: SOP-002 | Version: 1.0 | Status: Current | Date: 2026-02-12

Fresh 🌱

Spawn your first agent team by describing the task and team structure you want in natural language.

Overview ​

Claude Code handles all team creation automatically. You provide the task description and desired team structure, and Claude creates the team, spawns teammates, and coordinates work based on your prompt.

Prerequisites ​

  • Agent teams enabled (SOP-001)
  • Claude Code running with experimental feature enabled
  • Clear understanding of the task that needs parallel work

Decision Tree ​

Step-by-Step Instructions ​

Step 1: Start Claude Code with Agent Teams Enabled ​

bash
claude

Verify agent teams are enabled by checking output - should show no errors about experimental features.

Step 2: Describe Your Task in Natural Language ​

Tell Claude what you want a team to accomplish. Include:

  • What they should do
  • How many teammates (optional)
  • What roles or perspectives each should take
  • What models to use (optional)

Example 1: Research Task ​

Create an agent team to explore architecture options for a new CLI tool
that tracks TODO comments. I want:
- One teammate researching user experience considerations
- One teammate analyzing technical architecture approaches
- One teammate playing devil's advocate with critical feedback

Example 2: Code Review Task ​

Spawn 3 reviewers for this TypeScript module. Have them each focus on:
- Security and authentication
- Performance and scalability
- Test coverage and reliability

Example 3: Debugging Task ​

Create 5 teammates to investigate why the app crashes after one message.
Have them form competing hypotheses about the root cause and actively
try to disprove each other's theories. Update a document with findings.

Step 3: Wait for Team Initialization ​

Claude will:

  1. Analyze your request
  2. Spawn the requested teammates
  3. Assign initial tasks
  4. Start coordinating work

You'll see:

  • Team configuration created
  • Teammate sessions spawned
  • Shared task list initialized
  • Progress messages from Claude

Step 4: Observe Initial Setup ​

Claude will show you:

  • Number of teammates spawned
  • Their assigned roles/focus areas
  • Initial task breakdown
  • Coordination plan

Example output:

✓ Team 'research-cli-tool' created
✓ Spawned 3 teammates:
  - UX Research Specialist
  - Technical Architect
  - Devil's Advocate Critic

✓ Created task list with 9 items
✓ Beginning investigation...

Step 5: Monitor and Interact ​

Switch between teammates (in-process mode):

Shift+Up/Down arrows to cycle between agents

Message a specific teammate:

Tell the security reviewer: "Focus on JWT token handling"

View task list:

Press Ctrl+T to show/hide task list

Get team status:

Show me the current status of all teammates

Verification Checklist ​

✓ Team created successfully

  • See "Team [name] created" message
  • No error messages about spawning

✓ Teammates visible

  • In-process: can cycle with Shift+Up/Down
  • Split panes: each teammate has visible pane

✓ Task list initialized

  • Press Ctrl+T shows task list
  • Tasks show pending/in-progress/completed status

✓ Communication working

  • Teammates messaging appears automatically
  • Can see cross-team discussion
  • Messages arrive without manual polling

✓ Lead responding

  • Claude is coordinating work
  • Synthesizing findings
  • Asking teammates for clarification

Troubleshooting ​

Q: Claude didn't create a team A:

  1. Task may be too simple for parallelization
  2. Try more explicit request: "Create an agent team with 3 teammates to..."
  3. Make sure request describes team structure clearly

Q: Teammates not appearing A:

  1. Team may be running in background. Press Shift+Down to cycle
  2. Spawn may be slow. Give it 10-15 seconds
  3. Check Claude output for error messages

Q: "Permission denied" errors A:

  1. Pre-approve common operations: adjust permission settings
  2. Or use --dangerously-skip-permissions flag

Q: Task list not showing A:

  1. Press Ctrl+T to toggle visibility
  2. Verify you're in the lead's session (not a teammate)

Q: Not enough tasks A:

  1. Tell Claude: "Break this work into smaller tasks, aim for 5-6 per teammate"
  2. Claude will replan task distribution

Next Steps ​

After team is created:

  1. Monitor and steer work
  2. Assign specific tasks
  3. Review and synthesize findings
  4. Clean up when done

See Also ​