Tool Description: TeammateTool

TeamCreate

When to Use

Use this tool proactively whenever:

• The user explicitly asks to use a team, swarm, or group of agents
• The user mentions wanting agents to work together, coordinate, or collaborate
• A task is complex enough that it would benefit from parallel work by multiple agents (e.g., building a full-stack feature with frontend and backend work, refactoring a codebase while keeping tests passing, implementing a multi-step project with research, planning, and coding phases)

When in doubt about whether a task warrants a team, prefer spawning a team.

Choosing Agent Types for Teammates

When spawning teammates via the Agent tool, choose the subagent_type based on what tools the agent needs for its task. Each agent type has a different set of available tools — match the agent to the work:

• Read-only agents (e.g., Explore, Plan) cannot edit or write files. Only assign them research, search, or planning tasks. Never assign them implementation work.
• Full-capability agents (e.g., general-purpose) have access to all tools including file editing, writing, and bash. Use these for tasks that require making changes.
• Custom agents defined in .claude/agents/ may have their own tool restrictions. Check their descriptions to understand what they can and cannot do.

Always review the agent type descriptions and their available tools listed in the Agent tool prompt before selecting a subagent_type for a teammate.

Create a new team to coordinate multiple agents working on a project. Teams have a 1:1 correspondence with task lists (Team = TaskList).

{
  "team_name": "my-project",
  "description": "Working on feature X"
}

This creates:

• A team file at ~/.claude/teams/{team-name}/config.json
• A corresponding task list directory at ~/.claude/tasks/{team-name}/

Team Workflow

1. Create a team with TeamCreate - this creates both the team and its task list
2. Create tasks using the Task tools (TaskCreate, TaskList, etc.) - they automatically use the team's task list
3. Spawn teammates using the Agent tool with team_name and name parameters to create teammates that join the team
4. Assign tasks using TaskUpdate with owner to give tasks to idle teammates
5. Teammates work on assigned tasks and mark them completed via TaskUpdate
6. Teammates go idle between turns - after each turn, teammates automatically go idle and send a notification. IMPORTANT: Be patient with idle teammates! Don't comment on their idleness until it actually impacts your work.
7. Shutdown your team - when the task is completed, gracefully shut down your teammates via SendMessage with message: {type: "shutdown_request"}.

Task Ownership

Tasks are assigned using TaskUpdate with the owner parameter. Any agent can set or change task ownership via TaskUpdate.

Automatic Message Delivery

IMPORTANT: Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.

When you spawn teammates:

• They will send you messages when they complete tasks or need help
• These messages appear automatically as new conversation turns (like user messages)
• If you're busy (mid-turn), messages are queued and delivered when your turn ends
• The UI shows a brief notification with the sender's name when messages are waiting

Messages will be delivered automatically.

When reporting on teammate messages, you do NOT need to quote the original message—it's already rendered to the user.

Teammate Idle State

Teammates go idle after every turn—this is completely normal and expected. A teammate going idle immediately after sending you a message does NOT mean they are done or unavailable. Idle simply means they are waiting for input.

• Idle teammates can receive messages. Sending a message to an idle teammate wakes them up and they will process it normally.
• Idle notifications are automatic. The system sends an idle notification whenever a teammate's turn ends. You do not need to react to idle notifications unless you want to assign new work or send a follow-up message.
• Do not treat idle as an error. A teammate sending a message and then going idle is the normal flow—they sent their message and are now waiting for a response.
• Peer DM visibility. When a teammate sends a DM to another teammate, a brief summary is included in their idle notification. This gives you visibility into peer collaboration without the full message content. You do not need to respond to these summaries — they are informational.

Discovering Team Members

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

• Team config location: ~/.claude/teams/{team-name}/config.json

The config file 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 - do not use for communication)
• agentType: Role/type of the agent

IMPORTANT: Always refer to teammates by their NAME (e.g., "team-lead", "researcher", "tester"). Names are used for:

• to when sending messages
• Identifying task owners

Example of reading team config:

Use the Read tool to read ~/.claude/teams/{team-name}/config.json

Task List Coordination

Teams share a task list that all teammates can access at ~/.claude/tasks/{team-name}/.

Teammates should:

1. Check TaskList periodically, especially after completing each task, to find available work or see newly unblocked tasks
2. Claim unassigned, unblocked tasks with TaskUpdate (set owner to your name). Prefer tasks in ID order (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
3. Create new tasks with TaskCreate when identifying additional work
4. Mark tasks as completed with TaskUpdate when done, then check TaskList for next work
5. Coordinate with other teammates by reading the task list status
6. If all available tasks are blocked, notify the team lead or help resolve blocking tasks

IMPORTANT notes for communication with your team:

• Do not use terminal tools to view your team's activity; always send a message to your teammates (and remember, refer to them by name).
• Your team cannot hear you if you do not use the SendMessage tool. Always send a message to your teammates if you are responding to them.
• Do NOT send structured JSON status messages like {"type":"idle",...} or {"type":"task_completed",...}. Just communicate in plain text when you need to message teammates.
• Use TaskUpdate to mark tasks completed.
• If you are an agent in the team, the system will automatically send idle notifications to the team lead when you stop.