Agents

Autonomous sub-processes that Claude can spawn to handle complex tasks in parallel, each with its own tool access and context.

Agents are autonomous sub-processes that Claude spawns to handle complex or parallelizable tasks. When Claude encounters a problem that benefits from delegation — a broad codebase search, an independent verification pass, or a multi-step workflow — it spawns an agent, provides a task description, and receives a summary when the work is done.

Each agent runs with its own context window, tool budget, and (optionally) its own model. The spawning Claude sees only the agent’s final summary, not the intermediate tool calls — which keeps the main conversation focused.

How agents work

Claude spawns agents using the Agent tool. A minimal spawn looks like:

Agent({
  prompt: "Search the codebase for all usages of the deprecated `getUser` function and list the files.",
  subagent_type: "Explore",
  description: "find getUser usages"
})

When the agent completes, it returns a single message summarizing its findings. Claude then relays a concise summary to you.

Parallel agents

Claude can launch multiple agents in a single message to work concurrently:

# Claude's internal turn — two agents launched at once
Agent({ prompt: "...", subagent_type: "Explore", description: "search auth module" })
Agent({ prompt: "...", subagent_type: "Explore", description: "search payment module" })

Both agents run simultaneously. Claude waits for both to complete before continuing.

Background agents

Agents can run in the background while Claude keeps the conversation responsive:

Agent({
  prompt: "Run the full test suite and report any failures.",
  run_in_background: true,
  description: "run tests"
})

Claude receives a notification when the background agent completes and can then review its output.

Isolated agents (worktrees)

You can run an agent in an isolated git worktree so its file changes don’t affect your working tree:

Agent({
  prompt: "Refactor the logging module and open a pull request.",
  isolation: "worktree",
  description: "refactor logging"
})

If the agent makes no changes, the worktree is cleaned up automatically. If it does make changes, Claude returns the worktree path and branch name.

Built-in agents

Claude Code ships with several built-in agent types.

general-purpose

The default agent type. Used when no subagent_type is specified. Has access to all tools.

When to use: Researching complex questions, searching code, executing multi-step tasks, or any task where you’re not confident the first few searches will find the right match.

Agent({
  prompt: "Find where the authentication token is validated and explain the flow.",
  description: "trace auth flow"
})

---

Explore

A fast, read-only search specialist. Has access to Glob, Grep, Read, and Bash (read-only operations only). Cannot create, edit, or delete files. Uses a faster model (Haiku by default) for speed.

When to use: Finding files by pattern, searching code for keywords, answering questions about the codebase. Specify a thoroughness level in your prompt: "quick", "medium", or "very thorough".

Agent({
  subagent_type: "Explore",
  prompt: "Find all React components that use the useAuth hook. Thoroughness: medium.",
  description: "find useAuth components"
})

Explore is strictly read-only. It cannot write files, run git write commands, or install packages — any attempt will fail. This makes it safe to run concurrently with other work.

---

Plan

A software architect agent that explores the codebase and designs implementation plans. Read-only; cannot create or modify files.

When to use: Before implementing a significant feature, to get a step-by-step implementation plan, identify critical files, and consider architectural trade-offs.

Agent({
  subagent_type: "Plan",
  prompt: "Design an implementation plan for adding rate limiting to the API endpoints.",
  description: "plan rate limiting"
})

The Plan agent returns a structured plan with a “Critical Files for Implementation” section listing the files most relevant to the task.

---

verification

Verifies that implementation work is correct by running builds, tests, linters, and custom checks. Produces a PASS, FAIL, or PARTIAL verdict with evidence. Runs as a background task by default.

When to use: After completing non-trivial changes (3+ file edits, backend changes, infrastructure changes). Pass the original task description, the list of changed files, and the approach taken.

Agent({
  subagent_type: "verification",
  prompt: "Verify the rate limiting implementation. Task: add rate limiting to API endpoints. Files changed: src/middleware/rateLimit.ts, src/routes/api.ts. Approach: token bucket algorithm with Redis.",
  description: "verify rate limiting"
})

The verification agent runs the project’s build and test suite, applies type-specific verification strategies (e.g., for backend changes: starting the server and hitting endpoints), and includes adversarial probes before issuing a verdict.

