{"id":168715,"date":"2026-06-13T21:39:45","date_gmt":"2026-06-13T18:39:45","guid":{"rendered":"https:\/\/computingforgeeks.com\/?p=168715"},"modified":"2026-06-13T21:39:45","modified_gmt":"2026-06-13T18:39:45","slug":"claude-code-subagents-guide","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/claude-code-subagents-guide\/","title":{"rendered":"Claude Code Subagents: Configure Specialized AI Agents"},"content":{"rendered":"

You ask Claude Code to add a feature, and halfway through it spends a thousand tokens grepping the codebase, then dumps the results into the same conversation you are trying to keep clean. A subagent solves exactly that. It does the messy side work in its own context window and hands back only the summary, so your main thread stays focused on the actual task.<\/p>\n\n

This is the complete guide to Claude Code subagents: what they are (and the thing most write-ups get wrong about parallelism), the full frontmatter schema field by field, how Claude decides to delegate, foreground versus background, chaining a reviewer into a fixer, and the community libraries worth stealing from. Every command and the agent that catches a real SQL injection further down was run on a live install.<\/p>\n\n

Ran all of this on Claude Code 2.1.177 in June 2026; the delegation output below is the real thing, not a mock-up.<\/em><\/p>\n\n

What Claude Code subagents actually are (and are not)<\/h2>\n\n

A subagent is a specialized assistant with its own system prompt, its own tool access, and its own permissions. When Claude hits a task that matches the subagent’s description, it hands that task off. The subagent works in a separate context window and returns only its result, which is the whole point: the search results, logs, and file dumps never touch your main conversation.<\/p>\n\n

Here is the part competitors get wrong. A regular subagent runs inside a single session and blocks the main thread until it finishes.<\/strong> It is not, by itself, parallelism. Claude Code has three distinct things and they are easy to conflate:<\/p>\n\n\n

\n
Feature<\/th>What it is<\/th>Runs in parallel?<\/th><\/tr><\/thead>
Subagents<\/strong><\/td>Specialized workers inside one session, context-isolated<\/td>No by default (blocking), unless marked background<\/td><\/tr>\n
Background agents<\/strong><\/td>Many independent sessions you launch and monitor from one place<\/td>Yes<\/td><\/tr>\n
Agent teams<\/strong><\/td>Separate sessions that talk to each other<\/td>Yes, and they coordinate<\/td><\/tr>\n<\/tbody><\/table><\/figure>\n\n\n

This guide is about the first one. A single subagent can be told to run in the background (more on that below), but the mental model to start with is a focused helper that takes a side quest off your hands and reports back. The benefits stack up fast: context stays lean, you can lock a reviewer down to read-only tools, and you can route a cheap task to Haiku instead of burning Opus on it.<\/p>\n\n

1. Create your first subagent<\/h2>\n\n

The fastest way in is the built-in manager. Inside a session, run:<\/p>\n\n\n

\/agents<\/code><\/pre>\n\n\n
That opens a tabbed interface. The Library<\/strong> tab lists every subagent available to you (built-in, user, project, and plugin) and lets you create, edit, or delete one. The Running<\/strong> tab shows live and recently finished subagents so you can open or stop them. Pick Create new agent<\/strong>, choose Personal<\/strong> to save it under ~\/.claude\/agents\/<\/code> so it follows you across projects, or Project<\/strong> to drop it in the repo’s .claude directory<\/a> next to your other config. Then let Claude generate the first draft from a plain-English description. You select the tools, the model, a color, and whether it keeps memory, then save. It is usable immediately, no restart.<\/p>\n\n
The manager is the recommended path, but a subagent is just a Markdown file, and once you have seen the shape you will often write them by hand. Create the file directly:<\/p>\n\n\n
mkdir -p .claude\/agents\nvim .claude\/agents\/code-reviewer.md<\/code><\/pre>\n\n\n
The official starting point is this minimal reviewer. YAML frontmatter on top, the system prompt as the Markdown body:<\/p>\n\n\n
---\nname: code-reviewer\ndescription: Reviews code for quality and best practices\ntools: Read, Glob, Grep\nmodel: sonnet\n---\n\nYou are a code reviewer. When invoked, analyze the code and provide\nspecific, actionable feedback on quality, security, and best practices.<\/code><\/pre>\n\n\n
One gotcha that trips people up: subagents are loaded at session start. Edit a file on disk and you have to restart the session to pick up the change. Agents created or edited through \/agents<\/code> take effect right away. That asymmetry catches everyone once.<\/p>\n\n
2. The agent file, field by field<\/h2>\n\n
Only name<\/code> and description<\/code> are required. Everything else is optional, and this is the full set, which no other guide lists completely and correctly:<\/p>\n\n\n
\n
Field<\/th>What it does<\/th><\/tr><\/thead>
name<\/code><\/td>Required. Lowercase-and-hyphens identifier. Identity comes from this, not the filename.<\/td><\/tr>\n
description<\/code><\/td>Required. When Claude should delegate here. This is the most important field you write.<\/td><\/tr>\n
tools<\/code><\/td>Allowlist of tools. Omit it and the subagent inherits every tool the main thread has.<\/td><\/tr>\n
disallowedTools<\/code><\/td>Denylist. Applied before tools<\/code> resolves, so a tool named in both is removed.<\/td><\/tr>\n
model<\/code><\/td>sonnet<\/code>, opus<\/code>, haiku<\/code>, fable<\/code>, a full model ID, or inherit<\/code>. Defaults to inherit<\/code>.<\/td><\/tr>\n
permissionMode<\/code><\/td>default<\/code>, acceptEdits<\/code>, auto<\/code>, dontAsk<\/code>, bypassPermissions<\/code>, or plan<\/code>.<\/td><\/tr>\n
maxTurns<\/code><\/td>Cap on agentic turns before the subagent stops.<\/td><\/tr>\n
skills<\/code><\/td>Skills to preload into context at startup (full content injected, not just the name).<\/td><\/tr>\n
mcpServers<\/code><\/td>MCP servers exposed to this subagent only. See the MCP setup guide<\/a> for the server side.<\/td><\/tr>\n
hooks<\/code><\/td>Lifecycle hooks scoped to this subagent.<\/td><\/tr>\n
memory<\/code><\/td>user<\/code>, project<\/code>, or local<\/code>. Persists learnings across sessions.<\/td><\/tr>\n
background<\/code><\/td>true<\/code> to always run this one concurrently. Default false<\/code>.<\/td><\/tr>\n
effort<\/code><\/td>low<\/code>, medium<\/code>, high<\/code>, xhigh<\/code>, or max<\/code> (model dependent). Overrides the session.<\/td><\/tr>\n
isolation<\/code><\/td>Set to worktree<\/code> to run in a throwaway git worktree, an isolated copy of the repo.<\/td><\/tr>\n
color<\/code><\/td>A named color (red<\/code>, blue<\/code>, green<\/code>, yellow<\/code>, purple<\/code>, orange<\/code>, pink<\/code>, cyan<\/code>) for the task list and transcript.<\/td><\/tr>\n
initialPrompt<\/code><\/td>Auto-submitted as the first turn when the agent runs as the main session via --agent<\/code> or the agent<\/code> setting.<\/td><\/tr>\n<\/tbody><\/table><\/figure>\n\n\n
A few of these carry real weight. The body of the file becomes the system prompt verbatim, and the subagent gets only that prompt plus basic environment details like the working directory, not Claude Code’s full system prompt. The tools<\/code> field is your security lever: omit it for a builder that needs everything, restrict it hard for a reviewer that should never write. And model<\/code> is your cost lever, since routing a grep-heavy explorer to Haiku instead of Opus is free money.<\/p>\n\n
Two scope notes. Project agents in .claude\/agents\/<\/code> outrank personal ones in ~\/.claude\/agents\/<\/code> when names collide, with managed and CLI-flag definitions above both and plugin agents below. And if two files in the same scope declare the same name<\/code>, Claude Code keeps one and silently drops the other, so keep names unique across the whole tree. Plugin-supplied subagents also ignore hooks<\/code>, mcpServers<\/code>, and permissionMode<\/code> for security reasons.<\/p>\n\n
3. Watch it work on a real bug<\/h2>\n\n
Theory is cheap. Here is a deliberately ugly payment.py<\/code> with a SQL injection and a quadratic loop hiding in it, and the read-only reviewer from above sitting in .claude\/agents\/<\/code>:<\/p>\n\n\n
\"A<\/figure>\n\n\n
Ask Claude to use it by name and it delegates, the subagent reads the file with its three read-only tools, and the findings come back into the main thread:<\/p>\n\n\n
claude -p \"Use the code-reviewer subagent to review payment.py\"<\/code><\/pre>\n\n\n
The reviewer flagged the string-formatted query on line 6 as a SQL injection and the nested loop as an O(n^2) pass that should be a single sum, each with the exact fix. None of that touched the main conversation as raw file content; it arrived as a clean report:<\/p>\n\n\n
\"Claude<\/figure>\n\n\n
That is the entire value proposition in one screenshot. A focused agent, scoped to read-only tools, did the review in its own window and returned a tight summary.<\/p>\n\n
4. How Claude decides to delegate<\/h2>\n\n
Automatic delegation runs off the description<\/code> field. Claude reads what you wrote there, matches it against the task at hand, and hands off when they line up. So the description is not documentation, it is the trigger. Write it as the condition for use, and the near-universal convention in the popular agent libraries is to add a nudge like Use PROACTIVELY<\/code> or use immediately after writing code<\/code> to push Claude toward delegating without being asked.<\/p>\n\n
When you want a specific subagent to run and refuse to leave it to chance, there are three explicit routes:<\/p>\n\n\n