Claude Code subagents are focused assistants that Claude runs within a session. Each ordinary subagent receives a fresh context, a delegated task, and a selected set of available tools, then returns a result to the caller. Use one to keep a code search or review out of your main conversation. Define a project subagent in .claude/agents/ when the same task and constraints recur. This guide shows a small reviewer definition, how to invoke it, how to verify its output, and when a separate coordination layer is useful.
The details below follow Anthropic’s current Claude Code subagent documentation. The file and prompt are original illustrations; their frontmatter has been parsed locally, but the reviewer was not run in Claude Code. Tool availability and permissions also depend on the running client and session settings.
How a Claude Code subagent works
Claude can delegate automatically when a task matches an agent description, or you can request an agent by name. A standard subagent starts with its own context window. It does not receive the full parent conversation or the files the parent already read; the parent supplies a delegation message and the subagent reads what it needs. Its result returns to the caller, which must assess the evidence before acting. A conversation fork is a documented exception: it inherits the parent context. Do not design every subagent prompt as though it were a fork.
The project definition is a Markdown file under .claude/agents/. A personal definition under ~/.claude/agents/ is available across projects. The file begins with YAML frontmatter: name and description are required; tools, model, permissionMode, and other fields are optional. The Markdown body is the subagent’s system prompt. The description tells Claude when to delegate, so state the trigger plainly rather than stuffing the description with a full workflow. Anthropic documents the frontmatter fields and scope rules.
A scoped reviewer you can adapt
Suppose you want a reviewer that identifies concrete risks in a changed file without editing it. Save this illustrative definition as .claude/agents/scoped-reviewer.md in your project. Its three built-in tools are named exactly as in the current Claude Code docs. This is a file definition, not a command to launch an agent or a claim that the review has run.
---
name: scoped-reviewer
description: Review a named code change for concrete correctness risks and missing proof.
tools: Read, Grep, Glob
---
Review only the paths named in the delegation request.
Read nearby code only when a finding depends on it.
Report each issue with its file path, the behavior at risk,
and the evidence in the code.
Separate confirmed findings from questions.
Suggest a focused check for each finding.
Do not edit files, claim to have run tests,
or declare a change ready to merge.The tools field narrows the subagent’s tool list to Read, Grep, and Glob when those tools are available. No Bash or Edit tool is granted by this definition. This is a useful scope for source review, but tool lists are not a substitute for your session’s permission policy or repository rules. If a task needs commands, decide which commands are justified, give a separate agent the necessary access, and review its output. Avoid granting a full shell merely to make a read-only example sound capable.
The example names paths in the task prompt rather than hard-coding a repository layout into the reusable agent. The body asks for file-level evidence and distinguishes observations from unanswered questions. It also asks the reviewer to avoid an attractive but unsupported conclusion: a reviewer who only reads code cannot honestly say the tests passed. For a real review, the parent should inspect each reported path and run the relevant checks before accepting the result.
Create, invoke, and check the result
- Create .claude/agents/scoped-reviewer.md in the repository and review its frontmatter and Markdown body.
- Ask Claude Code to use the scoped-reviewer agent on a named change and state the exact paths, intended behavior, and constraints.
- Read the returned findings. Verify cited code and run the relevant tests yourself or delegate those checks to an agent with appropriate tools.
- Record the decision and proof where the next person or agent can find them.
An explicit request can be as simple as: “Use the scoped-reviewer agent to review src/auth/session.ts for session-expiry bugs. Report file evidence and any missing tests; do not edit files.” This is natural-language invocation, matching Anthropic’s documented example. It does not depend on a made-up orchestration API. If Claude does not detect a newly created agents directory in an existing session, restart that session; Anthropic notes this discovery exception.
Check whether Claude actually delegated. Its transcript should show a subagent tool call with the agent name and task; a plausible final answer alone does not prove delegation happened. Then judge the result on the cited code, not the agent’s confidence. A good finding identifies a reachable behavior and the relevant lines. A weak finding says “might be a race” without the path that could race. If the reviewer requests unavailable context, give it a tighter follow-up or inspect the path in the main session.
What context and tools does it receive?
Fresh context is useful because large searches and file reads stay out of the main conversation. It also makes a precise task brief essential. Include the target paths, expected behavior, constraints, and the format of the result. Do not assume a non-fork subagent remembers a design decision you made earlier. Current Claude Code docs say custom subagents normally load applicable CLAUDE.md files and a git-status snapshot, while the built-in Explore and Plan agents are exceptions. Those sources still do not replace the specific decision you need the worker to follow.
Tools in frontmatter are an allowlist drawn from tools available to subagents in that session. If you omit tools, the definition inherits the available subagent tool pool; if you name tools that are unavailable, launch may fail. Claude Code can also expose connected MCP tools to subagents, subject to the subagent’s tool settings and the client’s connection. A tool being listed does not prove that the account has project access or that a write is authorized. Test the exact client and permissions before relying on an MCP workflow.
For work on the same checkout, two agents editing one file can collide even when each agent has a fresh context. Assign distinct paths or use isolated worktrees where the task calls for them. Claude Code documents an optional isolation: worktree setting, but that changes the file environment and should be chosen deliberately. A read-only review avoids this class of edit conflict; an implementation task needs ownership, integration, and a test plan as well as a subagent definition.
When subagents help, and when they cost more
Delegation is most useful for a bounded side task with a compact return: locate all call sites of one interface, review one patch for security assumptions, or investigate independent hypotheses. The parent can continue with its own work while reading remains separate. A narrow prompt and a named output shape improve the chance that the result is actionable. Subagent requests still consume model usage, so spawning several for a trivial search can cost more attention and tokens than doing the search directly.
Keep a small edit or a decision that depends heavily on the full conversation in the main session. For broad implementation, first divide the work by file ownership and acceptance checks. A subagent’s final message is a report, not a durable project record. Anthropic also documents ways to resume some custom subagents in the same session, so “disappears immediately” would be inaccurate; the retained transcript still does not serve as a shared task board for every other client. For an evidence trail beyond the transcript, the Claude Code hooks guide shows how to record bounded tool events.
Choose the coordination mode for the task
The same scoped-reviewer example leads to different coordination choices. Start with the context the reviewer needs and who must receive its evidence; use the smallest mode that covers that boundary. The distinctions follow Anthropic’s current subagent and fork documentation and agent-team documentation. Availability and settings must be checked in the Claude Code installation used for the task.
- Bounded review in this Claude session: use the ordinary scoped-reviewer subagent with a fresh context. Pass the named path, expected behavior, and constraints; retain the delegation transcript, cited path and lines, and the exact follow-up check the caller ran.
- Review requiring the earlier conversation: use a fork so the worker inherits that context. Name which earlier decision matters; retain the fork transcript, the cited code evidence, and a check on the relevant revision. Reconfirm mutable facts before acting.
- Independent Claude sessions that must communicate: consider an agent team. Assign file ownership and a shared task, then retain teammate messages, cited paths and lines, and the integrated check. Confirm the experimental team feature is available in the current client.
- Claude, Cursor, and Codex sharing one task: use an explicit work record each client can reach. Record owner, scope, revision, decision, cited evidence, and next check; verify access from each participating client before relying on the record.
For the illustrative reviewer file above, the first row is the intended use. Its YAML was parsed locally, but no Claude Code delegation, cited finding, or follow-up test was observed. The other rows are decision examples, not execution reports. A transcript proves which worker was invoked; a cited line supports a finding; and the actual check result, with revision and environment, is needed before a completion claim.
Subagents, agent teams, and cross-client work
Claude Code agent teams are a separate, currently experimental feature. Teammates are independent Claude Code instances that can share a task list and communicate. Anthropic also documents cross-session messaging. Therefore a subagent is not the only way Claude Code can coordinate parallel work, and it would be wrong to say Claude sessions cannot exchange findings. The useful distinction is scope: a subagent returns focused work to its caller; a team coordinates Claude sessions; a mixed-tool workflow needs a record that its participating clients can all reach.
For example, Claude Code, Cursor, and Codex may each touch the same application. Their session-local messages do not automatically establish who owns a change or what was approved for the whole project. A shared handoff can hold the task, contract, and verification evidence across clients. See the cross-client orchestration guide for that wider workflow, and the agent orchestration primer for the basic terms. These are coordination patterns, not a reason to turn every short Claude task into a multi-agent system.
Using AppHandoff as the shared record
AppHandoff exposes its MCP service at https://. After a client connects and the account has access, an agent can use bootstrap to resolve a project, find to list cards, and get to read a specific card. The served tool catalog also includes read_skill, ticket, plan, message, project, and decide_lifecycle_proposal; the last is for a signed-in human’s approval-card click, not a model action. Write operations follow project scope, revision, and human approval rules. The AppHandoff MCP overview explains where the shared record fits, and the Claude Code MCP server guide covers connection choices.
An agent that needs a current work item can read it with get rather than guessing from an old chat. It can attach evidence to a ticket when a permitted write is appropriate, and a human can approve a gated lifecycle action through the offered approval path. Do not infer that every Claude Code installation exposes the same MCP tools to every subagent: connection mode, scopes, and local settings matter. The reviewer file above intentionally uses only built-in read tools, so it does not depend on any AppHandoff connection.
A practical review checklist
- Name the smallest task whose result the main conversation needs.
- Choose a project or personal definition and write a short, specific description.
- Grant the least set of tools required for that task; check actual session permissions.
- Include paths, expected behavior, and the desired evidence in the delegation prompt.
- Verify that delegation occurred and inspect the returned file evidence.
- Run missing checks, then put decisions and proof in a shared record if more than one session or client needs them.
Subagents save context when the task boundary is clear. Their strongest output is evidence the caller can check: a file path, a concrete behavior, a missing check, and a bounded recommendation. Keep the definition simple, verify a real invocation in your own Claude Code environment, and treat cross-session coordination as a separate design choice.
Frequently asked questions
What are Claude Code subagents?
Claude Code subagents are focused assistants that run within a session. An ordinary subagent starts with a fresh context, receives a delegated task and available tools, then returns a result to its caller. A conversation fork is a documented exception that inherits parent context.
How do I create and invoke a project subagent?
Put a Markdown file with required name and description YAML fields under .claude/agents/. Add a focused system prompt below the frontmatter, then ask Claude Code to use that agent by name on a specific task. Check the transcript to confirm delegation occurred.
Can Claude Code subagents use MCP tools?
They can use MCP tools that are available to the main session when their tool settings and permissions allow them. A connected server does not by itself grant project access or permission to write. Check the specific client, connection, account scope, and subagent definition.
How are subagents different from agent teams?
Subagents return focused work to a caller within one session. Claude Code agent teams are a separate, experimental feature with independent teammates, a shared task list, and direct communication. Cross-client workflows may need a shared record accessible to each participating tool.