Claude Code subagents: when they help and when they cost you

The built-in ones you already use

Before you write a custom subagent, know what is already delegating. Claude Code ships built-in subagents it uses automatically, and most of the context saving people attribute to their own configuration is coming from these.

Explore used to run on Haiku unconditionally. As of Claude Code v2.1.198 it inherits the main conversation’s model instead, capped at Opus on the Claude API, so a session on a higher tier does not run exploration on a more expensive model than you chose. If you want exploration cheap again, define your own.

---
name: Explore
description: Searches and explains a codebase without changing it.
tools: Read, Grep, Glob
model: haiku
---

You answer questions about a codebase by reading it. Never edit a file.
Return a short summary with exact file paths and line references, not
a transcript of what you looked at.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Defining one

---
name: test-writer
description: Writes unit tests for existing code. Use when asked to add test coverage for a file that already works.
tools: Read, Write, Bash
model: haiku
maxTurns: 20
---

You write unit tests for code that already exists and works.

Rules:
- Match the existing test style in the repository. Read a neighbouring
  test file first; do not invent a new convention.
- Test behaviour through the public interface, never private internals.
- Cover the error paths, not only the happy path.
- Never modify the implementation. If it looks wrong, say so and stop.
- Run the tests you wrote before reporting done.

Scope, precedence, and where files live

• Both directories are scanned recursively, so agents/review/ and agents/research/ are fine. Identity comes only from the name field, never the path.
• Project subagents are discovered by walking up from the working directory, so every .claude/agents/ between there and the repo root is scanned. When two nested directories define the same name, the one closest to the working directory wins.
• Two files in the same directory sharing a name is undefined: Claude Code loads one by filesystem read order. /doctor reports the clash.
• Files are watched, so an edit takes effect within a few seconds with no restart. The exception: if ~/.claude/agents/ did not exist when the session started, you have to restart.

What isolation actually costs

The pitch for subagents is that they keep your main context clean. That is true and it is only half the picture.

A subagent receives its own system prompt plus basic environment details such as the working directory. It does not receive the full Claude Code system prompt, and it does not receive the main conversation’s auto memory. The one exception is a fork, which inherits the parent conversation and system prompt.

Where they earn their keep

The review subagent is still the best one

A reviewer with read-only tools, a fresh context, and an instruction to be sceptical is the highest-value subagent most repositories can have. It catches things the agent that wrote the code cannot, because it has none of the investment in the approach.

---
name: reviewer
description: Reviews a diff for bugs before it is committed. Use after changes are complete.
tools: Read, Grep, Glob, Bash
model: opus
effort: high
---

You review diffs for defects. You did not write this code and you have
no attachment to the approach.

Report only:
- Bugs that will actually occur, with the input that triggers them.
- Security issues with a concrete exploit path.
- Broken error handling.

Do not report style, naming, or preferences. If you find nothing real,
say so plainly. A short honest review is worth more than a long one.

Worktree isolation, for anything you would not run on your checkout

Setting isolation: worktree gives the subagent a temporary git worktree, branched by default from your default branch rather than the parent session’s HEAD. Its Bash commands run inside that worktree, and Claude Code blocks commands that try to redirect git back at your main checkout. The worktree is cleaned up automatically if the subagent made no changes.

---
name: migrator
description: Applies a mechanical codemod across many files. Use for framework or API migrations.
tools: Read, Edit, Write, Grep, Glob, Bash
model: haiku
isolation: worktree
permissionMode: acceptEdits
maxTurns: 60
---

Apply the requested migration across every matching file.

Do not change behaviour. If a file needs a judgement call, skip it and
list it at the end rather than guessing. Run the build before reporting
done and report the file count you changed.

The cost model

A subagent runs a full agent loop with its own context, so it is not free. Whether it saves money depends almost entirely on the model field.

• Inherited model, small task: more expensive. You paid to re-establish context and gained nothing.
• Cheaper model, mechanical task: substantially cheaper. This is the real win, and it requires the model field.
• Expensive model, review of a finished diff: worth it. Catching one real bug pays for a lot of reviews.
• Search that would have filled your main context: cheaper, because context cost compounds across every later turn.

Questions people ask

Keep reading