Claude Code Subagents: What They Are and How to Use Them

By CodeAgentSwarm · Updated October 31, 2026

A subagent is a helper that Claude Code hands a side task to. It works in its own context window, does the noisy part (searching the codebase, reading logs, reviewing a diff) and sends back only the result, so your main conversation stays short and focused. This guide covers what Anthropic's docs say about subagents, how to write your own, and how CodeAgentSwarm shows every subagent while it works, with its model and current step, and lets agents start subagents on any model you are signed in to.

What subagents are

In Anthropic's words, from the subagents documentation, each subagent "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." When a task matches a subagent's description, Claude delegates to it and gets the result back.

  • Clean context: the subagent does not see your conversation history. It reads what it needs and returns a summary.
  • Limited tools: you can give a reviewer read-only tools and keep Edit and Write away from it.
  • Its own model: a quick search can run on a smaller model while the main session stays on a bigger one.
  • Same usage limits: a subagent sends its own requests, and they count toward the same limits as your main conversation.

The built-in subagents

  • Explore: a fast, read-only agent for searching and analyzing a codebase.
  • Plan: a read-only research agent used in plan mode to gather context before proposing a plan.
  • general-purpose: for complex, multi-step tasks that need both exploration and changes.

Claude picks them on its own. You can also ask for one directly, for example: "use the Explore subagent to find every place we read the session cookie".

How to create your own subagent

A subagent is a Markdown file with YAML frontmatter. Put it in .claude/agents/ to share it with a project, or in ~/.claude/agents/ to use it in all your projects. Only name and description are required.

markdown
---
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.
  • description tells Claude when to delegate. Keep it short and specific.
  • tools limits what the subagent can use. Leave it out and it inherits the available tools.
  • model accepts sonnet, opus, haiku, fable, a full model ID or inherit.

You do not have to write the file by hand. Ask Claude Code to create the subagent for you and review what it writes.

Subagents can run in the foreground, blocking the main conversation until they finish, or in the background while you keep working.

Subagents vs Agent Teams vs separate sessions

Subagents live inside one session and report back to it. Agent Teams coordinate several Claude Code sessions through a lead (see Claude Code Agent Teams vs CodeAgentSwarm). Separate sessions are fully independent, and you can still ask one agent to plan the work and hand it out with a coordinator.

See every subagent in CodeAgentSwarm

In a plain terminal, a subagent is a line that says work was delegated, and what it does stays out of sight. The CodeAgentSwarm Chat gives each turn a subagents block. Every row shows:

  • The agent icon and the subagent name.
  • What it is doing right now.
  • Its model and reasoning level, when the agent reports them (for Claude Code, when the call names a model such as Haiku).
  • Its status and how long it has been running.

Click a row to open that subagent's own conversation: its instructions, its replies and the tools it used. A breadcrumb takes you back to the main conversation. Next to the message box, a counter shows how many subagents are running; it lists the ones waiting for you first, then the running ones, then the finished ones, so you can open any of them later.

Subagents on any model you are signed in to

CodeAgentSwarm also gives every agent a way to start its own subagents, and they can run on any model you are signed in to in CodeAgentSwarm, not only the parent's. The rules are simple:

  • If you name an agent or a model ("ask a Codex subagent to review this"), it uses that one.
  • Otherwise the subagent uses the same agent, model and reasoning as the parent.
  • The agent only picks another provider when a second opinion or a better-suited model clearly helps, and only if that provider still has quota left.
  • It tells you why in one short line, and these subagents show when they are waiting for an answer from you.

If you ask for the work to go to another agent yourself, CodeAgentSwarm opens it as a normal, visible session instead, so you can follow it like any other. For running many sessions at once, see Claude Code agent swarm.

FAQ

What is a subagent in Claude Code?

A specialized helper with its own context window, system prompt, tools and permissions. Claude delegates a task to it and receives only the result, which keeps the main conversation focused.

Where do I put custom subagents?

In .claude/agents/ for one project or ~/.claude/agents/ for all your projects. Each subagent is a Markdown file with name and description in its frontmatter, plus optional tools and model.

Do subagents use more of my plan?

They send their own requests, and those count toward the same usage limits as your main conversation.

Can a subagent use a different model?

Yes. Set model in the frontmatter (sonnet, opus, haiku, fable, a full model ID or inherit). In CodeAgentSwarm, agents can also start subagents on another provider you are signed in to, such as Codex.

How do I see what a subagent is doing?

In the CodeAgentSwarm Chat, each subagent appears as a row with its current step, model, status and time. Click it to open its full conversation.