Agent Teams — Multi-Session Orchestration

🧠 Knowledge Check

Q: What's the key architectural difference between subagents and agent teams?

Communication model. Subagents can only report back to the parent session (one-way). Agent team teammates can message each other directly and coordinate through a shared task list. Each teammate is a fully independent Claude Code session. This makes teams better for collaborative work but significantly more expensive.

Enable Agent Teams

Agent teams are disabled by default. Enable them:

Via Settings

Via Environment

Starting a Team

Just describe what you need in natural language:

Claude creates the team, spawns teammates, coordinates work, and synthesizes findings.

Display Modes

In-Process (Default)

All teammates run inside your main terminal:

Split Panes

Each teammate gets its own terminal pane. Requires tmux or iTerm2.

🧠 Knowledge Check

Q: How do you interact with individual teammates in the in-process display mode?

Use Shift+Up/Down to select a teammate, then type to message them directly. Press Enter to view their full session, Escape to interrupt their turn, and Ctrl+T to toggle the shared task list. Each teammate is a full Claude Code session you can interact with independently.

Shared Task List

The shared task list coordinates work across the team:

Task States

Tasks can have dependencies — a pending task with unresolved dependencies can't be claimed until those dependencies are completed.

Assignment Modes

• Lead assigns: Tell the lead which task to give to which teammate
• Self-claim: After finishing a task, teammates pick up the next unassigned, unblocked task

Task claiming uses file locking to prevent race conditions.

Delegate Mode

Prevents the lead from implementing tasks itself — restricts it to coordination-only tools:

• Spawn/message/shutdown teammates
• Manage the task list
• No file edits, no bash commands

Press Shift+Tab to cycle into delegate mode during a session.

Pro Tip: Delegate mode forces better architecture. When the lead can't implement, it focuses on clear task decomposition and quality review.

✍️ Recall Exercise

Fill in the blanks:

• Enable agent teams: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=___
• Toggle the task list: Ctrl+___
• Delegate mode restricts the lead to ___-only tools

• 1
• Ctrl+T
• coordination

Quality Gates with Hooks

TeammateIdle Hook

Runs when a teammate is about to go idle. Exit 2 to send them back to work:

TaskCompleted Hook

Runs when a task is marked complete — validate the work:

🧠 Knowledge Check

Q: A TeammateIdle hook exits with code 2. What happens?

The teammate is sent back to work instead of going idle. Exit code 2 blocks the idle action and feeds the stderr message back as feedback. This is how you enforce quality gates — if a teammate hasn't run tests or their code doesn't lint, the hook sends them back to fix it.

Team Lifecycle

Shut Down a Teammate

The teammate can approve (exits gracefully) or reject with an explanation.

Clean Up the Team

This removes shared team resources. Active teammates must be shut down first.

Cost Considerations

Agent teams are expensive — each teammate is a separate Claude instance:

1. Use Sonnet for teammates — good balance of capability and cost
2. Keep teams small — 2-3 teammates, not 6
3. Keep spawn prompts focused — everything adds to context
4. Clean up when done — idle teammates still consume tokens

✍️ Recall Exercise

Fill in the blanks:

• To select teammates in-process mode: Shift+___/Down
• Task states flow: Pending → ___ → Completed
• Teammates need ___ for split panes

• Shift+Up/Down
• In Progress
• tmux (or iTerm2)

🔨 Try It Yourself

1. Enable agent teams:

   export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
   

2. Start a Claude session in a project
3. Ask:

   Create a team of 2 to analyze this project:
   - Teammate 1: analyze the architecture and suggest improvements
   - Teammate 2: find potential bugs or security issues
   Use Sonnet for both teammates.
   

4. Use Shift+Up/Down to switch between teammates
5. Use Ctrl+T to view the task list
6. When done, ask the lead to clean up the team

Reflection: How does the team's output compare to asking a single session to do both tasks?

🤔 What Would You Do?

Scenario: You need to build a new feature with a React frontend, Express API, and database migration. The components are somewhat interdependent (the frontend needs to know the API contract, the API needs to know the schema).

Use agent teams with plan approval:

The key is using plan approval and task dependencies to handle the interdependencies. The backend designs first, frontend references the design, tests cover both.

📋 Key Takeaways (Review These Tomorrow)

Next up: Headless / SDK Mode & CI/CD → — Run Claude Code non-interactively in scripts and GitHub Actions.