Claude Code Subagents

A practical guide to Claude Code subagents: when to use them, how to create custom agents, tool permissions, context isolation, background tasks, memory, hooks, and team rollout.

Claude Code subagents are specialized workers that handle a focused task in their own context and return a summary to the main conversation. They are useful when a side task would flood your main session with search results, logs, test output, or file exploration that you do not need to keep in the main thread.

Last checked on May 24, 2026. Claude Code supports built-in subagents, custom user and project subagents, plugin-provided agents, CLI-defined agents, foreground/background execution, session-wide --agent, subagent memory, tool restrictions, hooks, and experimental forked subagents. Treat subagents as a workflow primitive, not as a reason to split every task.

Quick Answer

Use a subagent when a task is self-contained, can be delegated with a clear prompt, and should return a concise result. Good examples are code review, test failure triage, log analysis, documentation research, security checks, or independent research across several modules. Keep the main conversation for tasks that require frequent back-and-forth, shared context across planning and implementation, or fast targeted edits.

The most important rule: a normal subagent starts with a fresh context. It does not automatically see your conversation history, earlier tool results, or files already read by the main session. If the subagent needs a path, error message, decision, or constraint, include it in the delegation prompt or in the subagent definition.

Subagents vs Other Claude Code Mechanisms

Subagents solve context isolation and role specialization. They are not a replacement for every customization surface.

Need	Better mechanism
Keep long research output out of the main thread	Subagent
Reuse a role with its own prompt and tool limits	Custom subagent
Run several independent investigations in parallel	Subagents or agent view
Create a reusable prompt that runs in the main context	Skill or slash command
Store project-wide instructions	`CLAUDE.md` or project rules
Enforce permissions before tool calls	Permission rules and hooks
Coordinate many workers with shared task state	Agent teams
Avoid file conflicts between parallel coding sessions	Worktrees

If you only need a short reusable instruction, create a skill or slash command. If you need a worker with its own role, context, tools, and model choice, create a subagent.

Built-In, Custom, Plugin, And CLI Agents

Claude Code can use multiple kinds of subagents:

Agent type	Where it comes from	Best use
Built-in agents	Claude Code itself	Explore, plan, or general-purpose delegation without extra setup.
User subagents	`~/.claude/agents/`	Personal agents you want across projects.
Project subagents	`.claude/agents/`	Team-shared agents for one repository.
Plugin agents	Installed plugin `agents/` folders	Distributed workflow integrations.
CLI-defined agents	`claude --agents ...`	Temporary agents for tests, scripts, or automation.
Managed agents	Organization managed settings	Enterprise-controlled agents and policy.

For a team repository, prefer .claude/agents/ after the workflow is stable enough to share. For personal experimentation, start in ~/.claude/agents/ or use /agents.

Create And Manage Agents

The recommended interactive path is the /agents command. It opens the agent management interface where you can view built-in, user, project, and plugin agents, create a new agent, edit tool access, delete custom agents, and see which agent is active when duplicates exist.

Manual creation is also simple. Put a Markdown file in .claude/agents/ for a project agent:

---
name: code-reviewer
description: Review recent changes for correctness, security, maintainability, and test coverage. Use proactively after code edits.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. Review the current diff first, then inspect only the files needed to verify the change.

Report findings by severity:

1. Blocking bugs or security risks.
2. Regressions or missing tests.
3. Maintainability suggestions.

Do not edit files. Return file paths, line references, and concrete fixes.

Subagent files are loaded at session start. If you add or edit files directly on disk while Claude Code is already running, restart the session. Agents created through /agents are available immediately.

Frontmatter Fields That Matter

Every subagent needs a clear identity and delegation description. Treat the description field as search intent for Claude. Claude uses it to decide when the agent should run.

Field	Required	Practical guidance
`name`	Yes	Use lowercase letters and hyphens, such as `code-reviewer`.
`description`	Yes	Explain when to delegate. Include "use proactively" only when the agent really should run without being asked.
Markdown body or `prompt`	Yes	The agent system prompt. Be explicit about workflow, output format, and limits.
`tools`	No	Omit to inherit tools, or list a narrow set such as `Read, Grep, Glob`.
`disallowedTools`	No	Remove risky tools from an inherited set.
`model`	No	Use when the role needs a different model from the main session.
`permissionMode`	No	Useful for narrow local workflows, but do not rely on it to bypass parent policy.
`mcpServers`	No	Give the agent specific MCP access when needed.
`hooks`	No	Run hooks only while that subagent is active.
`skills`	No	Preload skill content into the agent context at startup.
`memory`	No	Give the agent persistent memory with `user`, `project`, or `local` scope.
`background`	No	Hint whether the agent can run concurrently.
`color`	No	UI identification. Helpful when several agents run at once.

Keep names unique. If two files within one scope declare the same name, Claude Code may keep one and discard another without a useful warning.

How To Invoke A Subagent

There are three common patterns.

Natural Language

Name the agent in your prompt and let Claude decide whether to delegate:

Use the test-runner subagent to run the failing test suite and report only the failing cases.

This is the softest form. It usually works when the agent description is clear.

Agent Mention

Use an agent mention when you want a specific subagent for one task. The full request still goes through the main conversation, but the mention controls which agent Claude invokes.

@"code-reviewer (agent)" review the auth changes in the current diff.

You can also type the agent name manually when needed. Plugin-provided agents may use scoped names.

Session-Wide Agent

Use --agent when the whole session should run as that agent:

claude --agent code-reviewer

You can also make a project default in .claude/settings.json:

{
  "agent": "code-reviewer"
}

Be careful with session-wide agents. The subagent system prompt replaces the default Claude Code system prompt for that session, while normal memory loading still applies. Use this for deliberate modes, not casual one-off tasks.

