[{"data":1,"prerenderedAt":797},["ShallowReactive",2],{"guide:/guides/claude-code-subagents":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"tag":10,"date":11,"body":12,"_type":142,"_id":792,"_source":793,"_file":794,"_stem":795,"_extension":796},"/guides/claude-code-subagents","guides",false,"","Understanding Claude Code subagents (the Task tool)","What subagents are in Claude Code, how the Task tool spawns them to work in parallel, and how the SubagentStop hook lets you track them finishing.","Workflow","2026-08-15",{"type":13,"children":14,"toc":782},"root",[15,38,45,50,62,68,80,86,91,132,137,269,274,315,328,334,346,352,357,370,390,513,541,700,742,748,776],{"type":16,"tag":17,"props":18,"children":19},"element","p",{},[20,23,29,31,36],{"type":21,"value":22},"text","When a Claude Code run needs to do several independent things, like searching across a large codebase or working through a list of files, it can spawn ",{"type":16,"tag":24,"props":25,"children":26},"strong",{},[27],{"type":21,"value":28},"subagents",{"type":21,"value":30}," through the ",{"type":16,"tag":24,"props":32,"children":33},{},[34],{"type":21,"value":35},"Task",{"type":21,"value":37}," tool. Each subagent is its own agent working in parallel, and the main run gathers their results. Here is what that means, how to define your own, and how to keep an eye on it.",{"type":16,"tag":39,"props":40,"children":42},"h2",{"id":41},"what-a-subagent-is",[43],{"type":21,"value":44},"What a subagent is",{"type":16,"tag":17,"props":46,"children":47},{},[48],{"type":21,"value":49},"A subagent is a separate Claude Code agent that the main session launches to handle a scoped piece of work. Instead of doing everything itself in one long thread, the main agent fans the work out: several subagents run at once, each on its own task, and report back with a summary rather than everything they read.",{"type":16,"tag":17,"props":51,"children":52},{},[53,55,60],{"type":21,"value":54},"The important detail is that a subagent has ",{"type":16,"tag":24,"props":56,"children":57},{},[58],{"type":21,"value":59},"its own context window",{"type":21,"value":61},". It can grep through forty files, read three of them in full, and hand back six lines. None of that noise lands in the main conversation, which is why a run that uses subagents well stays coherent much longer than one that does everything inline.",{"type":16,"tag":39,"props":63,"children":65},{"id":64},"why-it-matters",[66],{"type":21,"value":67},"Why it matters",{"type":16,"tag":17,"props":69,"children":70},{},[71,73,78],{"type":21,"value":72},"Subagents make a run faster on parallelisable work, and they keep the main context clean. But they also make it ",{"type":16,"tag":24,"props":74,"children":75},{},[76],{"type":21,"value":77},"busier and harder to read",{"type":21,"value":79},": the main session can sit \"working\" for a while because five subagents are running underneath it, with nothing printed in between. Knowing whether a session is genuinely busy or actually stuck is exactly the kind of thing that gets murky here.",{"type":16,"tag":39,"props":81,"children":83},{"id":82},"defining-your-own",[84],{"type":21,"value":85},"Defining your own",{"type":16,"tag":17,"props":87,"children":88},{},[89],{"type":21,"value":90},"Beyond the generic ones Claude spawns on its own, you can define named subagents as markdown files, one per agent:",{"type":16,"tag":92,"props":93,"children":94},"ul",{},[95,115],{"type":16,"tag":96,"props":97,"children":98},"li",{},[99,104,106,113],{"type":16,"tag":24,"props":100,"children":101},{},[102],{"type":21,"value":103},"Project agents",{"type":21,"value":105},": ",{"type":16,"tag":107,"props":108,"children":110},"code",{"className":109},[],[111],{"type":21,"value":112},".claude/agents/*.md",{"type":21,"value":114},", committed with the repository and shared with your team.",{"type":16,"tag":96,"props":116,"children":117},{},[118,123,124,130],{"type":16,"tag":24,"props":119,"children":120},{},[121],{"type":21,"value":122},"User agents",{"type":21,"value":105},{"type":16,"tag":107,"props":125,"children":127},{"className":126},[],[128],{"type":21,"value":129},"~/.claude/agents/*.md",{"type":21,"value":131},", available in every project.",{"type":16,"tag":17,"props":133,"children":134},{},[135],{"type":21,"value":136},"The frontmatter declares the agent, and the body is its system prompt:",{"type":16,"tag":138,"props":139,"children":143},"pre",{"className":140,"code":141,"language":142,"meta":7,"style":7},"language-markdown shiki shiki-themes github-light github-dark","---\nname: test-runner\ndescription: Runs the test suite and fixes failing tests. Use after code changes.\ntools: Read, Edit, Bash, Grep\nmodel: sonnet\n---\n\nYou run the project's test suite, read the failures, and fix them.\n\nRun `npm test` first. Fix only what the failures point at, never refactor\naround them, and re-run until the suite is green. Report which tests failed\nand what you changed, nothing else.\n","markdown",[144],{"type":16,"tag":107,"props":145,"children":146},{"__ignoreMap":7},[147,159,169,178,187,196,204,214,223,231,251,260],{"type":16,"tag":148,"props":149,"children":152},"span",{"class":150,"line":151},"line",1,[153],{"type":16,"tag":148,"props":154,"children":156},{"style":155},"--shiki-default:#005CC5;--shiki-default-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold",[157],{"type":21,"value":158},"---\n",{"type":16,"tag":148,"props":160,"children":162},{"class":150,"line":161},2,[163],{"type":16,"tag":148,"props":164,"children":166},{"style":165},"--shiki-default:#24292E;--shiki-dark:#E1E4E8",[167],{"type":21,"value":168},"name: test-runner\n",{"type":16,"tag":148,"props":170,"children":172},{"class":150,"line":171},3,[173],{"type":16,"tag":148,"props":174,"children":175},{"style":165},[176],{"type":21,"value":177},"description: Runs the test suite and fixes failing tests. Use after code changes.\n",{"type":16,"tag":148,"props":179,"children":181},{"class":150,"line":180},4,[182],{"type":16,"tag":148,"props":183,"children":184},{"style":165},[185],{"type":21,"value":186},"tools: Read, Edit, Bash, Grep\n",{"type":16,"tag":148,"props":188,"children":190},{"class":150,"line":189},5,[191],{"type":16,"tag":148,"props":192,"children":193},{"style":165},[194],{"type":21,"value":195},"model: sonnet\n",{"type":16,"tag":148,"props":197,"children":199},{"class":150,"line":198},6,[200],{"type":16,"tag":148,"props":201,"children":202},{"style":155},[203],{"type":21,"value":158},{"type":16,"tag":148,"props":205,"children":207},{"class":150,"line":206},7,[208],{"type":16,"tag":148,"props":209,"children":211},{"emptyLinePlaceholder":210},true,[212],{"type":21,"value":213},"\n",{"type":16,"tag":148,"props":215,"children":217},{"class":150,"line":216},8,[218],{"type":16,"tag":148,"props":219,"children":220},{"style":165},[221],{"type":21,"value":222},"You run the project's test suite, read the failures, and fix them.\n",{"type":16,"tag":148,"props":224,"children":226},{"class":150,"line":225},9,[227],{"type":16,"tag":148,"props":228,"children":229},{"emptyLinePlaceholder":210},[230],{"type":21,"value":213},{"type":16,"tag":148,"props":232,"children":234},{"class":150,"line":233},10,[235,240,246],{"type":16,"tag":148,"props":236,"children":237},{"style":165},[238],{"type":21,"value":239},"Run ",{"type":16,"tag":148,"props":241,"children":243},{"style":242},"--shiki-default:#005CC5;--shiki-dark:#79B8FF",[244],{"type":21,"value":245},"`npm test`",{"type":16,"tag":148,"props":247,"children":248},{"style":165},[249],{"type":21,"value":250}," first. Fix only what the failures point at, never refactor\n",{"type":16,"tag":148,"props":252,"children":254},{"class":150,"line":253},11,[255],{"type":16,"tag":148,"props":256,"children":257},{"style":165},[258],{"type":21,"value":259},"around them, and re-run until the suite is green. Report which tests failed\n",{"type":16,"tag":148,"props":261,"children":263},{"class":150,"line":262},12,[264],{"type":16,"tag":148,"props":265,"children":266},{"style":165},[267],{"type":21,"value":268},"and what you changed, nothing else.\n",{"type":16,"tag":17,"props":270,"children":271},{},[272],{"type":21,"value":273},"A few things to get right:",{"type":16,"tag":92,"props":275,"children":276},{},[277,288,299,310],{"type":16,"tag":96,"props":278,"children":279},{},[280,286],{"type":16,"tag":107,"props":281,"children":283},{"className":282},[],[284],{"type":21,"value":285},"description",{"type":21,"value":287}," is how the main agent decides to delegate, so write it as a trigger (\"use after code changes\"), not as a title.",{"type":16,"tag":96,"props":289,"children":290},{},[291,297],{"type":16,"tag":107,"props":292,"children":294},{"className":293},[],[295],{"type":21,"value":296},"tools",{"type":21,"value":298}," narrows what the subagent may do. Leave it out and it inherits the full set; naming a short list is both safer and cheaper.",{"type":16,"tag":96,"props":300,"children":301},{},[302,308],{"type":16,"tag":107,"props":303,"children":305},{"className":304},[],[306],{"type":21,"value":307},"model",{"type":21,"value":309}," pins a model per agent, which is worth it when a task is mechanical enough for a smaller one.",{"type":16,"tag":96,"props":311,"children":312},{},[313],{"type":21,"value":314},"A project agent and a user agent with the same name collide, and the project one wins.",{"type":16,"tag":17,"props":316,"children":317},{},[318,320,326],{"type":21,"value":319},"The ",{"type":16,"tag":107,"props":321,"children":323},{"className":322},[],[324],{"type":21,"value":325},"/agents",{"type":21,"value":327}," command inside a session lists what is available and walks you through creating one, writing the same files for you.",{"type":16,"tag":39,"props":329,"children":331},{"id":330},"getting-one-to-actually-run",[332],{"type":21,"value":333},"Getting one to actually run",{"type":16,"tag":17,"props":335,"children":336},{},[337,339,344],{"type":21,"value":338},"Delegation is a decision the main agent makes, based on the ",{"type":16,"tag":107,"props":340,"children":342},{"className":341},[],[343],{"type":21,"value":285},{"type":21,"value":345}," you wrote, so a vague one means your agent never gets used. Two things fix that: phrase the description as a situation rather than a capability, and say so in the prompt when you want it. \"Use the test-runner agent on the auth module\" is unambiguous, and it also tells you whether the agent is doing its job before you rely on it being picked automatically.",{"type":16,"tag":39,"props":347,"children":349},{"id":348},"where-subagents-do-not-help",[350],{"type":21,"value":351},"Where subagents do not help",{"type":16,"tag":17,"props":353,"children":354},{},[355],{"type":21,"value":356},"They are not free. Each one starts from a blank context, so it knows nothing about the conversation so far beyond the instructions it is handed, and briefing it properly costs tokens. A subagent also cannot spawn its own subagents, and it cannot ask you a question mid-flight. That makes them excellent for wide, read-heavy work (search, audit, review, per-file transformations) and poor for anything that needs the thread of the discussion you have been having.",{"type":16,"tag":39,"props":358,"children":360},{"id":359},"the-subagentstop-hook",[361,362,368],{"type":21,"value":319},{"type":16,"tag":107,"props":363,"children":365},{"className":364},[],[366],{"type":21,"value":367},"SubagentStop",{"type":21,"value":369}," hook",{"type":16,"tag":17,"props":371,"children":372},{},[373,375,380,382,388],{"type":21,"value":374},"Claude Code fires a dedicated hook, ",{"type":16,"tag":107,"props":376,"children":378},{"className":377},[],[379],{"type":21,"value":367},{"type":21,"value":381},", each time a subagent finishes, distinct from ",{"type":16,"tag":107,"props":383,"children":385},{"className":384},[],[386],{"type":21,"value":387},"Stop",{"type":21,"value":389},", which fires when the whole turn ends. That lets you track subagents completing independently:",{"type":16,"tag":138,"props":391,"children":395},{"className":392,"code":393,"language":394,"meta":7,"style":7},"language-json shiki shiki-themes github-light github-dark","{\n  \"hooks\": {\n    \"SubagentStop\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"echo 'a subagent finished' >> ~/claude-subagents.log\" }] }\n    ]\n  }\n}\n","json",[396],{"type":16,"tag":107,"props":397,"children":398},{"__ignoreMap":7},[399,407,420,433,489,497,505],{"type":16,"tag":148,"props":400,"children":401},{"class":150,"line":151},[402],{"type":16,"tag":148,"props":403,"children":404},{"style":165},[405],{"type":21,"value":406},"{\n",{"type":16,"tag":148,"props":408,"children":409},{"class":150,"line":161},[410,415],{"type":16,"tag":148,"props":411,"children":412},{"style":242},[413],{"type":21,"value":414},"  \"hooks\"",{"type":16,"tag":148,"props":416,"children":417},{"style":165},[418],{"type":21,"value":419},": {\n",{"type":16,"tag":148,"props":421,"children":422},{"class":150,"line":171},[423,428],{"type":16,"tag":148,"props":424,"children":425},{"style":242},[426],{"type":21,"value":427},"    \"SubagentStop\"",{"type":16,"tag":148,"props":429,"children":430},{"style":165},[431],{"type":21,"value":432},": [\n",{"type":16,"tag":148,"props":434,"children":435},{"class":150,"line":180},[436,441,446,451,456,460,466,471,475,479,484],{"type":16,"tag":148,"props":437,"children":438},{"style":165},[439],{"type":21,"value":440},"      { ",{"type":16,"tag":148,"props":442,"children":443},{"style":242},[444],{"type":21,"value":445},"\"hooks\"",{"type":16,"tag":148,"props":447,"children":448},{"style":165},[449],{"type":21,"value":450},": [{ ",{"type":16,"tag":148,"props":452,"children":453},{"style":242},[454],{"type":21,"value":455},"\"type\"",{"type":16,"tag":148,"props":457,"children":458},{"style":165},[459],{"type":21,"value":105},{"type":16,"tag":148,"props":461,"children":463},{"style":462},"--shiki-default:#032F62;--shiki-dark:#9ECBFF",[464],{"type":21,"value":465},"\"command\"",{"type":16,"tag":148,"props":467,"children":468},{"style":165},[469],{"type":21,"value":470},", ",{"type":16,"tag":148,"props":472,"children":473},{"style":242},[474],{"type":21,"value":465},{"type":16,"tag":148,"props":476,"children":477},{"style":165},[478],{"type":21,"value":105},{"type":16,"tag":148,"props":480,"children":481},{"style":462},[482],{"type":21,"value":483},"\"echo 'a subagent finished' >> ~/claude-subagents.log\"",{"type":16,"tag":148,"props":485,"children":486},{"style":165},[487],{"type":21,"value":488}," }] }\n",{"type":16,"tag":148,"props":490,"children":491},{"class":150,"line":189},[492],{"type":16,"tag":148,"props":493,"children":494},{"style":165},[495],{"type":21,"value":496},"    ]\n",{"type":16,"tag":148,"props":498,"children":499},{"class":150,"line":198},[500],{"type":16,"tag":148,"props":501,"children":502},{"style":165},[503],{"type":21,"value":504},"  }\n",{"type":16,"tag":148,"props":506,"children":507},{"class":150,"line":206},[508],{"type":16,"tag":148,"props":509,"children":510},{"style":165},[511],{"type":21,"value":512},"}\n",{"type":16,"tag":17,"props":514,"children":515},{},[516,518,524,525,531,533,539],{"type":21,"value":517},"The payload carries the usual ",{"type":16,"tag":107,"props":519,"children":521},{"className":520},[],[522],{"type":21,"value":523},"session_id",{"type":21,"value":470},{"type":16,"tag":107,"props":526,"children":528},{"className":527},[],[529],{"type":21,"value":530},"transcript_path",{"type":21,"value":532}," and ",{"type":16,"tag":107,"props":534,"children":536},{"className":535},[],[537],{"type":21,"value":538},"cwd",{"type":21,"value":540},", so on a machine running several projects you can tell which one the subagent belonged to:",{"type":16,"tag":138,"props":542,"children":546},{"className":543,"code":544,"language":545,"meta":7,"style":7},"language-bash shiki shiki-themes github-light github-dark","#!/usr/bin/env bash\npayload=$(cat)\nproject=$(basename \"$(echo \"$payload\" | jq -r '.cwd')\")\necho \"$(date +%H:%M:%S) $project subagent done\" >> ~/claude-subagents.log\n","bash",[547],{"type":16,"tag":107,"props":548,"children":549},{"__ignoreMap":7},[550,559,589,659],{"type":16,"tag":148,"props":551,"children":552},{"class":150,"line":151},[553],{"type":16,"tag":148,"props":554,"children":556},{"style":555},"--shiki-default:#6A737D;--shiki-dark:#6A737D",[557],{"type":21,"value":558},"#!/usr/bin/env bash\n",{"type":16,"tag":148,"props":560,"children":561},{"class":150,"line":161},[562,567,573,578,584],{"type":16,"tag":148,"props":563,"children":564},{"style":165},[565],{"type":21,"value":566},"payload",{"type":16,"tag":148,"props":568,"children":570},{"style":569},"--shiki-default:#D73A49;--shiki-dark:#F97583",[571],{"type":21,"value":572},"=",{"type":16,"tag":148,"props":574,"children":575},{"style":165},[576],{"type":21,"value":577},"$(",{"type":16,"tag":148,"props":579,"children":581},{"style":580},"--shiki-default:#6F42C1;--shiki-dark:#B392F0",[582],{"type":21,"value":583},"cat",{"type":16,"tag":148,"props":585,"children":586},{"style":165},[587],{"type":21,"value":588},")\n",{"type":16,"tag":148,"props":590,"children":591},{"class":150,"line":171},[592,597,601,605,610,615,620,625,630,635,640,645,650,655],{"type":16,"tag":148,"props":593,"children":594},{"style":165},[595],{"type":21,"value":596},"project",{"type":16,"tag":148,"props":598,"children":599},{"style":569},[600],{"type":21,"value":572},{"type":16,"tag":148,"props":602,"children":603},{"style":165},[604],{"type":21,"value":577},{"type":16,"tag":148,"props":606,"children":607},{"style":580},[608],{"type":21,"value":609},"basename",{"type":16,"tag":148,"props":611,"children":612},{"style":462},[613],{"type":21,"value":614}," \"$(",{"type":16,"tag":148,"props":616,"children":617},{"style":242},[618],{"type":21,"value":619},"echo",{"type":16,"tag":148,"props":621,"children":622},{"style":462},[623],{"type":21,"value":624}," \"",{"type":16,"tag":148,"props":626,"children":627},{"style":165},[628],{"type":21,"value":629},"$payload",{"type":16,"tag":148,"props":631,"children":632},{"style":462},[633],{"type":21,"value":634},"\" ",{"type":16,"tag":148,"props":636,"children":637},{"style":569},[638],{"type":21,"value":639},"|",{"type":16,"tag":148,"props":641,"children":642},{"style":580},[643],{"type":21,"value":644}," jq",{"type":16,"tag":148,"props":646,"children":647},{"style":242},[648],{"type":21,"value":649}," -r",{"type":16,"tag":148,"props":651,"children":652},{"style":462},[653],{"type":21,"value":654}," '.cwd')\"",{"type":16,"tag":148,"props":656,"children":657},{"style":165},[658],{"type":21,"value":588},{"type":16,"tag":148,"props":660,"children":661},{"class":150,"line":180},[662,666,670,675,680,685,690,695],{"type":16,"tag":148,"props":663,"children":664},{"style":242},[665],{"type":21,"value":619},{"type":16,"tag":148,"props":667,"children":668},{"style":462},[669],{"type":21,"value":614},{"type":16,"tag":148,"props":671,"children":672},{"style":580},[673],{"type":21,"value":674},"date",{"type":16,"tag":148,"props":676,"children":677},{"style":462},[678],{"type":21,"value":679}," +%H:%M:%S) ",{"type":16,"tag":148,"props":681,"children":682},{"style":165},[683],{"type":21,"value":684},"$project",{"type":16,"tag":148,"props":686,"children":687},{"style":462},[688],{"type":21,"value":689}," subagent done\"",{"type":16,"tag":148,"props":691,"children":692},{"style":569},[693],{"type":21,"value":694}," >>",{"type":16,"tag":148,"props":696,"children":697},{"style":462},[698],{"type":21,"value":699}," ~/claude-subagents.log\n",{"type":16,"tag":17,"props":701,"children":702},{},[703,705,710,712,719,721,726,728,733,734,740],{"type":21,"value":704},"One warning if you plan to notify on it: a fan-out of eight subagents fires this hook eight times in a row. Wire ",{"type":16,"tag":107,"props":706,"children":708},{"className":707},[],[709],{"type":21,"value":367},{"type":21,"value":711}," to a desktop alert or a sound and you will regret it within one run. Counting is fine; announcing is not. See the ",{"type":16,"tag":713,"props":714,"children":716},"a",{"href":715},"/guides/claude-code-hook-events",[717],{"type":21,"value":718},"reference of every hook event",{"type":21,"value":720}," for how ",{"type":16,"tag":107,"props":722,"children":724},{"className":723},[],[725],{"type":21,"value":367},{"type":21,"value":727}," sits alongside ",{"type":16,"tag":107,"props":729,"children":731},{"className":730},[],[732],{"type":21,"value":387},{"type":21,"value":470},{"type":16,"tag":107,"props":735,"children":737},{"className":736},[],[738],{"type":21,"value":739},"Notification",{"type":21,"value":741}," and the rest.",{"type":16,"tag":39,"props":743,"children":745},{"id":744},"seeing-busy-with-subagents-at-a-glance",[746],{"type":21,"value":747},"Seeing \"busy with subagents\" at a glance",{"type":16,"tag":17,"props":749,"children":750},{},[751,753,759,761,767,769,774],{"type":21,"value":752},"The number of live subagents is a great signal for ",{"type":16,"tag":754,"props":755,"children":756},"em",{},[757],{"type":21,"value":758},"how busy",{"type":21,"value":760}," a session really is, but a log line does not convey it, and a notification per subagent is worse than nothing. ",{"type":16,"tag":713,"props":762,"children":764},{"href":763},"/",[765],{"type":21,"value":766},"Blooby",{"type":21,"value":768}," reads ",{"type":16,"tag":107,"props":770,"children":772},{"className":771},[],[773],{"type":21,"value":367},{"type":21,"value":775}," (and every other event) and reflects it in the session's mascot, so a session churning through subagents visibly looks hard at work, and you can tell it apart from one that is idle or waiting on you.",{"type":16,"tag":777,"props":778,"children":779},"style",{},[780],{"type":21,"value":781},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":7,"searchDepth":161,"depth":161,"links":783},[784,785,786,787,788,789,791],{"id":41,"depth":161,"text":44},{"id":64,"depth":161,"text":67},{"id":82,"depth":161,"text":85},{"id":330,"depth":161,"text":333},{"id":348,"depth":161,"text":351},{"id":359,"depth":161,"text":790},"The SubagentStop hook",{"id":744,"depth":161,"text":747},"content:guides:claude-code-subagents.md","content","guides/claude-code-subagents.md","guides/claude-code-subagents","md",1]