---

claude-code-guide

A documentation agent that answers questions about Claude Code, the Claude Agent SDK, and the Claude API. Fetches official documentation pages to give accurate, up-to-date answers.

When to use: When you ask questions like “Can Claude Code do X?”, “How do I configure Y?”, or “What’s the difference between Z and W?” Claude spawns this agent automatically to answer questions about itself.

---

statusline-setup

A specialized agent for setting up the terminal statusline integration. Invoked by the terminal setup workflow.

Custom agents

You can define your own agent types by creating Markdown files in .claude/agents/. Custom agents override built-in agents with the same name, letting you extend or replace defaults.

Directory structure

.claude/
└── agents/
    ├── code-reviewer.md
    └── database-expert.md

Claude Code searches for agent files in:

• <managed-path>/.claude/agents/ (policy)
• ~/.claude/agents/ (user)
• .claude/agents/ (project)

Project agents override user agents with the same name. User agents override built-in agents.

Agent file format

---
name: code-reviewer
description: >
  Use this agent for thorough code reviews. It checks style, correctness,
  test coverage, and security. Invoke after writing significant new code.
tools: Read, Glob, Grep, Bash
model: claude-opus-4-5
effort: high
---

You are an expert code reviewer...

Your system prompt continues here. The model follows these instructions
when it runs as this agent type.

Frontmatter fields

Field	Type	Description
name	string	Required. The agent type identifier used in subagent_type.
description	string	Required. When Claude should use this agent. Shown in the agent list.
tools	string	Comma-separated list of allowed tools. Omit to allow all tools.
disallowedTools	string	Comma-separated tools to block. Used when you want all tools except specific ones.
model	string	Model override for this agent. Use inherit to use the session model.
effort	string or int	Effort level: low, medium, high, max, or an integer.
permissionMode	string	Permission mode for the agent session.
maxTurns	integer	Maximum number of agentic turns before stopping.
skills	string	Comma-separated skill names to preload for this agent.
mcpServers	array	MCP servers to attach to this agent (by name or inline config).
hooks	object	Session-scoped hooks for this agent.
memory	user, project, or local	Persistent memory scope for the agent.
background	boolean	Always run as a background task when spawned.
initialPrompt	string	Text prepended to the first user turn (slash commands work here).
isolation	worktree	Always run in an isolated git worktree.

Example: a focused code reviewer

---
name: code-reviewer
description: >
  Use after writing significant code changes. Reviews for correctness,
  style consistency with the codebase, test coverage gaps, and security issues.
  Returns a structured report with PASS/FAIL per category.
tools: Read, Glob, Grep, Bash
effort: high
---

You are a thorough code reviewer for this project.

When invoked, you will receive a description of the changes made. Your job is to:

1. Read all changed files
2. Check for correctness (logic errors, edge cases, error handling)
3. Check style consistency with surrounding code
4. Identify missing test coverage
5. Flag potential security issues

Output a structured report with a verdict for each category.

Invoke it by name:

Agent({
  subagent_type: "code-reviewer",
  prompt: "Review the changes to src/auth/tokenValidator.ts. The change adds token expiry checking.",
  description: "review token validator"
})

The /agents command

Type /agents at the prompt to open the agent management panel. It shows:

• All available agent types (built-in, plugin, and custom)
• Each agent’s description and tool access
• Buttons to create or edit custom agent files

Writing effective agent prompts

Agents start with no context — they haven’t seen your conversation. Brief them completely:

Good prompt

We're adding rate limiting to the API. I've implemented a token bucket
algorithm in src/middleware/rateLimit.ts and wired it into src/routes/api.ts.

Verify the implementation:
1. Start the dev server: npm run dev
2. Test the /api/users endpoint — should allow 10 requests/minute
3. Verify the 429 response includes a Retry-After header
4. Test that the limit resets after 60 seconds

Report PASS or FAIL for each check with the exact command output.

Weak prompt

Based on your findings, verify the rate limiting works.

A good agent prompt:

• Explains what was done and why
• Points to the specific files involved
• Gives concrete verification steps or questions
• Specifies the expected output format

For more on tool-level configuration, see the Agent tool reference.