Claude Code Agent Teams

Appearance

SOP-001: Enable Agent Teams ​

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

Fresh 🌱

Enable experimental agent teams in Claude Code so you can create and manage multiple coordinated sessions.

Overview ​

Agent teams are disabled by default. This SOP walks you through enabling them via settings.json or environment variables.

Prerequisites ​

  • Claude Code CLI installed
  • Text editor for configuration
  • Access to shell/terminal

Decision Tree ​

Step-by-Step Instructions ​

  1. Open settings.json

    bash
    # On macOS/Linux
open ~/.claude/settings.json

# On Windows (PowerShell)
notepad $env:USERPROFILE\.claude\settings.json

  2. Add or update the env section

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

  3. Save the file

    • Make sure JSON is valid (no trailing commas)
    • Close your editor

  4. Restart Claude Code

    bash
    # Kill any running Claude Code sessions
pkill -f "claude"

# Start fresh
claude

Option 2: Enable via Environment Variable ​

  1. Set temporary environment variable (current shell only)

    bash
    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

  2. Set permanent environment variable

    macOS/Linux (add to ~/.bash_profile or ~/.zshrc):

    bash
    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

    Then reload:

    bash
    source ~/.zshrc  # or ~/.bash_profile

    Windows (PowerShell):

    powershell
    [Environment]::SetEnvironmentVariable("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "1", "User")

    Restart your shell after this change.

Verification Checklist ​

✓ Confirm settings.json has the env section (or env var is set)

bash
cat ~/.claude/settings.json | grep CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

✓ Start Claude Code

bash
claude

✓ Check that agent teams are available Type a message asking Claude to create a team:

Create an agent team with 2 teammates to help me explore architecture options for a CLI tool.

✓ Verify teammates appear

  • In in-process mode: teammates appear in your terminal
  • In split panes mode: teammates get their own panes

✓ Success indicators:

  • Claude mentions "spawning teammates"
  • You see a task list appear
  • You can switch between agents (Shift+Up/Down)

Troubleshooting ​

Q: I don't see teammates appearing A:

  1. Check that the setting is actually saved: cat ~/.claude/settings.json
  2. Restart Claude Code completely: pkill -f claude then claude
  3. Ask Claude explicitly: "Create an agent team with 3 teammates"

Q: Getting "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not defined" A:

  1. Verify settings.json file exists: ls ~/.claude/settings.json
  2. Check JSON syntax: ensure no trailing commas
  3. Try restarting multiple times (sometimes takes multiple restarts)

Q: Split panes mode not working A:

  1. tmux not installed: brew install tmux
  2. For iTerm2: install it2 CLI: pip install it2
  3. Enable Python API: iTerm2 → Settings → General → Enable Python API

Q: Settings.json file doesn't exist A:

  1. Create directory: mkdir -p ~/.claude
  2. Create file: touch ~/.claude/settings.json
  3. Add content:
    json
    {
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

See Also ​