Claude Code Subagents

Q: Where do I put custom Claude Code agents?

In .claude/agents/ inside a project to share them with that repository, or in ~/.claude/agents/ to use them in every project. Each agent is one Markdown file with a name and description in its frontmatter.

Q: Can a Claude Code subagent use a different model?

Yes. Set model: in the agent's frontmatter to haiku, sonnet, opus, fable, a full model id or inherit; CLAUDE_CODE_SUBAGENT_MODEL sets one model for all subagents.

Claude Code subagents are helper agents that run in their own context window with their own instructions, tools and model; Claude Code ships built-in ones such as Explore and Plan, and you add your own as Markdown files in .claude/agents/.

2:46 A Claude Code subagent is a separate Claude instance that the main session hands a task to, running in its own context window with its own system prompt, tool list and permissions, and sending back only its result; custom ones are Markdown files with YAML frontmatter in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects) (Create custom subagents, read Nov 6, 2026). Claude Code already delegates on its own, broad searches to the built-in Explore agent for example, so most people meet subagents before they write one.

Quick facts

Built-in agents	Explore, Plan, general-purpose, plus `claude`, `statusline-setup` and `claude-code-guide`
Custom agent files	`.claude/agents/<name>.md` or `~/.claude/agents/<name>.md`
Required fields	`name`, `description`
Models	`sonnet`, `opus`, `haiku`, `fable`, a full model id, or `inherit`
Runs	In the background by default (since the week of Jun 29, 2026)
Usage	Counts toward the same usage limits as the main session

Sources for the table: Create custom subagents and What's new, Anthropic, read Nov 6, 2026.

Built-in subagents

Explore is a fast, read-only searcher for finding code; Claude can ask it to be quick, medium or very thorough. Plan does read-only research while the session is in plan mode. General-purpose has every tool and handles multi-step tasks. Smaller helpers include statusline-setup (on Sonnet) and claude-code-guide (on Haiku), which answers questions about Claude Code itself. Explore and Plan start without your CLAUDE.md files and the git status snapshot, to stay light; CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 removes them (Create custom subagents, read Nov 6, 2026).

How do you create a custom subagent?

Save a Markdown file whose frontmatter names and describes the agent and whose body is its system prompt. Anthropic's best practices page gives this reviewer, .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Because its tools are only Read, Grep and Glob, it cannot edit anything, and Claude Code enforces that rather than asking politely (Best practices for Claude Code, read Nov 6, 2026). Claude picks an agent by its description, so a description that says when to use it matters; you can also name it in a prompt ("have the reviewer compare the rate limiter against SPEC.md").

Other frontmatter fields include disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory (user, project or local), background, effort, isolation: worktree (work in a separate git checkout), omitClaudeMd and color. Agents can also come from plugins or be passed on the command line with --agents (Create custom subagents, read Nov 6, 2026).

The /agents command

On Claude Code v2.1.197 and earlier, /agents opened a wizard for creating agents. It now only prints a reminder to ask Claude or edit .claude/agents/ directly, so guides that walk through the wizard are out of date (Create custom subagents, read Nov 6, 2026). Asking Claude ("create a subagent that only runs the test suite and reports failures") writes the file for you.

When are subagents worth it?

2:24 Anthropic's best practices list four cases where they pay off: running independent pieces of work at the same time; keeping long output such as a full test run out of the main conversation; getting a reviewer that has not seen how the code was written; and giving a task fewer tools than the main session (Best practices for Claude Code, read Nov 6, 2026).

2:33 The same page is frank about the cost. Every subagent sends its own requests, which count against the same usage as your conversation, and a fresh one must first gather context your session already had, so it can be slower than doing the work in place. Handing a task to a subagent of the same model does not make the answer smarter; only the fresh perspective of a reviewer adds something. Anthropic now lists "use subagents to protect your context window" among old advice, since most current models have a 1M-token window and compact automatically. To spend less, set model: haiku for simple jobs, ask for short summaries back, and check /usage to see what each agent type costs.

Background agents, forks and chains

Subagents run in the background by default since the week of Jun 29, 2026, so the main conversation keeps moving. They can start their own subagents (background chains are capped at five levels, from the week of Jun 8, 2026), and fork mode, on by default since Aug 10 to 14, 2026, lets a side task start as a copy of the whole conversation; /fork and /subtask start these by hand (What's new, read Nov 6, 2026). Claude Code warns at startup when custom agent descriptions together pass 15,000 tokens.

Agent teams, agent view and dynamic workflows

Three related features go further. Agent teams run several full Claude Code sessions with a lead, a shared task list and direct messages between teammates; the feature is experimental, off by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), and Anthropic warns it uses "significantly more tokens" than one session (Agent teams, read Nov 6, 2026). Agent view, opened with claude agents, is one screen listing every background session and what needs your input (a research preview). Dynamic workflows are JavaScript scripts Claude writes to run dozens to hundreds of subagents at once for jobs such as a codebase-wide migration, available on all paid plans and turned on from /config on Pro (Dynamic workflows, read Nov 6, 2026).

Frequently asked questions

What are subagents in Claude Code? They are separate Claude instances that Claude Code delegates a task to, each with its own context window, instructions, tools and model, which report back a result. Claude Code includes Explore, Plan and general-purpose agents, and you can add your own.

Where do I put custom Claude Code agents? In .claude/agents/ inside a project to share them with that repository, or in ~/.claude/agents/ to use them in every project. Each agent is one Markdown file with a name and description in its frontmatter.

Can a Claude Code subagent use a different model? Yes. Set model: in the agent's frontmatter to haiku, sonnet, opus, fable, a full model id or inherit; CLAUDE_CODE_SUBAGENT_MODEL sets one model for all subagents.

Do subagents use more of my Claude usage? Yes. Every subagent's requests count against the same plan limits or API bill as the main session, and parallel agents spend tokens faster. See Claude Usage Limits.

Is /agents gone from Claude Code? The wizard is: since v2.1.198 the command only reminds you to ask Claude or edit the .claude/agents/ folder. The agents themselves work as before.