Video 20.2: Enabling and Configuring Agent Teams

Course: Claude Code - Parallel Agent Development Section: S20 - Agent Teams Video Length: 4 minutes Presenter: Daniel Treasure

Opening Hook

Agent Teams are currently experimental, which means we need to explicitly enable them. In this video, you'll learn exactly how to flip the switch—whether you prefer environment variables or configuration files—and verify everything is working.

Key Talking Points

What to say:

Why It's Experimental - Agent Teams is an experimental feature in Claude Code - This isn't a limitation—it's Anthropic being transparent about stability - You can use it in production, but know that the feature is still evolving - Enabling it is intentional: you decide when you're ready

The Feature Flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS - Single environment variable controls everything - When set to 1 (or "true"), Agent Teams functionality becomes available - Without it, the spawn commands won't work—Claude will treat it as a regular request

Two Ways to Enable

Environment Variable Approach (temporary, one session)
Set before launching Claude Code
Persists only for that terminal session
Good for testing or temporary use
Command: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Settings.json Approach (persistent, all sessions)
Stored in ~/.claude/settings.json
Applies every time you launch Claude Code
Best for regular team use
Add field: "experimental_agent_teams": true

The settings.json File - Located at ~/.claude/settings.json - Controls many Claude Code behaviors - You can manage feature flags here - Human-readable, easy to toggle on/off - Survives across sessions and machine restarts

Teammate Display Mode Configuration - Setting: "teammate_mode" in settings.json - Three options: "in-process", "tmux", "auto" - in-process: all teammates in one terminal, navigate with Shift+Up/Down - tmux: split panes, see all teammates simultaneously (requires tmux session) - auto: intelligently chooses tmux if available, otherwise in-process - Can also specify with CLI flag: claude --teammate-mode tmux

Verification - How to confirm the feature is enabled - Testing that it actually works - Knowing what to expect vs what's a problem

What to show on screen:

Filesystem: navigate to ~/.claude and show the settings.json file exists (or create it)
Open settings.json in an editor and show the configuration
Add/enable the experimental flag
Show the terminal command for the env var approach
Restart Claude Code and verify the team spawn now works
Show error message that occurs WITHOUT the flag (then enable and try again)

Demo Plan

0:00-0:45 - The Settings.json File - Open file manager or terminal and navigate to ~/.claude - Show that settings.json might already exist (if Claude Code has been used before) - Open it in a text editor (VS Code, nano, or whatever is convenient) - Narrate: "This is the global configuration for Claude Code" - Show other settings that might already be there (model preferences, API key, etc.)

0:45-1:30 - Enable the Feature Flag - Scroll to or add the line: "experimental_agent_teams": true - Explain that this one boolean controls whether teams are available - Show what it looks like when false (teams won't work) - Toggle it to true and save the file - Narrate: "With this enabled, Claude Code now knows we want to use teams"

1:30-2:15 - Test with Environment Variable Method - Open a fresh terminal - Show the command: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 - Explain this is the temporary, session-based approach - Launch Claude Code with this env var set - Verify teams work with this approach - Narrate: "This is useful if you want to test teams without changing your persistent config"

2:15-3:00 - Teammate Display Mode - Go back to settings.json - Add or show the "teammate_mode" setting - Explain the three options briefly - Show the value: "auto" is the safe default - Comment: "We'll dive deeper into tmux setup in a later video, but for now, 'auto' or 'in-process' works great" - Optional: show what the setting looks like in config

3:00-3:30 - Verification and Diagnostics - Back in a Claude Code session with teams enabled - Try spawning a simple team: "Create a team with 2 teammates" - Show that it works (teammates appear) - If it fails, show the error message and explain what to check - Narrate: "If you see this error, verify the flag is set correctly and Claude Code has restarted"

3:30-4:00 - Lead-out - Confirm that teams are now ready to use - Next video will focus on the Team Lead role and delegation modes - Brief preview: "We'll also learn how to control what the lead can and can't do"

Code Examples & Commands

Environment Variable Approach

# Set it for this session only
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Then launch Claude Code
claude

# Or in one line:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Settings.json Configuration (Full Example)

{
  "api_key": "sk-...",
  "default_model": "claude-opus-4-6",
  "experimental_agent_teams": true,
  "teammate_mode": "auto",
  "timeout_seconds": 30,
  "auto_save": true
}

Adding Just the Flag

{
  "experimental_agent_teams": true
}

CLI Flag Method (Alternative)

# You can also pass it as a CLI argument
claude --experimental-agent-teams

# Or with teammate mode specified
claude --teammate-mode tmux --experimental-agent-teams

Checking What's Enabled (in Claude Code)

# After starting Claude Code, you can ask:
> What feature flags are currently enabled?
# Claude will report back on the configuration

Gotchas & Tips

Gotchas: - The setting is experimental_agent_teams (with underscore), not experimentalAgentTeams (camelCase). JSON is case-sensitive. - Environment variable is all-caps and also with underscore: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, not EXPERIMENTAL_AGENT_TEAMS - If you set the env var but not the settings.json flag, only that session will have teams enabled - Changes to settings.json don't take effect until you restart Claude Code - If you get a "feature not available" error, first check that teams are enabled and Claude Code has restarted

Tips: - For most developers, set it in settings.json once and forget about it - Use the env var approach for quick testing or CI/CD scripts - Start with "teammate_mode": "auto" to let Claude Code pick the best display strategy for your terminal - If you ever want to disable teams, just set the flag to false or remove the line entirely - Keep your settings.json readable: comments are allowed in JSON5 format if Claude Code supports it (check docs)

Lead-out

Now that teams are enabled, you're ready to learn about the Team Lead role and how to control what you—as the lead—can and cannot do. In the next video, we'll explore Delegate Mode and how to step into a pure coordination role when your team is ready to work independently.

Reference URLs

Claude Code Settings Documentation: https://www.anthropic.com/claude-code/docs/configuration
Environment Variables in Claude Code: https://www.anthropic.com/claude-code/docs/env-setup
tmux Documentation: https://github.com/tmux/tmux/wiki
Settings File Format: https://www.anthropic.com/claude-code/docs/settings-reference

Prep Reading

Review the Claude Code configuration docs for any settings you might want to customize
Check if you use tmux on your system (if you do, familiarize yourself with split pane basics)
Understand that experimental features may change in future releases
Prepare a simple test team scenario in your head (what would you build with 2-3 teammates?)

Notes for Daniel

This is a "plumbing" video—it's not flashy, but it's essential. Keep the pacing brisk; settings are straightforward. The goal is confidence: viewers should feel like they've checked off "teams enabled" and are ready to move on. Don't spend too much time on alternative methods; mention them but focus on the recommended approach (settings.json for persistence). If you make a typo in settings.json and the demo fails, use it as a teaching moment: "See? JSON is strict. Let's fix it." This builds credibility.

Terminal work can feel slow on video. Have the text editor open before recording, or edit the file quickly and clearly so it doesn't feel like dead air. Show the save action explicitly so viewers know the settings took effect.

Quick Reference