When you work with Claude Code on a real codebase, the bottleneck is rarely the model’s intelligence. It’s context. Every file you read, every test log, every documentation page you fetch competes for the same finite context window. Run a broad search across an unfamiliar repo and the useful signal gets buried under thousands of lines of grep output that you’ll never look at again.
Subagents are Claude Code’s answer to that problem. A subagent is a specialized assistant that runs in its own context window, with its own system prompt, its own tool access, and its own permissions. It does the noisy work somewhere else and hands back only the summary. Think of it as delegating to a teammate: you don’t want their entire research process dumped on your desk, you want the conclusion.
The single most important thing about a subagent is that it has a fresh, isolated context. It doesn’t see your conversation history, the files already in your main session, or the skills you’ve loaded. Claude composes a short delegation message describing the task, the subagent works from there, and when it finishes only its final result returns to your conversation.
This buys you several things at once:
Read, Grep, and Glob literally cannot edit your files.The trade-off is startup latency: a subagent begins from zero and may need a moment to gather context. Keep that tension in mind throughout this post. Isolation is powerful, but it isn’t free.
Before you write a single config file, Claude Code already delegates on your behalf. Three built-ins do most of the work:
Write and Edit are denied. When Claude needs to find where something lives without changing anything, this is what it reaches for. You’ll see it pick a thoroughness level (quick, medium, or very thorough) depending on how much ground it needs to cover.Explore and Plan deliberately skip your CLAUDE.md files and git status to stay fast and cheap. That’s a reasonable default, but worth knowing: if a rule like “ignore the vendor/ directory” matters to a search, you need to restate it in your prompt rather than assume the subagent inherited it.
A subagent is just a Markdown file with YAML frontmatter. The frontmatter is configuration; the body is the system prompt.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Only name and description are required. Drop the file in one of these locations, listed from highest to lowest priority when names collide:
| Location | Scope |
|---|---|
.claude/agents/ | Current project. Check into version control so the team shares it |
~/.claude/agents/ | All your projects. Your personal, portable agents |
A plugin’s agents/ directory | Wherever that plugin is enabled |
The friendlier path is the /agents command, which opens a tabbed interface. The Library tab lets you create an agent with guided setup. You can even describe what you want in plain English and let Claude generate the identifier, description, and system prompt for you, then pick which tools and model it gets. Agents created this way take effect immediately. Files you add by hand are loaded at session start, so you’ll need to restart to pick them up.
You can get a long way with just name, description, tools, and model, but a few more fields unlock the interesting behavior:
description is the one Claude reads to decide when to delegate. Make it action-oriented and specific. If the real job is “inspect auth changes and look for unsafe patterns”, say exactly that. Adding “use proactively” nudges Claude to reach for it without being asked.tools is an allowlist. Omit it and the subagent inherits everything the main conversation has. Tighten it aggressively: if an agent only needs to read, don’t give it write access.disallowedTools is a denylist, applied before tools. Handy when you want “everything except writes”: disallowedTools: Write, Edit.model accepts haiku, sonnet, opus, fable, a full model ID, or inherit (the default). Cheap work goes to Haiku, careful analysis to Sonnet or Opus.permissionMode accepts default, acceptEdits, plan, and others. Setting plan gives you a read-only explorer.memory accepts project, user, or local. Gives the agent a persistent directory it can write to, so a reviewer can accumulate “patterns I keep seeing in this codebase” across sessions.background set to true makes it always run concurrently instead of blocking.isolation: worktree runs the agent in a temporary git worktree, so its edits land on an isolated copy of the repo. This is what makes parallel editing agents safe from clobbering each other.One subtlety: subagents do not inherit Claude Code’s full default system prompt. They get your prompt plus a few environment details (like the working directory) and nothing else. That’s a feature. The agent’s behavior is exactly what you wrote, with no inherited bloat to fight against.
Once an agent exists, there are three ways to invoke it, escalating from a hint to a hard guarantee:
# 1. Natural language — Claude decides whether to delegate
Use the test-runner subagent to fix the failing tests
# 2. @-mention — guarantees this specific agent runs for one task
@"code-reviewer (agent)" look at the auth changes
# 3. Session-wide — the whole session adopts this agent's prompt and tools
claude --agent code-reviewerAnd Claude delegates automatically too, matching your request against each agent’s description. The better your descriptions, the better the routing.
Isolate high-volume operations. This is the highest-value use. Anything that produces a wall of output, like running the full test suite, fetching docs, or grinding through log files, is a perfect delegation target:
Use a subagent to run the test suite and report only the failing
tests with their error messagesThe verbose output lives and dies in the subagent’s context. Your main thread sees the failures and nothing else.
Run research in parallel. For independent investigations, spawn several subagents at once:
Research the authentication, database, and API modules in parallel
using separate subagentsEach explores its own area, then Claude synthesizes the findings. The catch: this works only when the research paths are genuinely independent. And remember that every subagent’s result returns to your main context. Fan out too wide and the summaries themselves start to crowd things out.
Chain agents in sequence. For multi-step workflows, pass the baton:
Use the code-reviewer subagent to find performance issues,
then use the optimizer subagent to fix themEach agent finishes, returns results, and Claude feeds the relevant pieces into the next.
Subagents live inside one session. But once you start leaning on delegation, you’ll find yourself wanting to run whole sessions in parallel. That’s where agent view comes in. Run claude agents (or press the left arrow) to open a single dashboard of every Claude Code session you have open, each row showing its status, last response, and timestamp.
Two commands feed it:
/bg pushes your current session to the background while it keeps running.claude --bg "<task>" launches a fresh background session without even opening a foreground tab.The shift is philosophical: instead of an agent pausing until you respond, work runs continuously while you monitor a queue. A good habit is to treat “needs input” alerts as your primary signal. The agents work, and you step in only when one of them is actually blocked. Name your sessions with /rename so the dashboard stays legible, and reach for claude --bg for anything that’ll take more than thirty seconds.
Delegation has overhead: setup latency, context-gathering time, and the handoff itself. It’s the wrong tool when:
For those, stay in the main conversation. And if you just want a reusable prompt or workflow that runs in your main context rather than off in an isolated one, that’s what Skills are for. Subagents are specifically for delegated work where only the result matters.
repo-explorer, test-runner, pr-reviewer. Not helper or assistant.research.md or review-notes.md, when you want to verify or reuse the work later.The mental model that sticks: you’re not configuring a tool, you’re building a small team. Each member is good at one thing, has exactly the access they need, and reports back a clean summary. Your job shifts from doing every step yourself to deciding who does what. That turns out to be a much better use of the context you’ve got.
Update: subagents report back and disappear — but what if agents could talk to each other? That’s agent teams, covered in the next post in this series.