Claude Code Subagents: Keep the Noise Out of Your Main Session

Ask Claude to find every place a config value is read across a big repo and your context window fills with grep output, file listings and dead ends. 20 minutes later the thing you were actually doing has been compacted into a summary. A subagent is the fix: a separate Claude with its own context window that does the noisy work and sends back only the answer.

This post covers what a subagent is and is not, the built-in ones you already have, writing your own as a Markdown file, limiting what it can touch, and the 3 ways to invoke one. The file format and fields are from the current docs, linked at the end. If you are new to Claude Code, Install Claude Code on Windows, Native and in WSL is the starting point.

What a Subagent Is

A subagent is a Markdown file with a system prompt and some frontmatter. When Claude delegates to it, Claude Code starts a fresh conversation with that prompt, the task, and a limited set of tools. The subagent does not see your conversation history. It works, and its final message is all that comes back into your session. That isolation is the point: the search results, logs and file contents it read stay in its context, not yours.

It is not a cheaper Claude by default. A subagent runs on the main conversation’s model unless its file says otherwise, and it costs tokens like any session. The saving is in your context window, and in your attention.

The Built-In Ones

You have been using subagents without writing any. When Claude says it is exploring the codebase, that is usually one of these:

Explore: read-only search and analysis. Fast, one-shot, cannot edit. This is the one that keeps the grep output out of your session.
Plan: research during plan mode, with Write and Edit denied. Plan mode leans on it.
general-purpose: multi-step tasks that need both exploration and action.
claude-code-guide: answers questions about Claude Code itself, on Haiku.
statusline-setup: what /statusline runs, on Sonnet.

To block one, a deny rule names it: "deny": ["Agent(Explore)"] in permissions. Subagents can spawn their own, 3 levels deep by default, and up to 20 run at once; both are environment variables if you need to change them.

Write Your Own

A subagent is a file in .claude\agents\ for one project or ~\.claude\agents\ for every project. Only name and description are required; the body is the system prompt. The docs’ code reviewer, as a project file:

---
name: code-reviewer
description: Reviews code for quality and best practices. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer.

When invoked:
1. Run git diff to see recent changes
2. Focus on the modified files
3. Begin the review immediately

Report by priority: critical issues, warnings, suggestions. Include specific fixes.

The description matters more than it looks. Claude reads every subagent’s description to decide when to delegate, so write what the agent is for and when to use it, in one or two lines. A vague description means it never gets picked, or gets picked for the wrong thing.

Claude Code watches both folders, so a new or edited file is picked up within seconds with no restart. The exception is the first file in a folder that did not exist when the session started; restart for that one. You can also just ask Claude to write the file for you, and /agents prints a reminder of exactly that.

The Fields That Limit It

The frontmatter is where you decide what the subagent can touch. The ones worth knowing, all optional:

tools: an allowlist. Read, Grep, Glob makes it read-only. Omit it and the agent inherits every tool, MCP tools included.
disallowedTools: the opposite. disallowedTools: Write, Edit keeps everything else and removes the 2 that change files.
model: sonnet, opus, haiku, a full model ID, or inherit. A search or summarise agent on Sonnet is the usual way to spend less.
permissionMode: default, acceptEdits, plan, dontAsk and the rest, as in the permissions post.
maxTurns: a turn limit so a stuck agent stops.
isolation: worktree: run it in a temporary git worktree so its edits never touch your checkout.
memory: user, project or local gives the agent its own auto memory between runs.
hooks: hooks scoped to this agent, for example a PreToolUse hook that refuses anything but a SELECT.

Multi-word field names are camelCase, and a field Claude Code does not recognise is ignored silently, so a typo in disallowedTools gives the agent every tool with no warning. Check a new agent does what you think by giving it a task it should refuse.

Invoke One

3 ways, from a hint to a guarantee:

Use the code-reviewer subagent to look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

The first is plain language and Claude decides whether to delegate. The second is an @-mention, picked from the same typeahead as files, and it guarantees that agent runs for the task; Claude still writes the task prompt from what you asked. The third runs the whole session as that agent, with its tool limits and model, and the name shows as @code-reviewer in the startup header. To make that the default for a project, set "agent": "code-reviewer" in .claude\settings.json.

Foreground, Background, and Talking Back

A foreground subagent blocks the conversation until it finishes. A background one runs while you carry on, and its permission prompts surface in your main session. A finished subagent keeps its history, so Claude can send it a follow-up by name instead of starting over; Explore and Plan are the exceptions, they are one-shot. Ctrl+X Ctrl+K, pressed twice, stops every background subagent in the session.

There is also a fork: /subtask draft unit tests for the parser changes so far starts a subagent that inherits your whole conversation instead of starting fresh, which is the right tool when any other agent would need too much explaining. It runs in a panel below the prompt and its result arrives as a message.

Other Considerations

A subagent’s edits are not in your checkpoints. Rewinding your session restores only the files you had already edited in the main conversation; a subagent’s other changes stay. Git is the undo for those. Rewind Claude Code Edits With Checkpoints has the detail.

CLAUDE.md still loads for custom subagents by default; Explore and Plan skip it, and omitClaudeMd: true skips it for yours. Your auto memory is not loaded into them.

Subagent transcripts live under the parent session in a subagents folder and go in the same 30 day sweep. The transcripts post covers the retention setting.

Skills can run in a subagent too. context: fork in a skill’s frontmatter does it, with agent: naming which one. Custom Slash Commands in Claude Code With Skills covers skills.

Frequently Asked Questions

When should I use a subagent instead of just asking?

When the work produces a lot of output you do not need to read: searches across a repo, reading logs, reviewing a diff. The summary comes back; the noise does not.

Do subagents see my conversation?

No. They start with their own system prompt, the task Claude writes for them, and the working directory. A fork started with /subtask is the exception and inherits everything.

Can a subagent use a cheaper model?

Yes, set model: sonnet or model: haiku in its frontmatter. Without the field it uses the main session’s model, or whatever CLAUDE_CODE_SUBAGENT_MODEL says.

How do I stop Claude delegating to a particular agent?

Add Agent(<name>) to permissions.deny. Agent(fork) stops forks specifically.

Where do project and user agents clash?

A project file in .claude\agents\ wins over a user file of the same name in ~\.claude\agents\, and a --agents JSON flag beats both for the session.

If SQL Server is part of your day job, my current work lives over at sqldba.blog: production DBA scripts, an error library and the SSMS guide.