A Claude Code subagent is a specialized assistant that runs in its own context window with its own system prompt, tool access and permissions. Claude delegates to it when a task matches its description, and only a summary comes back. That keeps noisy work, like test output, out of your main conversation.
Defining one
Per Anthropic's subagent documentation, a subagent is a Markdown file with YAML frontmatter, and the body becomes the system prompt. Only name and description are required.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Give specific, actionable feedback.
Other fields include disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background and isolation, which can set an isolated git worktree.
Where files live and which wins
From highest priority to lowest: managed settings, the session flag for agents, project .claude/agents/, user ~/.claude/agents/, then a plugin's agents folder. Identity comes from the name field, not the file name. If two share a name, the higher location wins.
Commit project agents so the team shares them.
What a subagent sees
Each starts with a fresh context. It does not see your conversation history or files already read. Its initial context includes its own system prompt, the delegation message Claude writes, CLAUDE.md files (except for the built-in Explore and Plan agents), a git status snapshot and any preloaded skills. A fork is the exception, since it inherits the full conversation.
Restricting tools
If you omit tools, the subagent inherits every tool available to subagents, which can include MCP tools. Use an allowlist for anything that should be read-only. The docs say disallowedTools is applied first, and a tool listed in both is removed. To block a subagent entirely, add a deny rule such as Agent(Explore) to permissions.
A frontmatter tool list is easy to get wrong, so confirm the agent's actual abilities with a test prompt before trusting it with a repository.
Cost
Subagent requests draw on your usage. Anthropic's cost page suggests delegating verbose operations like tests and log processing to subagents so only a summary returns, and choosing a smaller model for simple subagent work. Agent teams that run several instances use roughly seven times more tokens than a standard session when teammates run in plan mode, according to that page.
Checkpoints do not cover them
Rewinding usually does not restore edits a subagent made, apart from files Claude had already edited in your conversation. Use git to revert the rest.
Quick check
Does a subagent see my earlier conversation?
No, except a fork. It starts fresh with its own prompt, the delegation message, CLAUDE.md files and a git status snapshot.
What does a subagent get if I leave out tools?
Every tool available to subagents. Set an allowlist for read-only agents.
Sources
Last reviewed: 19 October 2026.
