{"slug": "claude-code-subagents-setup-config-and-when-to-use-them", "title": "Claude Code Subagents: Setup, Config, and When to Use Them", "summary": "Anthropic's Claude Code subagents provide isolated context windows and restricted tool allowlists to handle noisy, parallelizable tasks, keeping main conversation context clean. The feature is distinct from Skills and MCP servers, and is best used for codebase exploration, automated test runs, and research tasks, while trivial lookups and dependent tasks are poor fits.", "body_md": "# Claude Code Subagents: Setup, Config, and When to Use Them\n\nDelegate the noisy work, keep your context clean.\n\nMost Claude Code sessions get slow and cluttered for the same reason: every exploratory grep, every log dump, and every “let me check one more file” stays in the main conversation forever.\n\nSubagents exist to fix exactly that problem. They are one of the agent primitives built into [Claude Code](https://www.glukhov.org/ai-devtools/claude-code/) for handling noisy, parallelizable work — a way to push the mess into an isolated window and bring back only the summary that matters.\n\nA subagent is not a smarter Claude, and it is not the same thing as a Skill. It is a separate reasoning agent with its own context window, its own tool allowlist, and no memory of your current conversation unless you explicitly fork it. Understanding that distinction is the difference between a subagent setup that quietly saves you context budget and one that just adds latency for no benefit.\n\n## Subagents vs Skills vs MCP\n\nClaude Code gives you three extension points that solve different problems, and they get conflated constantly because all three can technically “help with a task.”\n\n| Layer | What it is | When to reach for it |\n|---|---|---|\n| Skill | Instructions loaded into the main agent’s context on demand |\nReusable procedures, checklists, playbooks — see\n|\n\n*out*of the main sessionA useful rule of thumb: a hook enforces a hard constraint deterministically, a Skill gives the main agent a capability inline, and a subagent is for work you want to delegate and keep out of the main context entirely. If a Skill’s job is to orchestrate a tool that doesn’t exist yet, that is usually a sign you need an MCP server, not a subagent. Claude Code isn’t alone in this shape — OpenCode’s ecosystem has a comparable idea in its [specialised agents](https://www.glukhov.org/ai-devtools/opencode/oh-my-opencode-agents/), which split planning, research, and review across dedicated roles in a similar way.\n\n## What a subagent actually is\n\nThree properties define a Claude Code subagent, and all three matter for how you use it:\n\n**Isolated context.** A subagent starts with a fresh window. It does not see your conversation history unless you explicitly fork it, which keeps its output from being polluted by whatever you discussed three turns ago.**A restricted tool allowlist.** Subagents can only use a subset of what the parent session already has — they cannot grant themselves new capabilities, and a well-designed subagent should get only the tools its job requires (read-only tools for a research agent, for example).**No cross-subagent visibility.** Subagents cannot see each other’s work in progress. If task B genuinely needs task A’s output, that is a sequential dependency, not something you can parallelize across two subagents.\n\nThe trigger for reaching for one is not “this task is hard.” It is “this task is noisy” — the kind of work that generates a lot of intermediate output (dozens of file reads, a long log, an exploratory grep across the whole repo) where none of that intermediate material needs to survive into your next conversation turn.\n\n## When to use a subagent (and when not to)\n\nGood fits: codebase exploration before a big change, automated test runs where you only care about pass/fail and failure summaries, security or style reviews, and any multi-step research task whose raw output would otherwise flood your main session.\n\nBad fits: two-second lookups (“what does this function return”), anything requiring tight back-and-forth refinement, and dependent tasks you’re tempted to “parallelize” even though the second one needs the first one’s answer. Using a subagent for a trivial lookup just adds the overhead of spinning up a fresh context window for no real isolation benefit.\n\n## Measuring the payoff: context and cost math\n\nThe pitch for subagents is abstract until you put numbers on a real task. Take a common one: grep a ~500-file service for every place a deprecated config key is still read, then report the exact file:line matches.\n\n| Approach | Main-session context consumed | What survives into your next turn |\n|---|---|---|\n| Direct exploration, no subagent | ~35-45K tokens — every grep hit, every file you opened to double-check, every dead end | All of it, including the wrong turns |\n| Delegated to an Explore subagent | ~1.5-3K tokens — one summarized report | Only the findings that mattered |\n\nThat’s roughly a 15-20x reduction in what your main session has to carry for that step, which is the actual mechanism behind “subagents keep sessions faster” — it is not magic, it is context that never gets loaded in the first place.\n\nThe cost side compounds the same way. Using the pricing from the [Claude Code pricing breakdown](https://www.glukhov.org/ai-devtools/claude-code/), running that same exploration pass on Opus ($5/MTok input, $25/MTok output) costs roughly $0.20-0.25 for the ~40K input tokens alone. Routing it to Haiku ($1/MTok input, $5/MTok output) drops that to $0.04-0.05 — and the main session’s Opus budget is never touched by the exploration tokens at all, since it only ever sees the ~2K-token summary.\n\n## Defining a custom subagent\n\nCustom subagents live as Markdown files with YAML frontmatter, either project-scoped in `.claude/agents/`\n\n(committed to the repo, shared by the whole team) or user-scoped in `~/.claude/agents/`\n\n(personal tools you bring to every project).\n\n```\n---\nname: code-reviewer\ndescription: >\n  Reviews staged changes for bugs, security issues, and style violations\n  before commit. Use when the user asks to review, audit, or check\n  changes prior to committing or opening a PR.  \ntools: Read, Grep, Glob\nmodel: sonnet\nskills:\n  - security-checklist\n---\nYou are a careful code reviewer. Read the staged diff, flag concrete\nissues with file:line references, and end with a short pass/fail summary.\nDo not modify any files.\n```\n\nThe `description`\n\nfield is the most important line in the file. It is what the parent session’s routing logic reads to decide whether this subagent fits the current task. Write it like a job posting — name the trigger condition explicitly, not a vague “helps with code.” Vague descriptions get skipped or misapplied by automatic dispatch.\n\nThe `tools`\n\nfield is your isolation boundary. Give a research subagent `Read`\n\n, `Grep`\n\n, and `Glob`\n\nand nothing else; giving it every tool available defeats the entire point of running it in a restricted sandbox. The optional `skills`\n\nfield preloads the full content of named Skills into the subagent’s startup context — useful when a subagent needs domain knowledge without spending a turn discovering and loading it mid-task.\n\n## Model routing: cheap models for grunt work\n\nSubagents are also where cost control gets real. Route file discovery, log scanning, and other cheap-to-verify work to Haiku, and reserve Sonnet or Opus for the reasoning-heavy steps — architecture decisions, ambiguous debugging, anything where getting it wrong is expensive. Haiku is roughly 15x cheaper per token than Opus, and on the kind of noisy exploration subagents are built for, that gap adds up fast across a real working session.\n\n## The Explore, Plan, Execute pattern\n\nFor complex, multi-step work, the pattern that holds up in practice is Explore, Plan, Execute — using cheap subagents for the parts that generate noise, and keeping the human review gate in the one place it actually matters.\n\nThe key detail people get backwards is where the review gate belongs. Exploration is cheap, so let a subagent read freely without asking permission first. Planning is analytical, so let the agent design the approach on its own. But before any agent modifies files, you want to see the plan and approve it — that is what Claude Code’s plan mode (`permissionMode: plan`\n\n) is for, and it is the same principle discussed in the broader [vibe coding best practices](https://www.glukhov.org/ai-devtools/vibe-coding/) around reviewing every diff before it lands.\n\n## Common mistakes\n\nA handful of mistakes show up repeatedly once teams start writing custom subagents:\n\n**Vague descriptions.**“Helps with code” will never route correctly. Name the exact trigger condition.** Over-broad tool access.**Giving a read-only research subagent write and bash access removes the isolation guarantee that made it worth creating in the first place.**Parallelizing dependent tasks.** If task B needs task A’s finished output, run them sequentially — subagents cannot coordinate mid-task the way a shared orchestrator can. For workflows that genuinely need agents talking to each other mid-task, that’s a different shape of problem; see[multi-agent orchestration patterns](https://www.glukhov.org/ai-systems/architecture/multi-agent-orchestration-patterns/)if you’re building a production system rather than a single-repo workflow.**Using a subagent for trivial work.**“Format this JSON” or “run this one command” doesn’t need a fresh context window; just do it directly.\n\n## Worked example: a code-review subagent end to end\n\nSay you want every non-trivial commit reviewed before it lands. Drop the `code-reviewer`\n\ndefinition shown earlier into `.claude/agents/code-reviewer.md`\n\n, commit it so the whole team shares the same reviewer, and invoke it with a natural request like “review my staged changes before I commit.” Claude Code matches your request against the subagent’s `description`\n\n, spins it up with only `Read`\n\n, `Grep`\n\n, and `Glob`\n\naccess, and it comes back with file:line-referenced findings and a pass/fail summary — none of the file-by-file noise from getting there ever touches your main session.\n\nWhat that looks like in the main transcript, annotated:\n\n```\nYou:  review my staged changes before I commit\n\nMain: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,\n       zero of it shown here]\n\nMain: code-reviewer findings:\n      - auth/session.go:142 — token refresh path doesn't handle expired\n        refresh token; falls through to nil dereference\n      - auth/session.go:203 — style: error wrapped without %w\n      PASS/FAIL: FAIL (1 blocking issue)\n```\n\nSix file reads and a grep pass happened, and your main session paid for exactly four lines of it. That gap — everything the subagent did versus the three-line summary you actually see — is the entire value proposition in one transcript.\n\nIf your team also uses Spec-Driven Development scaffolds, a review subagent slots naturally into the validation step; see [GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows](https://www.glukhov.org/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/) for how that review gate compares across portable and IDE-integrated SDD setups.\n\n## Is it worth setting up custom subagents?\n\nNot on day one. The built-in general-purpose subagent already covers most exploration and research delegation without you writing a single YAML file, and a single Explore-Plan-Execute pass is enough for most day-to-day work. Write a custom `.claude/agents/*.md`\n\nfile only once you’ve delegated the *same* task by hand three times — a code reviewer, a test-runner triager, a docs-lookup agent for one specific internal library. Teams that write five subagents in their first week usually end up with five stale `description`\n\nfields nobody updates when the actual trigger condition drifts, which quietly breaks automatic routing months later. Start with zero custom subagents, add one at a time, and only when repetition — not theoretical usefulness — demands it.\n\n## Known limitations\n\nA few rough edges are worth knowing before you build around subagents:\n\n**No recursive delegation.** A subagent cannot spawn its own subagents. If a task genuinely needs a second layer of delegation, that is a sign you want a different orchestration shape — see[multi-agent orchestration patterns](https://www.glukhov.org/ai-systems/architecture/multi-agent-orchestration-patterns/)for what that looks like outside a single Claude Code session.**No memory across invocations.** Every dispatch starts from zero, even if you called the same subagent five minutes ago on a related task. There is no built-in mechanism for a subagent to remember its last run.**Isolation is a tool allowlist, not a sandbox.** A subagent with`Bash`\n\naccess can still touch the filesystem and network like any other tool call. Restricting`tools`\n\nreduces blast radius; it does not create a hard security boundary.\n\n## Troubleshooting\n\n**Subagent never triggers.** The description is almost always the problem. Rewrite it around the specific trigger condition instead of a general capability statement, and double-check the file lives in `.claude/agents/`\n\n(project) or `~/.claude/agents/`\n\n(personal) with the right extension.\n\n**Subagent burns too much context anyway.** Check the `tools`\n\nallowlist — an overly broad toolset invites overly broad exploration. Also check whether the task should have been split into two subagents instead of one doing everything.\n\n**A listed skill doesn’t load inside the subagent.** Claude Code skips a missing or disabled skill named in the `skills`\n\nfield rather than failing the run, and logs a line to that effect in the debug output (`/debug`\n\nfrom the main session, then reproduce the dispatch) — something like `skill \"security-checklist\" not found, skipping`\n\n. Run `/doctor`\n\nafterward to confirm the rest of your setup is healthy.\n\n**Results feel inconsistent between runs.** This is often a model-routing issue, not a subagent-design issue — reasoning-heavy work assigned to a cheap model will vary more. Move it to Sonnet or Opus and keep Haiku for the deterministic, low-ambiguity steps.\n\nSubagents are one piece of a much larger toolbox; if you’re comparing Claude Code against the rest of the [AI developer tools ecosystem](https://www.glukhov.org/ai-devtools/) before committing to this workflow, that overview is a good next stop.\n\n## Useful links\n\n[Claude Code install and config for Ollama, llama.cpp, pricing](https://www.glukhov.org/ai-devtools/claude-code/)[Claude Skills and SKILL.md for Developers](https://www.glukhov.org/ai-devtools/claude-code/claude-skills-for-developers/)[GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows](https://www.glukhov.org/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/)[What is Vibe Coding?](https://www.glukhov.org/ai-devtools/vibe-coding/)[Multi-Agent Orchestration Patterns: A Practical Guide](https://www.glukhov.org/ai-systems/architecture/multi-agent-orchestration-patterns/)[Oh My Opencode Specialised Agents Deep Dive](https://www.glukhov.org/ai-devtools/opencode/oh-my-opencode-agents/)[AI Developer Tools: The Complete Guide](https://www.glukhov.org/ai-devtools/)", "url": "https://wpnews.pro/news/claude-code-subagents-setup-config-and-when-to-use-them", "canonical_source": "https://www.glukhov.org/ai-devtools/claude-code/claude-code-subagents/", "published_at": "2026-08-04 07:16:42+00:00", "updated_at": "2026-08-04 09:33:24.341687+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["Claude Code", "Anthropic", "OpenCode"], "alternates": {"html": "https://wpnews.pro/news/claude-code-subagents-setup-config-and-when-to-use-them", "markdown": "https://wpnews.pro/news/claude-code-subagents-setup-config-and-when-to-use-them.md", "text": "https://wpnews.pro/news/claude-code-subagents-setup-config-and-when-to-use-them.txt", "jsonld": "https://wpnews.pro/news/claude-code-subagents-setup-config-and-when-to-use-them.jsonld"}}