team-management

Team Management

Create, manage, and shut down agent teams. This skill covers team lifecycle from creation through cleanup.

Experimental: Agent teams are disabled by default. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in your settings.json or environment.

Related skills:

• Orchestrating - Primitives overview and quick reference
• Task System - Managing work items and dependencies
• Messaging - Communication between agents
• Agent Types - Choosing the right agent for each role
• Spawn Backends - How teammates run (in-process, tmux, iTerm2)
• Error Handling - Troubleshooting and recovery

---

Core Architecture

A team consists of:

• Leader (you) - Creates team, spawns workers, coordinates work
• Teammates (spawned agents) - Execute tasks, report back
• Task List - Shared work queue with dependencies
• Inboxes - JSON files for inter-agent messaging

File Structure

~/.claude/teams/{team-name}/
├── config.json              # Team metadata and member list
└── inboxes/
    ├── team-lead.json       # Leader's inbox
    ├── worker-1.json        # Worker 1's inbox
    └── worker-2.json        # Worker 2's inbox

~/.claude/tasks/{team-name}/
├── 1.json                   # Task #1
├── 2.json                   # Task #2
└── 3.json                   # Task #3

Team Config Structure

{
  "name": "my-project",
  "description": "Working on feature X",
  "leadAgentId": "team-lead@my-project",
  "createdAt": 1706000000000,
  "members": [
    {
      "agentId": "team-lead@my-project",
      "name": "team-lead",
      "agentType": "team-lead",
      "color": "#4A90D9",
      "joinedAt": 1706000000000,
      "backendType": "in-process"
    },
    {
      "agentId": "worker-1@my-project",
      "name": "worker-1",
      "agentType": "Explore",
      "model": "haiku",
      "prompt": "Analyze the codebase structure...",
      "color": "#D94A4A",
      "planModeRequired": false,
      "joinedAt": 1706000001000,
      "tmuxPaneId": "in-process",
      "cwd": "/Users/me/project",
      "backendType": "in-process"
    }
  ]
}

---

Two Ways to Spawn Agents

Method 1: Task Tool (Subagents)

Use Task for short-lived, focused work that returns a result:

Task({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

For agents that make code changes, use isolation: "worktree" to give them an isolated git worktree copy. The worktree is automatically cleaned up if no changes are made; if changes are made, the worktree path and branch are returned:

Task({
  subagent_type: "general-purpose",
  description: "Apply patch to codebase",
  prompt: "Implement the described feature changes",
  isolation: "worktree"  // Agent works in an isolated git worktree copy
})

Characteristics:

• Runs synchronously (blocks until complete) or async with run_in_background: true
• Returns result directly to you
• No team membership required
• isolation: "worktree" prevents changes from affecting the main working directory until reviewed
• Best for: searches, analysis, focused research, isolated code edits

Method 2: Task Tool + team_name + name (Teammates)

Use Task with team_name and name to spawn persistent teammates:

// First create a team
TeamCreate({ team_name: "my-project", description: "Working on feature X" })

// Then spawn a teammate into that team
Task({
  team_name: "my-project",        // Required: which team to join
  name: "security-reviewer",      // Required: teammate's name
  subagent_type: "general-purpose",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead.",
  run_in_background: true         // Teammates usually run in background
})

Characteristics:

• Joins team, appears in config.json
• Communicates via inbox messages
• Can claim tasks from shared task list
• Persists until shutdown
• Best for: parallel work, ongoing collaboration, pipeline stages

Key Difference

Aspect	Task (subagent)	Task + team_name + name (teammate)
Lifespan	Until task complete	Until shutdown requested
Communication	Return value	Inbox messages
Task access	None	Shared task list
Team membership	No	Yes
Coordination	One-off	Ongoing

---

Creating a Team

TeamCreate

TeamCreate({
  team_name: "feature-auth",
  description: "Implementing OAuth2 authentication"
})

Creates:

• ~/.claude/teams/feature-auth/config.json
• ~/.claude/tasks/feature-auth/ directory
• You become the team leader

Constraint: One team per session. Clean up the current team before starting a new one.

---

Delegate Mode

By default, the lead may start implementing tasks itself instead of waiting for teammates. Delegate mode restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.

When to use: When you want the lead to focus entirely on orchestration (breaking down work, assigning tasks, synthesizing results) without touching code directly.

How to enable: Start a team first, then press Shift+Tab to cycle into delegate mode.

---

Permissions Model

• Teammates start with the lead's permission settings
• You can change individual teammate modes after spawning
• You cannot set per-teammate modes at spawn time

Security: --dangerously-skip-permissions is inherited by ALL teammates. Every teammate can execute any tool without confirmation. Use only in fully trusted, sandboxed environments. For production workflows, omit this flag.

---

Environment Variables

Spawned teammates automatically receive these:

CLAUDE_CODE_TEAM_NAME="my-project"
CLAUDE_CODE_AGENT_ID="worker-1@my-project"
CLAUDE_CODE_AGENT_NAME="worker-1"
CLAUDE_CODE_AGENT_TYPE="Explore"
CLAUDE_CODE_AGENT_COLOR="#4A90D9"
CLAUDE_CODE_PLAN_MODE_REQUIRED="false"
CLAUDE_CODE_PARENT_SESSION_ID="session-xyz"

Using in prompts:

Task({
  team_name: "my-project",
  name: "worker",
  subagent_type: "general-purpose",
  prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages."
})

---

Plan Approval

For complex or risky tasks, require teammates to plan before implementing:

Task({
  team_name: "careful-work",
  name: "architect",
  subagent_type: "Plan",
  prompt: "Design an implementation plan for adding OAuth2 authentication",
  mode: "plan",  // Requires plan approval
  run_in_background: true
})

When the teammate finishes planning, they send a plan_approval_request to the lead. The lead reviews and either approves or rejects with feedback. If rejected, the teammate stays in plan mode, revises based on feedback, and resubmits.

See Messaging for plan approval tool syntax.

---

Graceful Shutdown

Always follow this sequence:

// 1. Request shutdown for all teammates
SendMessage({ to: "worker-1", message: { type: "shutdown_request", reason: "All tasks complete" } })
SendMessage({ to: "worker-2", message: { type: "shutdown_request", reason: "All tasks complete" } })

// 2. Wait for shutdown approvals
// Teammates respond with: SendMessage({ to: "team-lead", message: { type: "shutdown_response", request_id: "...", approve: true } })

// 3. Only then cleanup
TeamDelete()

Shutdown behavior: Teammates finish their current request or tool call before shutting down, which can take time.

Automate shutdown triggers with TeammateIdle and TaskCompleted hooks — see Error Handling for hook configuration.

Crashed teammates: Teammates have a 5-minute heartbeat timeout. If a teammate crashes:

1. They are automatically marked as inactive after timeout
2. Their tasks remain in the task list
3. Another teammate can claim their tasks
4. Cleanup will work after timeout expires

---

Cleanup

TeamDelete

TeamDelete()

Removes:

• ~/.claude/teams/{team-name}/ directory
• ~/.claude/tasks/{team-name}/ directory

IMPORTANT:

• Will fail if teammates are still active. Use shutdown first.
• Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly.

---

Discovering Team Members

Teammates can read the team config file to discover other team members:

cat ~/.claude/teams/{team-name}/config.json

The config contains a members array with each teammate's:

• name - Human-readable name (always use this for messaging and task assignment)
• agentId - Unique identifier (for reference only)
• agentType - Role/type of the agent

IMPORTANT: Always refer to teammates by their name (e.g., "team-lead", "researcher", "tester").