Agent Teams & Parallel Sessions

Topics

• Subagents: 6 built-in types and how they work
• Foreground vs background subagents
• Custom subagents in .claude/agents/
• Agent frontmatter and persistent memory
• Agent Teams: multi-agent collaboration
• Display modes: in-process vs tmux
• Orchestration patterns: fan-out, pipeline, supervisor

Activities

• Create a custom subagent with persistent memory enabled
• Use `--agents` CLI flag to define session-level subagents
• Test foreground vs background subagents (Ctrl+B)
• Resume a completed subagent to continue its work
• Set up an agent team with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
• Assign frontend and backend to separate agents
• Use headless mode for automated testing
• Build an orchestration workflow for your capstone project

Skills You'll Gain

Subagents (built-in + custom), agent teams, persistent memory, parallel sessions, headless mode, orchestration

Learning Objectives

By the end of this week, you will be able to:

1. Explain what subagents are and how Claude Code uses them automatically
2. Create custom subagents with specific tools, models, and permissions
3. Configure persistent memory for subagents that learn across sessions
4. Set up and orchestrate an agent team for a multi-part project
5. Choose the right orchestration pattern for different types of work

Lesson

What Are Subagents?

When you give Claude Code a complex task, it often breaks it into smaller pieces and delegates them to subagents — specialized workers that handle specific subtasks. Think of it like a manager (Claude) delegating work to team members (subagents).

Claude Code has 6 built-in subagent types:

Claude automatically chooses which subagent to use based on the task. You can also explicitly request one: "Use an Explore agent to find all API endpoints in this project."

Foreground vs Background Subagents

By default, subagents run in the foreground — you see their work in real-time. But you can background a running task with Ctrl+B, which lets you continue working while the subagent finishes in the background.

Background subagents:

• Run independently without blocking your main session
• Have pre-approved permissions (asked upfront)
• Auto-deny anything not pre-approved (no interactive permission prompts)
• Report results when finished

Custom Subagents

You can create project-specific agents in .claude/agents/ or personal agents in ~/.claude/agents/. A custom agent is a markdown file with frontmatter:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools: ["Read", "Glob", "Grep"]
model: claude-sonnet-4-5-20250929
permissionMode: plan
maxTurns: 20
memory: project
---

# Code Reviewer Agent

You are a code review specialist. When given code to review, you should:
1. Check for security vulnerabilities
2. Identify performance issues
3. Suggest improvements to readability
4. Verify test coverage for changed code

Key frontmatter fields:

Persistent Agent Memory

When you set memory: project, the agent remembers information across sessions. It learns patterns, preferences, and project-specific knowledge over time.

For example, a code-reviewer agent with persistent memory might learn:

• "This project uses camelCase for variables and PascalCase for components"
• "The team prefers explicit error handling over try-catch blocks"
• "Tests should use the AAA pattern (Arrange, Act, Assert)"

Agent Teams (Experimental)

Agent teams enable multi-agent collaboration where multiple Claude instances work together on a project. One agent leads, others implement.

Enable with:

$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Display modes:

• in-process — All agents share one terminal window. You see interleaved output.
• tmux — Each agent gets its own terminal pane. Requires tmux installed.

How teams work:

┌──────────────────────┐
│     Team Lead         │
│  (delegate mode)      │
│                       │
│  Creates tasks,       │
│  assigns teammates,   │
│  reviews results      │
└──────────┬───────────┘
           │ assigns tasks
    ┌──────┴──────┐
    ▼             ▼
┌─────────┐ ┌─────────┐
│Frontend │ │Backend  │
│ Agent   │ │ Agent   │
│         │ │         │
│ Builds  │ │ Builds  │
│ UI      │ │ API     │
└─────────┘ └─────────┘

The team lead uses delegate permission mode — it can only coordinate, not modify files directly. Teammates handle implementation.

Direct teammate messaging: Use Shift+Up/Down to switch between teammates and send messages.

Orchestration Patterns:

1. Fan-out — The lead assigns independent tasks to multiple agents simultaneously (e.g., "Agent A: build the UI. Agent B: build the API. Agent C: write tests.")

2. Pipeline — Work flows from one agent to the next (e.g., "Agent A designs the schema → Agent B implements it → Agent C tests it.")

