Claude Code Agents: What They Do and When to Use One

Claude Code agents, called subagents in Anthropic’s docs, are helpers that Claude Code hands a side job to. Each one works in its own context window, with its own instructions and tools, and reports back only a summary.

Use one when a job would flood your conversation with search results, logs or file contents. Don’t use one for a quick fix you could finish in one message.

You already believe in the ideas behind agents. You just haven’t applied them to Claude Code yet.

What is a Claude Code agent?

Claude Code itself is an agent. It reads your files, decides what to do, does it, and checks the result.

A subagent is a second Claude it sends off on an errand. It gets a fresh context window, a set of instructions, and a list of tools it’s allowed to use. When it’s done, it hands back a summary, and the messy middle stays out of your main conversation.

Which agents come built in?

You get three main ones without setting anything up. Claude Code calls them on its own when a task fits.

Agent	What it does	Can it edit files?
Explore	Searches and reads your project fast	No, read-only
Plan	Gathers context in plan mode before Claude proposes a plan	No, read-only
General-purpose	Handles multi-step jobs that need both looking and doing	Yes

There are smaller helpers too, such as one that answers questions about Claude Code itself.

Why hand work to an agent at all?

Think about how you already work.

You don’t spread every receipt across the desk to write one email. You keep the desk clear and pull out what you need. Claude’s context window works the same way. Every search result and log file it reads takes up room, and a crowded context makes the rest of the session worse.

A subagent is the clear desk. It can read forty files to answer one question, and you get back the answer, not the forty files.

Don’t you already give helpers a clear brief?

When you hand off a job, you say what it is, what done looks like, and what to leave alone. Nobody hires a painter and says “do something with the house.”

That’s all a subagent file is. A name, a one-line description of when to use it, and a short brief. The description matters most, because Claude Code reads it to decide when to send work that way.

Don’t you already limit who touches what?

You give the dog walker a door key, not your bank login. Same idea here.

Each agent can have its own tool list. A reviewer that should only read gets read tools and nothing else. It can look at every file and change none of them.

Don’t you reuse a brief that works?

Once you’ve written a good checklist, you keep it. Agents work that way too.

Save an agent in your project’s .claude/agents/ folder and it works in that project. Save it in ~/.claude/agents/ in your home folder and it works in every project you open.

How do you make your own agent?

The easiest way is to ask. Tell Claude Code: “Create a project subagent called link-checker that finds broken internal links and reports them without fixing anything.” It writes the file for you.

Or write it yourself. It’s a markdown file with a short header:

---
name: link-checker
description: Finds broken internal links on the site. Use after pages change.
tools: Read, Glob, Grep
model: haiku
---

Check every internal link in the site files. List each broken one
with its file and line. Don't change any files.

Only name and description are required. Leave out tools and the agent gets the full set. The model line lets you send simple jobs to a smaller, cheaper model.

To use it, just describe the task and Claude Code may delegate on its own. Or ask by name: “Use the link-checker subagent on the new pages.” On older versions, /agents opens a setup wizard. On current ones, it points you back to these two routes.

When should you skip an agent?

Agents aren’t free. Each one sends its own requests, and those count toward the same usage limits as your main conversation. Run several at once and you’ll see it in /usage.

Keep the work in your main conversation when you need lots of back-and-forth, when the task is a small targeted change, or when you want the answer fast. Reach for an agent when the output is long and you only need the summary, or when you want to lock down which tools a job can use.

Claude Code also has an experimental feature called agent teams, which runs several full Claude Code instances together. It’s off by default. Anthropic’s cost guide says teams use roughly seven times the tokens of a normal session when teammates work in plan mode. Leave it alone until single agents feel easy.

For what this usage costs on each plan, see How Much Does Claude Code Cost? If you’re brand new, start with What Is Claude Code?

Frequently asked questions

What’s the difference between an agent and a subagent in Claude Code? Claude Code is the agent you talk to. A subagent is a helper it delegates to, with its own context window, tools and instructions. Most people say “agents” for both.

Where are Claude Code agents saved? In .claude/agents/ inside a project, for that project only, or in ~/.claude/agents/ for all your projects. Each agent is a markdown file with a short header.

Do Claude Code subagents cost extra? There’s no separate fee, but they use your allowance. Each subagent’s requests count toward the same limits as your main conversation, so give simple ones a smaller model.

Can a subagent start its own subagents? Yes. By default they can nest up to three layers below your main conversation. Remove Agent from a subagent’s tool list to stop it spawning more.

---

Want to see Claude Code build a real site, agents and all? I made a free video that walks through it start to finish. Watch the free video.