Skip to main content
Claude Code can spawn sub-agents to work on tasks in parallel. A single Claude instance can act as a coordinator that breaks work into pieces, delegates each piece to a sub-agent, and assembles the results—or multiple Claude instances can collaborate as a team. This page covers how the agent system works and how to create custom agents.

​
The Agent tool

The primary mechanism for multi-agent work is the Agent tool (wire name Task for backward compatibility). When Claude calls this tool it spawns a sub-agent with its own conversation context, tool access, and (optionally) an isolated git worktree. The tool accepts the following parameters:
ParameterDescription
descriptionA short (3–5 word) label for the task
promptThe full task prompt for the sub-agent
subagent_typeOptional: the type of specialized agent to use
modelOptional: "sonnet", "opus", or "haiku" — overrides the agent definition’s model
run_in_backgroundSet true to run without blocking; Claude is notified on completion
isolation"worktree" — runs the agent in an isolated git worktree
cwdAbsolute path to run the agent in, overriding the working directory
nameName for the agent, making it addressable by other agents
Sub-agents inherit parent permissions by default. When isolation: "worktree" is set, the agent receives a fresh git worktree so its filesystem changes don’t interfere with the parent.

​
Background tasks

When run_in_background: true is passed, the sub-agent runs asynchronously. Claude receives a notification when it completes. Background tasks auto-activate after 120 seconds of non-interaction when CLAUDE_AUTO_BACKGROUND_TASKS is set or the corresponding feature flag is enabled. You can disable background tasks entirely with CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1. Background tasks are visible and manageable with the /tasks command (also aliased as /bashes).

​
Built-in agents

Claude Code ships several built-in agents that are always available:
Agent typePurpose
General purposeDefault agent for most delegated tasks
ExploreRead-only exploration of the codebase (one-shot; no follow-up messages)
PlanProduces a structured plan (one-shot; no follow-up messages)
Statusline setupConfigures the terminal status line
Claude Code GuideGuides users through Claude Code features (non-SDK only)
VerificationVerifies plan execution (when feature-flagged)
Built-in agents can be disabled for SDK use by setting CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 (only effective in non-interactive/SDK mode).

​
Custom agents

You can define custom agents in Markdown files placed in the .claude/agents/ directory. Claude Code loads agents from:
  • Project agents: .claude/agents/ — scoped to the current project
  • User agents: ~/.claude/agents/ — available in all projects
  • Managed agents: loaded from managed settings (enterprise/MDM)
  • Plugin agents: provided by installed plugins
Each agent is a Markdown file whose frontmatter defines its metadata: 
---
description: Runs the full test suite and summarizes failures
tools: [Bash, Read]
model: haiku
permissionMode: default
maxTurns: 20
---

You are a test runner agent. Run `npm test` and report all failures with file paths and line numbers.

​
Agent frontmatter fields

FieldDescription
descriptionWhat the agent does and when to use it (required)
toolsAllowlist of tools the agent may use
disallowedToolsTools explicitly blocked for this agent
modelModel to use (inherit to match the parent model)
effortEffort level (maps to thinking budget)
permissionModePermission mode for the agent
maxTurnsMaximum agentic turns before the agent stops
mcpServersMCP servers available to the agent (name reference or inline config)
hooksSession-scoped hooks registered when the agent starts
skillsSkill names to preload
memoryPersistent memory scope: "user", "project", or "local"
backgroundtrue — always run as a background task when spawned
isolation"worktree" — always run in an isolated git worktree
initialPromptText prepended to the first user turn (slash commands work)
The body of the Markdown file becomes the agent’s system prompt.

​
Agent definition types

BuiltInAgentDefinition  — ships with Claude Code, dynamic system prompts
CustomAgentDefinition   — user/project/managed .md files
PluginAgentDefinition   — provided by installed plugins
You can check whether a server or tool requirement is met via requiredMcpServers—agents that declare required MCP servers are hidden from the selector when those servers are not configured.

​
Agent teams and swarms

Agent teams are an experimental feature. Enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 or the --agent-teams CLI flag. A remote feature gate must also be active.
When agent teams are enabled, Claude can spawn teammate agents that run as peer processes rather than direct sub-agents. Teammates can receive follow-up messages from the coordinator and collaborate asynchronously.

​
Coordinator mode

Setting CLAUDE_CODE_COORDINATOR_MODE=1 replaces the standard built-in agent list with coordinator-specific agents designed to manage a pool of worker agents.

​
Team parameters (Agent tool)

When agent teams are enabled, the Agent tool gains additional parameters:
ParameterDescription
nameName for the spawned teammate, making it addressable via SendMessage({to: name})
team_nameTeam name for spawning; uses current team context if omitted
modePermission mode for the spawned teammate (e.g., "plan")

​
Use cases

Spawn one agent per test suite. Each runs in an isolated worktree so filesystem side-effects do not conflict.
Run the unit tests, integration tests, and linting checks in parallel.
Summarize all failures when done.
Claude will use Agent with run_in_background: true and isolation: "worktree" for each suite, then wait for all to complete.
Delegate independent modules to separate agents. The coordinator collects their diffs and resolves conflicts.
Use the built-in Explore agent to map the codebase, then spawn an implementation agent with the exploration results as context.

Build docs developers (and LLMs) love

Get started for freeTalk to us