> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```markdown theme={null}
---
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
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.