[{"data":1,"prerenderedAt":56},["ShallowReactive",2],{"blog-claude-code-subagents":3,"blog-related-claude-code-subagents":39},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-subagents","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.","Getting started","getting-started","claude code subagents","2026-11-17",5,"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\u002Fagents\u002F`, and Claude delegates to it when the task matches its description.\n\n## When should you delegate to a subagent?\n\nDelegate when the work is **verbose** and you only need the conclusion:\n\n- Searching a large codebase to answer \"where is X handled?\".\n- Reading logs or test output and reporting the cause.\n- Reviewing a diff with fresh eyes, without the bias of having written it.\n- Running independent investigations at the same time.\n\nDon'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.\n\nThis is the main reason subagents help with [the context window](\u002Fblog\u002Fclaude-code-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.\n\n## What subagents does Claude Code already have?\n\nYou get a few without writing anything:\n\n- **Explore**: a fast, read-only agent for searching and reading a codebase. Claude picks a thoroughness: quick, medium or very thorough.\n- **Plan**: a read-only research agent used in [plan mode](\u002Fblog\u002Fclaude-code-plan-mode).\n- **General-purpose**: full tool access, for multi-step tasks that need both exploring and acting.\n\nThere are a couple of helpers too (one behind `\u002Fstatusline`, 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)`.\n\n## How do you write a custom subagent?\n\nCreate a Markdown file. The frontmatter configures it; the body is its system prompt.\n\n```md\n---\nname: code-reviewer\ndescription: Reviews code for quality and security. Use after writing or modifying code.\ntools: Read, Glob, Grep\nmodel: sonnet\n---\n\nYou are a code reviewer. When invoked, look at the files that changed\n(use `git diff` output if you were given it) and report:\n\n1. Bugs and edge cases that will fail at runtime.\n2. Security problems: injection, missing auth checks, secrets in code.\n3. Anything that contradicts the conventions in CLAUDE.md.\n\nBe specific: file, line, what is wrong, a suggested fix. Do not restate\nwhat the code does. If you find nothing, say so in one line.\n```\n\nSave it as `.claude\u002Fagents\u002Fcode-reviewer.md` for a project (commit it so the team gets it) or `~\u002F.claude\u002Fagents\u002Fcode-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.\n\nThe fields you will use most:\n\n| Field | What it does |\n| --- | --- |\n| `description` | Tells Claude when to delegate. This is what decides if your agent is ever used |\n| `tools` \u002F `disallowedTools` | Allowlist or denylist of tools. Give a reviewer read tools only |\n| `model` | `sonnet`, `opus`, `haiku`, a full model ID, or `inherit` |\n| `permissionMode` | The [permission mode](\u002Fblog\u002Fclaude-code-permission-modes) the agent runs in |\n| `maxTurns` | A ceiling on agentic turns |\n| `skills` | [Skills](\u002Fblog\u002Fclaude-code-skills) to preload into its context |\n| `mcpServers` | [MCP servers](\u002Fblog\u002Fclaude-code-mcp-servers) scoped to this agent |\n| `isolation` | `worktree` runs it in a temporary git worktree |\n| `background` | `true` to run it in the background |\n\nThere are more (`hooks`, `memory`, `effort`, `color`), documented on the [sub-agents page](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fsub-agents). Plugin-provided subagents ignore `hooks`, `mcpServers` and `permissionMode`.\n\n## How do you write a description that Claude acts on?\n\nClaude reads the `description` of every agent to decide whether to delegate. Write it like a trigger condition, not a title.\n\n- Weak: `Code reviewer`\n- Better: `Reviews code for quality and security. Use proactively after writing or modifying code.`\n\nSay 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.\n\n## How do you invoke a subagent?\n\nThree ways:\n\n```text\nUse the code-reviewer subagent to check my recent changes\n\n@\"code-reviewer (agent)\" look at the auth changes\n```\n\nand, for a whole session run as that agent:\n\n```sh\nclaude --agent code-reviewer\n```\n\nYou can also set `\"agent\": \"code-reviewer\"` in `.claude\u002Fsettings.json`. For a throwaway agent that exists for one session only, pass JSON on the command line:\n\n```sh\nclaude --agents '{\"code-reviewer\": {\"description\": \"Reviews code. Use after changes.\", \"prompt\": \"You are a senior code reviewer.\", \"tools\": [\"Read\", \"Grep\", \"Glob\"], \"model\": \"sonnet\"}}'\n```\n\nIf two locations define the same name, the higher priority wins: managed settings, then `--agents`, then `.claude\u002Fagents\u002F`, then `~\u002F.claude\u002Fagents\u002F`, then plugins.\n\n## Foreground or background?\n\nA 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.\n\nExplore and Plan are one-shot. Other subagents can be resumed by name or ID.\n\n## Which subagents are worth writing first?\n\nStart with the jobs you repeat:\n\n1. **A reviewer**, read-only, with your team's checklist in the prompt. See [using Claude Code to review code](\u002Fblog\u002Fclaude-code-code-review).\n2. **A test runner** that runs the suite and returns only the failures and their likely cause.\n3. **A researcher** with `WebFetch` and read tools that reports back with sources.\n\nKeep 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.\n\n## In Relais\n\nRelais 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](\u002Ffeatures). Relais agents with their own browser and routines are a different thing from Claude Code subagents; they are described on the [agents page](\u002Fagents).","\u003Cp>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 \u003Ccode>.claude\u002Fagents\u002F\u003C\u002Fcode>, and Claude delegates to it when the task matches its description.\u003C\u002Fp>\n\u003Ch2 id=\"when-should-you-delegate-to-a-subagent\">\u003Ca class=\"anchor\" href=\"#when-should-you-delegate-to-a-subagent\" aria-label=\"Link to this section\">#\u003C\u002Fa>When should you delegate to a subagent?\u003C\u002Fh2>\n\u003Cp>Delegate when the work is \u003Cstrong>verbose\u003C\u002Fstrong> and you only need the conclusion:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Searching a large codebase to answer &quot;where is X handled?&quot;.\u003C\u002Fli>\n\u003Cli>Reading logs or test output and reporting the cause.\u003C\u002Fli>\n\u003Cli>Reviewing a diff with fresh eyes, without the bias of having written it.\u003C\u002Fli>\n\u003Cli>Running independent investigations at the same time.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Don&#39;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.\u003C\u002Fp>\n\u003Cp>This is the main reason subagents help with \u003Ca href=\"\u002Fblog\u002Fclaude-code-context-window\">the context window\u003C\u002Fa>: 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.\u003C\u002Fp>\n\u003Ch2 id=\"what-subagents-does-claude-code-already-have\">\u003Ca class=\"anchor\" href=\"#what-subagents-does-claude-code-already-have\" aria-label=\"Link to this section\">#\u003C\u002Fa>What subagents does Claude Code already have?\u003C\u002Fh2>\n\u003Cp>You get a few without writing anything:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Explore\u003C\u002Fstrong>: a fast, read-only agent for searching and reading a codebase. Claude picks a thoroughness: quick, medium or very thorough.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Plan\u003C\u002Fstrong>: a read-only research agent used in \u003Ca href=\"\u002Fblog\u002Fclaude-code-plan-mode\">plan mode\u003C\u002Fa>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>General-purpose\u003C\u002Fstrong>: full tool access, for multi-step tasks that need both exploring and acting.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>There are a couple of helpers too (one behind \u003Ccode>\u002Fstatusline\u003C\u002Fcode>, one that answers questions about Claude Code itself). Explore and Plan skip \u003Ccode>CLAUDE.md\u003C\u002Fcode> and the git status snapshot to stay quick and cheap. You can switch a built-in off with a deny rule such as \u003Ccode>Agent(Explore)\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-write-a-custom-subagent\">\u003Ca class=\"anchor\" href=\"#how-do-you-write-a-custom-subagent\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you write a custom subagent?\u003C\u002Fh2>\n\u003Cp>Create a Markdown file. The frontmatter configures it; the body is its system prompt.\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode>---\nname: code-reviewer\ndescription: Reviews code for quality and security. Use after writing or modifying code.\ntools: Read, Glob, Grep\nmodel: sonnet\n---\n\nYou are a code reviewer. When invoked, look at the files that changed\n(use `git diff` output if you were given it) and report:\n\n1. Bugs and edge cases that will fail at runtime.\n2. Security problems: injection, missing auth checks, secrets in code.\n3. Anything that contradicts the conventions in CLAUDE.md.\n\nBe specific: file, line, what is wrong, a suggested fix. Do not restate\nwhat the code does. If you find nothing, say so in one line.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Save it as \u003Ccode>.claude\u002Fagents\u002Fcode-reviewer.md\u003C\u002Fcode> for a project (commit it so the team gets it) or \u003Ccode>~\u002F.claude\u002Fagents\u002Fcode-reviewer.md\u003C\u002Fcode> for all your projects. Claude Code watches these folders, so a new file is picked up within seconds. Only \u003Ccode>name\u003C\u002Fcode> and \u003Ccode>description\u003C\u002Fcode> are required.\u003C\u002Fp>\n\u003Cp>The fields you will use most:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Field\u003C\u002Fth>\u003Cth>What it does\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>\u003Ccode>description\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Tells Claude when to delegate. This is what decides if your agent is ever used\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>tools\u003C\u002Fcode> \u002F \u003Ccode>disallowedTools\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Allowlist or denylist of tools. Give a reviewer read tools only\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>model\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ccode>sonnet\u003C\u002Fcode>, \u003Ccode>opus\u003C\u002Fcode>, \u003Ccode>haiku\u003C\u002Fcode>, a full model ID, or \u003Ccode>inherit\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>permissionMode\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>The \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission mode\u003C\u002Fa> the agent runs in\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>maxTurns\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>A ceiling on agentic turns\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>skills\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"\u002Fblog\u002Fclaude-code-skills\">Skills\u003C\u002Fa> to preload into its context\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>mcpServers\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ca href=\"\u002Fblog\u002Fclaude-code-mcp-servers\">MCP servers\u003C\u002Fa> scoped to this agent\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>isolation\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ccode>worktree\u003C\u002Fcode> runs it in a temporary git worktree\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>background\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ccode>true\u003C\u002Fcode> to run it in the background\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>There are more (\u003Ccode>hooks\u003C\u002Fcode>, \u003Ccode>memory\u003C\u002Fcode>, \u003Ccode>effort\u003C\u002Fcode>, \u003Ccode>color\u003C\u002Fcode>), documented on the \u003Ca href=\"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fsub-agents\">sub-agents page\u003C\u002Fa>. Plugin-provided subagents ignore \u003Ccode>hooks\u003C\u002Fcode>, \u003Ccode>mcpServers\u003C\u002Fcode> and \u003Ccode>permissionMode\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-write-a-description-that-claude-acts-on\">\u003Ca class=\"anchor\" href=\"#how-do-you-write-a-description-that-claude-acts-on\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you write a description that Claude acts on?\u003C\u002Fh2>\n\u003Cp>Claude reads the \u003Ccode>description\u003C\u002Fcode> of every agent to decide whether to delegate. Write it like a trigger condition, not a title.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Weak: \u003Ccode>Code reviewer\u003C\u002Fcode>\u003C\u002Fli>\n\u003Cli>Better: \u003Ccode>Reviews code for quality and security. Use proactively after writing or modifying code.\u003C\u002Fcode>\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>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.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-invoke-a-subagent\">\u003Ca class=\"anchor\" href=\"#how-do-you-invoke-a-subagent\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you invoke a subagent?\u003C\u002Fh2>\n\u003Cp>Three ways:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>Use the code-reviewer subagent to check my recent changes\n\n@&quot;code-reviewer (agent)&quot; look at the auth changes\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>and, for a whole session run as that agent:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude --agent code-reviewer\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>You can also set \u003Ccode>&quot;agent&quot;: &quot;code-reviewer&quot;\u003C\u002Fcode> in \u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode>. For a throwaway agent that exists for one session only, pass JSON on the command line:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude --agents '{&quot;code-reviewer&quot;: {&quot;description&quot;: &quot;Reviews code. Use after changes.&quot;, &quot;prompt&quot;: &quot;You are a senior code reviewer.&quot;, &quot;tools&quot;: [&quot;Read&quot;, &quot;Grep&quot;, &quot;Glob&quot;], &quot;model&quot;: &quot;sonnet&quot;}}'\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>If two locations define the same name, the higher priority wins: managed settings, then \u003Ccode>--agents\u003C\u002Fcode>, then \u003Ccode>.claude\u002Fagents\u002F\u003C\u002Fcode>, then \u003Ccode>~\u002F.claude\u002Fagents\u002F\u003C\u002Fcode>, then plugins.\u003C\u002Fp>\n\u003Ch2 id=\"foreground-or-background\">\u003Ca class=\"anchor\" href=\"#foreground-or-background\" aria-label=\"Link to this section\">#\u003C\u002Fa>Foreground or background?\u003C\u002Fh2>\n\u003Cp>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.\u003C\u002Fp>\n\u003Cp>Explore and Plan are one-shot. Other subagents can be resumed by name or ID.\u003C\u002Fp>\n\u003Ch2 id=\"which-subagents-are-worth-writing-first\">\u003Ca class=\"anchor\" href=\"#which-subagents-are-worth-writing-first\" aria-label=\"Link to this section\">#\u003C\u002Fa>Which subagents are worth writing first?\u003C\u002Fh2>\n\u003Cp>Start with the jobs you repeat:\u003C\u002Fp>\n\u003Col>\n\u003Cli>\u003Cstrong>A reviewer\u003C\u002Fstrong>, read-only, with your team&#39;s checklist in the prompt. See \u003Ca href=\"\u002Fblog\u002Fclaude-code-code-review\">using Claude Code to review code\u003C\u002Fa>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A test runner\u003C\u002Fstrong> that runs the suite and returns only the failures and their likely cause.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A researcher\u003C\u002Fstrong> with \u003Ccode>WebFetch\u003C\u002Fcode> and read tools that reports back with sources.\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>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.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>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 \u003Ca href=\"\u002Ffeatures\">features page\u003C\u002Fa>. Relais agents with their own browser and routines are a different thing from Claude Code subagents; they are described on the \u003Ca href=\"\u002Fagents\">agents page\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33,36],{"id":16,"text":17},"when-should-you-delegate-to-a-subagent","When should you delegate to a subagent?",{"id":19,"text":20},"what-subagents-does-claude-code-already-have","What subagents does Claude Code already have?",{"id":22,"text":23},"how-do-you-write-a-custom-subagent","How do you write a custom subagent?",{"id":25,"text":26},"how-do-you-write-a-description-that-claude-acts-on","How do you write a description that Claude acts on?",{"id":28,"text":29},"how-do-you-invoke-a-subagent","How do you invoke a subagent?",{"id":31,"text":32},"foreground-or-background","Foreground or background?",{"id":34,"text":35},"which-subagents-are-worth-writing-first","Which subagents are worth writing first?",{"id":37,"text":38},"in-relais","In Relais",[40,45,51],{"slug":41,"title":42,"description":43,"category":7,"categoryId":8,"keyword":44,"date":10,"minutes":11},"claude-code-beginners-guide","Claude Code for beginners: install, first session, habits","Install Claude Code, run your first session and learn the habits that matter: specific prompts, plan before edit, CLAUDE.md, small commits, a clean context.","claude code for beginners",{"slug":46,"title":47,"description":48,"category":7,"categoryId":8,"keyword":49,"date":10,"minutes":50},"claude-code-hooks","Claude Code hooks: run a script on every tool call","Claude Code hooks run your own script before or after a tool call. Learn the config format, exit codes and three working examples you can paste today.","claude code hooks",6,{"slug":52,"title":53,"description":54,"category":7,"categoryId":8,"keyword":55,"date":10,"minutes":11},"claude-code-permission-modes","Claude Code permission modes explained (and when to use each)","Default, acceptEdits, plan, auto, dontAsk and bypassPermissions: what each Claude Code permission mode allows, how to switch, and which one fits which job.","claude code permission modes",1794931098788]