Agents and Swarms

Spawn parallel sub-agents, coordinate multi-agent teams, and define custom agents to tackle large or concurrent tasks.

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:

Parameter	Description
description	A short (3–5 word) label for the task
prompt	The full task prompt for the sub-agent
subagent_type	Optional: the type of specialized agent to use
model	Optional: "sonnet", "opus", or "haiku" — overrides the agent definition’s model
run_in_background	Set true to run without blocking; Claude is notified on completion
isolation	"worktree" — runs the agent in an isolated git worktree
cwd	Absolute path to run the agent in, overriding the working directory
name	Name 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 type	Purpose
General purpose	Default agent for most delegated tasks
Explore	Read-only exploration of the codebase (one-shot; no follow-up messages)
Plan	Produces a structured plan (one-shot; no follow-up messages)
Statusline setup	Configures the terminal status line
Claude Code Guide	Guides users through Claude Code features (non-SDK only)
Verification	Verifies 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

Field	Description
description	What the agent does and when to use it (required)
tools	Allowlist of tools the agent may use
disallowedTools	Tools explicitly blocked for this agent
model	Model to use (inherit to match the parent model)
effort	Effort level (maps to thinking budget)
permissionMode	Permission mode for the agent
maxTurns	Maximum agentic turns before the agent stops
mcpServers	MCP servers available to the agent (name reference or inline config)
hooks	Session-scoped hooks registered when the agent starts
skills	Skill names to preload
memory	Persistent memory scope: "user", "project", or "local"
background	true — always run as a background task when spawned
isolation	"worktree" — always run in an isolated git worktree
initialPrompt	Text 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:

Parameter	Description
name	Name for the spawned teammate, making it addressable via SendMessage({to: name})
team_name	Team name for spawning; uses current team context if omitted
mode	Permission mode for the spawned teammate (e.g., "plan")

Use cases

Parallel test execution

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.

Large refactors

Delegate independent modules to separate agents. The coordinator collects their diffs and resolves conflicts.

Explore then implement

Use the built-in Explore agent to map the codebase, then spawn an implementation agent with the exploration results as context.