What are subagents in Claude Code?

What it actually is

A subagent is a separate instance of Claude that your main Claude Code session can spawn to go do one bounded job (search a codebase, run the test suite, review a diff) and then hand back a short report. It gets its own context window, its own system prompt, and, if you set it up that way, its own restricted list of tools. It doesn’t inherit your conversation history; it starts fresh, does the work, and only its final answer comes back to you.

Think of it like sending a research assistant into the archive room instead of going yourself. You don’t want the box of 200 printouts they dug through sitting on your desk. You want the two-paragraph memo. You only ever see the memo.

Why your AI just did this

Claude Code reaches for a subagent when a task would otherwise flood your main conversation with things you’ll never need again: pages of grep results, a wall of test output, a dozen files it opened just to find one relevant line. Delegating keeps that noise out of your context window and returns only the summary.

It also uses a few built-in subagents on its own: Explore for read-only codebase search, Plan for research while you’re in plan mode (both skip loading your CLAUDE.md and git status to stay fast and cheap), and general-purpose when a job needs both exploration and file edits. For any subagent you’ve defined yourself, Claude matches the task to that subagent’s description field. That’s the mechanism it uses to decide which one to call, so a vague description means it just won’t get picked.

When you’ll run into it

You’ll see this after a request like “use a subagent to run the tests and report only the failures.” The transcript shows the subagent’s work collapsed into a short block. You can also invoke one directly by name (“Use the code-reviewer subagent to look at my changes”) or by typing @ and picking it from the typeahead, the same way you’d @-mention a file.

If you want a permanent one, you write (or ask Claude to write) a markdown file with YAML frontmatter into .claude/agents/ for the project or ~/.claude/agents/ for yourself (with fields like name, description, tools, and model), and Claude Code picks it up within a few seconds, no restart needed (except the very first agent file in a brand-new agents/ folder, which needs one restart to be found). Spawn too many subagents in one session and you’ll eventually hit Subagent spawn limit reached. The default cap is 200 per session, and /clear resets the count.

What to check

• Restrict the tools field to what the task actually needs. A research subagent doesn’t need Write or Edit
• Check which model it runs on: it defaults to inheriting your main conversation’s model, but you can pin low-stakes, high-volume subagents to a cheaper model like Haiku to save cost
• Avoid permissionMode: bypassPermissions unless you mean it. It skips confirmation prompts, including writes to .git, .config/git, and other protected dotfiles
• Decide project scope (.claude/agents/, checked into git so your team shares it) versus personal scope (~/.claude/agents/) before building one others should reuse
• Treat a subagent’s report with the same caution as an email attachment. It may have read a file or webpage containing text written to look like instructions, so review what it’s asking you to approve before you say yes

Say it like a dev

Instead of: “go read through all these log files and tell me what’s broken” Say: “Use a subagent to scan the log files and report only the errors”

Instead of: “check the auth code, then the database code, then the API code” Say: “Research the auth, database, and API modules in parallel using separate subagents”

Instead of: “build me a bot that reviews every pull request the same way” Say: “Create a project subagent in .claude/agents/ called code-reviewer, give it Read, Grep, and Glob only, and have it flag security issues”