Foreground And Background Subagents

Subagents can run in the foreground or background.

Mode	Behavior	Best use
Foreground	Blocks the main conversation until complete. Permission prompts surface to you.	Reviews or fixes that need interactive approvals.
Background	Runs while you continue working. Tool calls that would require new permission are auto-denied.	Long read-only research, logs, documentation lookup, or test analysis.

You can ask Claude to run a task in the background, or press Ctrl+B to background a running task. If background behavior is not desired, set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Background is not a magic speed boost. Running several agents multiplies token usage and can create competing edits if they touch the same files. Use read-only tools or worktree isolation when tasks might overlap.

What A Subagent Sees

A normal subagent starts fresh. Its context contains the agent prompt, the task message Claude writes when delegating, basic environment details, and configured project memory sources. It does not inherit the full parent conversation history or previous tool results.

Context item	Normal subagent behavior
Parent conversation history	Not included.
Files already read by the main session	Not included.
Agent system prompt	Included from the agent definition.
Delegation task message	Included, written by Claude from your request.
`CLAUDE.md` and memory	Loaded for most custom agents. Built-in Explore and Plan skip some memory and git context.
Git status	Included when available unless disabled.
Preloaded skills	Included only when listed in the `skills` field.
Tool results	Only from the subagent's own work.

This is why delegation prompts must be concrete. Bad: "review the thing we discussed earlier." Better: "review the current diff for src/auth/session.ts and src/auth/callback.ts; focus on token refresh, redirect handling, and missing tests."

Tool Permissions And Safety

Limit tool access by default. A code reviewer usually needs Read, Grep, Glob, and maybe Bash for git diff or tests. It usually does not need Edit or Write. A debugger may need Edit, but only if its job includes fixing the bug.

Role	Suggested tools	Avoid at first
Code reviewer	`Read, Grep, Glob, Bash`	`Edit`, `Write`
Test runner	`Read, Bash, Grep, Glob`	Broad write access
Documentation researcher	`Read, Grep, Glob, WebFetch` if available	Repo write tools
Security reviewer	`Read, Grep, Glob, Bash`	Automatic fixes
Migration implementer	`Read, Edit, Bash, Grep, Glob`	Deploy tools
Database analyst	`Bash` with hook guardrails	Write SQL

For sensitive workflows, combine subagent tools with permission rules and hooks. Tool lists narrow what an agent can do; permissions and hooks enforce policy around what should happen.

Memory, Skills, Hooks, And MCP

Subagents can become more capable when they load the right supporting context.

Feature	Use it when	Caution
`skills`	The agent should start with domain instructions or reusable workflow knowledge.	Preloaded skills add context cost.
`memory`	The agent should remember recurring project patterns across sessions.	Keep memory curated and avoid secrets.
`hooks`	The agent needs lifecycle checks while active.	Hooks run code, so keep them auditable.
`mcpServers`	The agent needs specialized external tools.	Grant the smallest MCP surface needed.

Project-scoped memory is often the best default for team agents because it can be versioned and improved with the repository. Use local memory for private machine-specific learning. Use user memory for patterns that apply across many repositories.

Practical Agent Roles

Start with roles that have clear inputs and outputs.

Code Reviewer

Purpose: inspect recent changes without editing. Output should be findings by severity, with file and line references.

Best prompt rule: "Do not summarize the whole diff. Report only actionable issues."

Test Triage Agent

Purpose: run or inspect tests, reduce noisy output, and return failing test names, error messages, likely root cause, and recommended next command.

Good delegation:

Use the test-triage subagent to run the auth test suite. Return only failing tests, root-cause hypotheses, and the smallest next verification command.

Observe the workflow: identify tasks that produce noisy output or require a stable checklist.
Write a narrow role: one purpose, one output format, one tool set.
Run manually: invoke the agent by name for a few real tasks.
Tighten description: improve when Claude should delegate.
Limit tools: remove edit or write access unless the role needs it.
Document in CLAUDE.md: explain when the team should use the agent.
Commit project agents: only after the behavior is predictable.

This keeps subagents useful instead of turning them into a confusing automation layer.

Common Mistakes

Mistake	Why it hurts	Better approach
Creating agents before the workflow is proven	You freeze the wrong process.	Run manually first, then promote repeated roles.
Vague descriptions	Claude cannot delegate reliably.	Say exactly when to use the agent.
Giving every agent all tools	More risk and less focus.	Grant the narrowest useful tools.
Expecting the parent context to be visible	Normal subagents start fresh.	Pass paths, errors, and decisions explicitly.
Returning huge reports	The main thread gets polluted anyway.	Require concise summaries and evidence.
Letting multiple agents edit the same files	Merge conflicts and duplicated work.	Use read-only agents or worktrees.
Using background agents for permission-heavy work	Background agents auto-deny prompts.	Use foreground for interactive approvals.
Not restarting after manual file edits	Claude may not load new agent definitions.	Restart the session or create through `/agents`.

A Starter Project Agent Set

For a Claude Code knowledge-base project, a small useful set is:

Agent	Purpose	Tools
`content-reviewer`	Check pages for thin content, unclear claims, missing internal links, and outdated sources.	`Read, Grep, Glob`
`source-checker`	Verify whether Claude Code claims still match official docs.	`Read, Grep, Glob, WebFetch` if available
`frontend-qa`	Inspect rendered pages, layout regressions, dark mode, and mobile overflow.	`Read, Bash`
`seo-structure-reviewer`	Check title, description, H2 flow, FAQ intent, and related-page links.	`Read, Grep, Glob`

Do not enable all of them at once. Start with content-reviewer or source-checker, because those directly support search traffic quality.