3. Supervisor — The lead reviews each agent's work before it proceeds (e.g., "Agent A: implement feature. Lead: review. Agent A: fix issues. Lead: approve.")

Practice Exercises

Exercise 1 (Guided): Create a Custom Subagent

1. Create .claude/agents/researcher.md:

---
name: researcher
description: Research questions about the codebase
tools: ["Read", "Glob", "Grep"]
model: claude-haiku-4-5-20251001
permissionMode: plan
maxTurns: 15
memory: project
---

# Researcher Agent

You explore the codebase to answer questions. Use Glob to find files,
Grep to search content, and Read to examine files in detail.
Provide concise, factual answers with file paths as references.

1. Test it: Ask Claude to "use the researcher agent to find all API routes in this project"
2. Check that it runs with the Haiku model and only reads files (no modifications)

Verification: The researcher agent finds and lists API routes without modifying any files. Memory is stored in .claude/projects/.

Exercise 2 (Independent): Agent Team Workflow

Goal: Set up a 3-agent team for a project task:

1. Enable agent teams: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
2. Start Claude with tmux mode: claude --teammate-mode tmux
3. Assign tasks: "Create a frontend agent for UI work and a backend agent for API work"
4. Give each agent a task from your project
5. Monitor both agents working in parallel

Hints:

• The team lead should use delegate mode
• Each teammate should have appropriate tools (frontend: Edit, Write; backend: Edit, Write, Bash)
• Use Shift+Up/Down to communicate with teammates

Verification: Both agents complete their tasks. The combined work is committed to Git.

Exercise 3 (Challenge): Orchestrated Build

Design and execute an orchestrated workflow using agent teams:

1. Define 3 agents with different specializations
2. Create a task list with dependencies (task B depends on task A)
3. Run the workflow using the pipeline pattern
4. Monitor progress using TeammateIdle hooks
5. Review and merge all work

Document the orchestration in a docs/agent-workflow.md file.

Self-Assessment Quiz

1. What are subagents, and how does Claude Code decide which one to use?

2. What does memory: project do in a custom agent's frontmatter?

3. Explain the difference between the delegate permission mode and normal permission modes.

4. What are the three orchestration patterns, and when would you use each?

Answers:

1. Subagents are specialized workers that Claude Code delegates subtasks to. Claude automatically chooses based on the task: Explore for searching code, Plan for designing strategies, general-purpose for complex multi-step work, Bash for command execution. You can also explicitly request a specific type.

2. memory: project enables persistent memory scoped to the current project. The agent remembers information (patterns, preferences, decisions) across sessions. This memory is stored in .claude/projects/ and loaded automatically in future sessions.

3. delegate mode restricts the agent to coordination only — it can assign tasks and communicate with teammates but cannot directly modify files or run commands. Normal modes (like acceptEdits or dontAsk) allow direct file modifications. The team lead uses delegate to orchestrate, while teammates use normal modes to implement.

4. Fan-out: Assign independent tasks to multiple agents simultaneously. Use when tasks do not depend on each other. Pipeline: Work flows from one agent to the next. Use when each step depends on the previous step. Supervisor: The lead reviews each agent's work before proceeding. Use when quality control is critical.

Claude Agent SDK

• Released alongside Sonnet 4.5, the Claude Agent SDK enables building custom agents with Claude.
• Allows developers to build custom agents with tool use, define agent workflows, and integrate Claude as an autonomous agent into existing applications.
• Relevant to agent teams and parallel session workflows covered this week.
• References: Announcement | Agent SDK docs

Agent Teams Updates (Feb 2026)

• Agent teams research preview launched — multi-agent collaboration feature requiring CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (v2.1.32). Note: this is token-intensive.
• tmux integration fixed for agent teammate sessions to properly send and receive messages (v2.1.33)
• TeammateIdle and TaskCompleted hook events added for orchestrating multi-agent workflows (v2.1.33)
• Agent teams crash fix when settings change between renders (v2.1.34)
• Sandbox security fix preventing excluded commands from bypassing Bash ask permission rules (v2.1.34)

Exercise:

• Enable agent teams with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and try a multi-agent task
• Set up a TeammateIdle hook to monitor agent collaboration
• Test agent teams in a tmux session