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-setup and claude-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. 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. 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. 3

    Create the file

    Make a new file called test-runner.md in 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. 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. 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-runner by hand.

  6. 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 description line 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, or inherit to copy your main session.
permissionMode
How much it may do without asking: default, acceptEdits, auto, dontAsk, bypassPermissions or plan.
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, project or local. Good for an agent that should learn your codebase over time.
background
Set to true to keep it running in the background even when Claude would normally wait for it.
isolation
Set to worktree to 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, xhigh or max, 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 --agent flag wins if you use both.
  • Define one for a single session with the --agents flag 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.

ApproachHow it worksWho coordinatesBest for
SubagentsHelpers inside one session that report a summary backYour main Claude sessionSide jobs, noisy searches, test runs, a fresh pair of eyes
Agent teamsSeveral full Claude sessions with a shared task list that message each otherA lead session, plus the teammates themselvesResearch, review and features where helpers need to talk
Separate sessionsIndependent Claude Code windows, each ideally in its own worktreeYouUnrelated features or bugs running side by side
Separate sessions in a VibeCodingDeck gridUp to 12 sessions in one window, each with a status lightYou, with alerts when one is waitingWatching 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: haiku for simple jobs like finding files or checking links.
  • Ask agents for short summaries, so twenty results do not flood your chat anyway.
  • Run /usage to 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_DEPTH to 1 to stop that, or leave Agent out of an agent's tools list.

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 started

Keep reading