How to Use Subagents in Claude Code

A subagent is a separate Claude with its own context window and its own instructions. The point is isolation: a search that reads forty files fills the subagent’s window, and only the summary comes back to yours. It also lets you send cheap work to a cheaper model.

1. Delegate the wide work

Use subagents to find every place we call the old fetchUser API.

What it does: hands the sprawling search to a separate context, so your main conversation gets the answer without the forty files it took to find it.

2. Write your own

Create .claude/agents/<name>.md for the project, or ~/.claude/agents/ for every project. Note: as of v2.1.198, /agents no longer opens an interactive wizard — write the file, or ask Claude to write it for you.

---
name: test-writer
description: Writes focused unit tests for a given file
tools: Read, Write, Bash
model: sonnet
---

You write minimal, behavior-focused unit tests. Match the project's existing test style.
Run the tests and confirm they pass before finishing.

What it does: defines a subagent. name and description are required — the description is what Claude reads when deciding to delegate, so write it as a trigger, not a title. tools narrows the inherited set; model takes sonnet, opus, haiku, fable, or a full ID.

Claude Code watches these directories and picks up changes within seconds, so no restart in most cases.

3. Invoke it

@"test-writer (agent)" write tests for src/lib/parse.ts

What it does: guarantees that subagent runs, rather than hoping Claude picks it. Naming it in plain prose (“use the test-writer subagent”) also works. To run a whole session as one: claude --agent test-writer.

Verify it worked

Run /context after a delegated search. If your main window barely grew, the isolation worked; if it ballooned, the work happened inline and you got none of the benefit — which is the whole reason to use a subagent rather than just asking.

Use them for broad searches, parallel independent tasks and focused reviews. Avoid them for tightly coupled steps that need shared state: a subagent starts blank, so everything it needs has to be in the task you hand it. Because each one runs its own context, they are also a real cost lever in both directions — see managing context for the rest of that picture.

Source: Claude Code subagents.