Hands-on Claude Code guide
Claude Code subagents: build a custom agent step by step
Updated November 17, 202610 min read
Claude Code subagents are helper agents that your main Claude session hands a side job to. Each one works in a fresh context (its own short-term memory), follows its own instructions, uses only the tools you allow, and sends back a short report when it finishes. Below you will build a real one from scratch, learn what each line of the file does, and get five more you can copy into your own project.
What a Claude Code subagent does while you keep chatting
Think of your main Claude Code session as a manager. When a job would fill the chat with long logs or hundreds of search results, the manager writes a short brief and gives the job to a helper. The helper does the messy work somewhere else and comes back with only the answer. That helper is a subagent.
A subagent does not see your chat history or the files Claude has already read. It gets the brief that Claude writes for it, its own instructions, and your project's CLAUDE.md (the notes file Claude reads at the start of a session). As of November 2026, a subagent that Claude starts from your main chat runs in the background by default, so you can keep typing while it works.
You already use subagents even if you never made one. Claude Code ships with several built-in Claude Code agents and picks them by itself:
- Explore: fast, read-only searching of your codebase. It can look but not edit.
- Plan: read-only research while you are in plan mode.
- general-purpose: bigger multi-step jobs that need to both look around and change things.
- Smaller helpers such as
claude(a catch-all),statusline-setupandclaude-code-guide.
Note
Searching for the Claude Code Task tool? It is the same thing under its old name. In version 2.1.63 Anthropic renamed the Task tool to Agent. Older Task(...) rules in your settings and agent files still work as aliases, so nothing breaks.
Build a test-runner subagent with me
We will make one useful helper: a test runner that runs your tests and tells you only what failed. Long test logs are the classic thing you do not want sitting in your main chat, so this is a good first agent. Follow the steps in order.
- 1
Pick one small job
Write the job in one sentence before anything else: "run the tests and report only the failures". A narrow job gets used at the right moment. A vague "helper" agent almost never does.
- 2
Choose where the file lives
For this project only, use the folder
.claude/agents/inside your project. Commit it and everyone on the project gets the agent. For every project on your computer, use~/.claude/agents/in your home folder instead. - 3
Create the file
Make a new file called
test-runner.mdin that folder and paste in the file shown below this list. The part between the two---lines is the header (called frontmatter). Everything under it is the agent's instructions. - 4
Restart once
Because this is the first file in a brand new agents folder, quit Claude Code and open it again. After that first time, Claude Code notices new and changed agent files within a few seconds, with no restart needed.
- 5
Try it
Type
Use the test-runner subagent to run the tests. You can also @-mention it:@"test-runner (agent)" check the tests, or type@agent-test-runnerby hand. - 6
Tune it
Read the report it sends back. If it is too long, tighten the instructions. If Claude never picks the agent on its own, make the
descriptionline clearer about when to use it.
---
name: test-runner
description: Runs the project's tests and reports only the failures. Use proactively after code changes and whenever the user asks to run or fix tests.
tools: Bash, Read, Grep, Glob
model: haiku
color: green
---
You run tests and report the results. You never edit files.
1. Find the test command. Look in package.json scripts, a Makefile, or CLAUDE.md.
2. Run the full test suite once.
3. If everything passes, reply with one line: the command you ran and "all passed".
4. If anything fails, list each failing test with its file name, the error
message, and the few lines of output that explain it. Skip passing tests.
5. Give the most likely cause of each failure in one sentence.
Do not try to fix anything yourself.A few choices in that file are deliberate. The tools line leaves out Edit and Write, so the agent cannot change your files with Claude's file tools. The model: haiku line runs it on Haiku, Anthropic's smaller and cheaper model. Running tests and reading output does not need a big model, and Haiku uses less of your plan. The words "use proactively" in the description are a phrase Anthropic's docs suggest when you want Claude to call the agent without being asked.
Every line of a subagent file, in plain words
Only name and description are required. Everything else is optional. Field names made of two words are joined together with a capital in the middle, like maxTurns. Here is what the main ones mean as of November 2026:
- name
- The agent's ID, such as
code-reviewer. Up to 256 characters, and it cannot contain:. Claude Code goes by this name, not by the file name. - description
- Tells Claude when to hand work to this agent. Write it as "use this when..." so Claude can match it to a task.
- tools
- The tools the agent may use, as a comma list or a YAML list. Leave it out and the agent gets every tool a subagent is allowed.
- disallowedTools
- Tools to take away. Handy when you want almost everything except, say, Write.
- model
- Which model it runs on:
sonnet,opus,haiku,fable, a full model ID, orinheritto copy your main session. - permissionMode
- How much it may do without asking:
default,acceptEdits,auto,dontAsk,bypassPermissionsorplan. - maxTurns
- A cap on how many steps it takes. When it hits the cap, its output is marked as partial.
- skills
- Skills loaded in full when the agent starts, up to 32 of them.
- mcpServers
- Outside tool connections (MCP servers) just for this agent. See the Claude Code MCP guide.
- hooks
- Scripts that run at set moments while this agent works. See Claude Code hooks.
- memory
- Gives the agent a folder that survives between chats:
user,projectorlocal. Good for an agent that should learn your codebase over time. - background
- Set to
trueto keep it running in the background even when Claude would normally wait for it. - isolation
- Set to
worktreeto give the agent its own temporary copy of the project, so its edits cannot clash with yours. - effort
- How hard it thinks:
low,medium,high,xhighormax, depending on the model. - color
- The label color you see in the terminal: red, blue, green, yellow, purple, orange, pink or cyan.
How to create and call Claude Code custom agents
Writing the file by hand is one way. The easier way is to ask. Type something like create a subagent that checks database migrations, read-only, using haiku and Claude writes the file for you. As of November 2026, the /agents command only prints a reminder to do exactly that, or to edit the agents folders yourself. Older versions (2.1.197 and earlier) opened a menu instead.
Once an agent exists, you have five ways to use it:
- Ask in plain words:
Use the code-reviewer subagent on my last commit. - @-mention it so Claude has no choice:
@"code-reviewer (agent)" look at the auth changes. - Run the whole session as that agent:
claude --agent code-reviewer. - Make it the default for a project with
"agent": "code-reviewer"in.claude/settings.json. The--agentflag wins if you use both. - Define one for a single session with the
--agentsflag and some JSON, shown below.
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'If two agents share a name, Claude Code picks one by rank. Organization settings come first, then the --agents flag, then your project's .claude/agents/, then your personal ~/.claude/agents/, and plugin agents come last.
Five custom subagents ready to copy
Each idea below is one file in .claude/agents/. Copy the shape of the test runner above and change the parts shown.
code-reviewer
tools: Read, Grep, Glob. A second opinion that cannot edit anything and never watched the code being written. Ask it to report only problems that change how the code behaves, and to skip style. For the built-in way to review, see Claude Code review.
migration-guard
tools: Read, Grep, model: sonnet. Reads new database migration files before you run them and flags anything that deletes data, locks a big table or cannot be undone.
docs-checker
tools: Read, Grep, Glob, model: haiku. Compares your README and docs with what the code really does, and lists every place they disagree.
refactorer
isolation: worktree. Makes the same mechanical change across many files in its own copy of the project, then runs the tests. Your working folder stays untouched until you merge.
codebase-notes
memory: project, tools: Read, Grep, Glob. Answers "where is X handled" questions and keeps notes in .claude/agent-memory/, so it gets quicker each time you ask.
Here is the refactorer in full, taken from Anthropic's worktree docs. Notice how short a useful agent can be:
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.Subagents vs agent teams vs separate sessions
These three get mixed up a lot. They all run more than one Claude at a time, but they are built for different jobs.
| Approach | How it works | Who coordinates | Best for |
|---|---|---|---|
| Subagents | Helpers inside one session that report a summary back | Your main Claude session | Side jobs, noisy searches, test runs, a fresh pair of eyes |
| Agent teams | Several full Claude sessions with a shared task list that message each other | A lead session, plus the teammates themselves | Research, review and features where helpers need to talk |
| Separate sessions | Independent Claude Code windows, each ideally in its own worktree | You | Unrelated features or bugs running side by side |
| Separate sessions in a VibeCodingDeck grid | Up to 12 sessions in one window, each with a status light | You, with alerts when one is waiting | Watching and steering many agents without juggling terminals |
Agent teams are experimental and switched off by default as of November 2026. You turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in the env part of settings.json. Anthropic warns they use far more tokens than one session, because every teammate is a separate Claude with its own context, and suggests starting with 3 to 5 teammates. Teammates cannot start teams of their own.
Separate sessions are the simplest option for unrelated work. Give each one its own folder with claude -w name so they cannot overwrite each other. The Claude Code worktrees guide shows how that works.
When a subagent costs more than it saves
Every subagent sends its own requests, and those count against the same usage limits as your main chat. A fresh subagent also has to gather context your main chat already had, so for a small job it can be slower than just asking in the main chat. Anthropic's best-practices page is direct about this: handing a task to a subagent does not make the answer smarter. What you get is parallel work, a cleaner main chat, or a reviewer who did not see the reasoning behind the code.
- Use
model: haikufor simple jobs like finding files or checking links. - Ask agents for short summaries, so twenty results do not flood your chat anyway.
- Run
/usageto see what share of your usage each subagent type takes. See Claude Code pricing for plan limits. - Subagents can start their own subagents, up to three layers deep. Set
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHto1to stop that, or leaveAgentout of an agent'stoolslist.
Subagents all live inside one chat window, and you only see their reports. When you would rather see every agent working, VibeCodingDeck's Swarms give one task to a lead agent plus 2 to 5 workers, each on its own copy of the project, and you choose which AI runs each role. More on that in AI agent orchestration.
Subagent questions
How do I create a subagent in Claude Code?
+
Save a Markdown file with a name and description header in .claude/agents/ (this project) or ~/.claude/agents/ (all projects). The text under the header is its instructions. Or just ask Claude to write one for you.
Can a Claude Code subagent see my main conversation?
+
No. It starts fresh with the brief Claude writes for it, its own instructions and your CLAUDE.md, but none of your chat. That is why the brief, and your agent's instructions, should include anything it needs to know.
Why is Claude not using my custom agent?
+
Usually the description is too vague. Say plainly when to use it and add "use proactively". If it is the first file in a new agents folder, restart Claude Code once. You can always force it with an @-mention.
What is the difference between subagents and agent teams?
+
Subagents report back to one main session. They only message each other if Claude gave them names when it started them. Agent teams are separate sessions that share a task list and message each other directly. Teams cost more and are still experimental.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Git first, agents second
Claude Code worktrees, starting with plain git worktree
Parallel agents
How to run multiple Claude Code agents at once: four ways, easiest last
Explainer
AI agent orchestration for coding: the words, the patterns and a worked example
Hooks cookbook
Claude Code hooks cookbook: 8 recipes to paste into settings.json
Review in two halves
Claude Code review: is it worth it, and how to use it for code review