Subagents in Claude Code: when to delegate and how to write one
What Claude Code subagents are, when delegating beats doing it in the main chat, and how to write your own agent file with tools, model and a tight prompt.
A subagent is a second Claude that runs in its own context window with its own system prompt and its own tool access, does one job, and hands back a summary. The noisy part (forty files read, a long log, a dead end) stays in its context, not yours. You write one as a Markdown file in .claude/agents/, and Claude delegates to it when the task matches its description.
#When should you delegate to a subagent?
Delegate when the work is verbose and you only need the conclusion:
- Searching a large codebase to answer "where is X handled?".
- Reading logs or test output and reporting the cause.
- Reviewing a diff with fresh eyes, without the bias of having written it.
- Running independent investigations at the same time.
Don't delegate when the task is a short edit, when you need to steer step by step, or when the work depends on the whole conversation. A subagent does not see your conversation history: Claude writes it a delegation prompt, and that prompt is all it has. Anything subtle you said ten turns ago is gone unless it is in that prompt.
This is the main reason subagents help with the context window: an investigation that would burn tens of thousands of tokens in your main chat costs you one paragraph of summary there. The tokens are still spent, though. Each subagent uses its own tokens, and they count toward your usage limits.
#What subagents does Claude Code already have?
You get a few without writing anything:
- Explore: a fast, read-only agent for searching and reading a codebase. Claude picks a thoroughness: quick, medium or very thorough.
- Plan: a read-only research agent used in plan mode.
- General-purpose: full tool access, for multi-step tasks that need both exploring and acting.
There are a couple of helpers too (one behind /statusline, one that answers questions about Claude Code itself). Explore and Plan skip CLAUDE.md and the git status snapshot to stay quick and cheap. You can switch a built-in off with a deny rule such as Agent(Explore).
#How do you write a custom subagent?
Create a Markdown file. The frontmatter configures it; the body is its system prompt.
---
name: code-reviewer
description: Reviews code for quality and security. Use after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, look at the files that changed
(use `git diff` output if you were given it) and report:
1. Bugs and edge cases that will fail at runtime.
2. Security problems: injection, missing auth checks, secrets in code.
3. Anything that contradicts the conventions in CLAUDE.md.
Be specific: file, line, what is wrong, a suggested fix. Do not restate
what the code does. If you find nothing, say so in one line.
Save it as .claude/agents/code-reviewer.md for a project (commit it so the team gets it) or ~/.claude/agents/code-reviewer.md for all your projects. Claude Code watches these folders, so a new file is picked up within seconds. Only name and description are required.
The fields you will use most:
| Field | What it does |
|---|---|
description | Tells Claude when to delegate. This is what decides if your agent is ever used |
tools / disallowedTools | Allowlist or denylist of tools. Give a reviewer read tools only |
model | sonnet, opus, haiku, a full model ID, or inherit |
permissionMode | The permission mode the agent runs in |
maxTurns | A ceiling on agentic turns |
skills | Skills to preload into its context |
mcpServers | MCP servers scoped to this agent |
isolation | worktree runs it in a temporary git worktree |
background | true to run it in the background |
There are more (hooks, memory, effort, color), documented on the sub-agents page. Plugin-provided subagents ignore hooks, mcpServers and permissionMode.
#How do you write a description that Claude acts on?
Claude reads the description of every agent to decide whether to delegate. Write it like a trigger condition, not a title.
- Weak:
Code reviewer - Better:
Reviews code for quality and security. Use proactively after writing or modifying code.
Say when to use it and what it returns. If an agent never fires, the description is almost always the problem. You can always call one by hand.
#How do you invoke a subagent?
Three ways:
Use the code-reviewer subagent to check my recent changes
@"code-reviewer (agent)" look at the auth changes
and, for a whole session run as that agent:
claude --agent code-reviewer
You can also set "agent": "code-reviewer" in .claude/settings.json. For a throwaway agent that exists for one session only, pass JSON on the command line:
claude --agents '{"code-reviewer": {"description": "Reviews code. Use after changes.", "prompt": "You are a senior code reviewer.", "tools": ["Read", "Grep", "Glob"], "model": "sonnet"}}'
If two locations define the same name, the higher priority wins: managed settings, then --agents, then .claude/agents/, then ~/.claude/agents/, then plugins.
#Foreground or background?
A foreground subagent blocks your conversation, and its permission prompts reach you. A background one runs while you carry on, and its prompts show up in your main session labelled with its name. Background agents get a smaller set of built-in tools. By default up to twenty can run at once, and a subagent can itself spawn subagents a few levels down, though you should rarely want that.
Explore and Plan are one-shot. Other subagents can be resumed by name or ID.
#Which subagents are worth writing first?
Start with the jobs you repeat:
- A reviewer, read-only, with your team's checklist in the prompt. See using Claude Code to review code.
- A test runner that runs the suite and returns only the failures and their likely cause.
- A researcher with
WebFetchand read tools that reports back with sources.
Keep each agent narrow, give it the fewest tools it needs, and put the exact output format in the prompt, because the summary is the only thing that comes back to you.
#In Relais
Relais shows subagents while they work: Explore, Plan and your own agents appear under their session with what they are doing, and the Tasks tab lists subagents and background commands with live output, a time and a stop button each. See the features page. Relais agents with their own browser and routines are a different thing from Claude Code subagents; they are described on the agents page.