Guide

Claude Code agents: creating and using subagents

Harrowtech.ai · last checked 13 October 2026

In Claude Code, the agents you create and call by name are subagents: helpers that Claude hands a side task to. Each one works in its own context window, with its own instructions and tool access, and sends back only a summary. Claude Code ships with some, and you can make your own as a Markdown file in .claude/agents/.

What a subagent is for

Anthropic's subagents page gives the main reason as context. A side task such as searching a codebase or reading logs can fill your conversation with output you will not look at again. A subagent does that work in its own context window and returns a summary, so your main conversation stays focused. Anthropic lists four other benefits:

• Limiting which tools a task can use.
• Reusing the same helper across projects.
• Giving a helper focused instructions for one kind of job.
• Cutting cost by sending simple tasks to a cheaper model such as Haiku.

Subagents make their own requests, and those count against the same usage limits as your main conversation.

The built-in subagents

Explore and Plan skip your CLAUDE.md files and the git status to stay quick and cheap. Every other subagent loads both. To stop Claude using a built-in, add it to the deny list in settings, for example "deny": ["Agent(Explore)"], or set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to remove Explore and Plan only.

Making your own

A subagent is a Markdown file. The header between the --- lines sets it up, and the text below becomes its system prompt. Anthropic notes that a subagent receives only that prompt plus basic details such as the working folder, not Claude Code's own system prompt, so the body needs to say everything the subagent should know.

There are two ways to create one:

• Ask Claude. Describe what you want and where to save it. Claude writes the file with a name, description, tool list, model and prompt.
• Write the file yourself in .claude/agents/ or ~/.claude/agents/.

On current versions /agents only prints a reminder to do one of these. The interactive wizard it used to open was in v2.1.197 and earlier, so older tutorials that walk through it no longer match.

Claude Code notices new and changed files within a few seconds, with no restart. The main exception Anthropic gives: if the agents folder did not exist when the session started, restart once after creating it.

Anthropic's example

This read-only reviewer is copied from Anthropic's subagents page:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

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

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

What each part does:

• description is what Claude reads when deciding whether to delegate. The words "Proactively" and "Use immediately after" push it to call the reviewer without being asked. Anthropic suggests phrases like "use proactively" for this.
• tools leaves out Edit and Write, so the reviewer cannot change files. It keeps Bash so it can run git diff.
• model: inherit runs it on whatever model the main conversation uses.
• The body tells it where to start, what to check and how to lay out its answer, which is what comes back to the main conversation.

Where the files live, and which one wins

When two subagents share a name, the one from the higher-priority location is used:

• Project folders are found by walking up from the working folder to the repository root. If two nested folders define the same name, the closer one wins.
• Subfolders such as agents/review/ are fine. The subagent is identified by its name field, not its path or filename.
• If two files in the same agents folder tree share a name, only one loads, picked by file system read order rather than a documented rule. /doctor reports such duplicates.
• Plugin subagents ignore the hooks, mcpServers and permissionMode fields for security. Copy the file into .claude/agents/ if you need them.

Every header field

Only name and description are required. Field names are case-sensitive camelCase, and Anthropic warns that a misspelt field is ignored without any error.

A file is skipped without a message if it has no name, has a name but no description, or has YAML that does not parse. Run Claude Code with --debug to see why, or check a folder before a session with claude plugin validate .claude/agents.

Limiting what a subagent can do

Tools

• tools is an allow list. Anthropic's safe-researcher example sets tools: Read, Grep, Glob, Bash, which leaves it unable to edit or write files or use MCP tools.
• disallowedTools is a deny list. Anthropic's no-writes example sets disallowedTools: Write, Edit and keeps everything else.
• With both set, the deny list is applied first. MCP tools can be named by server, as mcp__github.
• disallowedTools: Bash(git push *) removes Bash entirely, not only that command. To block one command and keep Bash, add Bash(git push *) to permissions.deny in settings instead, which applies to every subagent and the main conversation.
• Subagents running in the background get a smaller set of built-in tools than foreground ones, so the same file can end up with different tools depending on how it runs.

Permission mode

Without permissionMode, a subagent uses the main conversation's mode. If the main conversation is in bypass, accept edits or auto mode, the subagent runs in that mode whatever its file says.

Finer rules with a hook

For "allow this tool, but not like that", Anthropic's example puts a PreToolUse hook in the subagent's header that runs a script before each Bash command and blocks SQL writes by exiting with code 2. How hooks work is covered in Claude Code hooks.

Choosing the model

Claude Code decides a subagent's model in this order:

1. A model Claude passes for that particular call.
2. The model field in the file, where inherit means the main conversation's model.
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable, if set.
4. The main conversation's model.

Because the variable is only a default, setting it alone does not change subagents that name a model. To force one model onto every subagent, set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 as well. Run /tasks while a subagent is working to see which model it is on. Anthropic's example for lower-cost searching is to define your own subagent named Explore with model: haiku, which overrides the built-in one.

Using subagents

• In an interactive session, subagents Claude starts run in the background by default, so you can keep working. Their permission prompts appear in your main session with the subagent's name. Ctrl+B moves a running task to the background, and /tasks lists what is running.
• Each call starts a new subagent. To carry on from where one stopped, ask Claude to continue that work; it resumes the subagent with its history. Explore and Plan cannot be resumed, so use general-purpose or your own subagent for work you may continue.
• /subtask starts a fork: a subagent that begins with a copy of the whole conversation, so it needs no briefing. Anthropic says a fork costs less than a fresh subagent for tasks that need the same context, because it reuses the main session's prompt cache.

Patterns Anthropic suggests

• Keep noisy work out of the way: "Use a subagent to run the test suite and report only the failing tests with their error messages".
• Research in parallel: separate subagents for independent areas, then Claude combines the findings. Anthropic warns that many detailed reports coming back can still fill your context.
• Chain them: one subagent finds performance issues, the next fixes them.

Memory that lasts between sessions

The memory field gives a subagent its own folder of notes it reads and updates across conversations:

The first 200 lines or 25KB of the folder's MEMORY.md load at start. Turning auto memory off also turns this off.

Limits worth knowing

• A subagent can start subagents of its own, up to three layers below the main conversation by default. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes this, and 1 turns nesting off.
• By default no more than 20 can run at once in a session. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes that.
• Every description is loaded into context. If your own subagents' descriptions add up to more than 15,000 tokens, Claude Code warns at start-up. Keep descriptions short and put detail in the body, which only loads when the subagent runs.
• Apart from a fork, a subagent does not see your conversation, the skills or files Claude has already loaded, your output style or your auto memory. If a rule must reach it, put it in the subagent's file or in your request.

Subagent, skill, or the main session?

Skills and subagents also combine. A subagent can preload skills with its skills field, and a skill can run in a subagent with context: fork.

Anthropic's own tips for good subagents: keep each one focused on one job, write descriptions specific enough that Claude picks the right one, grant only the tools it needs, and check project subagents into version control.

What this guide does not cover

It does not cover agent teams, background sessions in agent view, dynamic workflows, plugin packaging, or the SubagentStart and SubagentStop hook events. For Anthropic's wider agent products, such as the Agent SDK, see Anthropic AI agents. For the command list, see Claude Code commands and shortcuts.

Sources

• Anthropic: Create custom subagents, including the code-reviewer, safe-researcher and no-writes examples, read 13 October 2026.
• Anthropic: Extend Claude Code, for skills compared with subagents, read 13 October 2026.
• Anthropic: Commands, for what /agents does now, read 13 October 2026.

Related: All Harrowtech.ai guides · Claude Code best practices · Claude Code skills · Claude Code hooks