The little helper

What it is and why it matters

A subagent is a helper that Claude launches for one specific job. It has a context all its own: it opens files, searches, reads, and at the end you get back only the summary. All the material it read along the way stays there and doesn't end up in your conversation.

Why it matters: the main conversation has limited space. If Claude opens fifty files to figure out where the login lives, all that text fills the chat, and after a while Claude has a harder time keeping track. With a subagent, the helper does the searching and you get an answer that's a few lines long.

“Little” here means it does a single task, not that it's less capable: a subagent usually runs on the same model as the main conversation. In normal sessions it usually works in the background, and in the meantime you keep talking to Claude.

Claude Code already has a few ready-made ones. The one I use most is Explore: it's for searching and understanding code, and it's read-only, meaning it can't write or edit files. Then there are the ones you create yourself, which we'll get to further down.

1. Search without filling up the chat

This is the simplest case. I need to find out where something lives in the project, and I don't care about seeing every file Claude opens to find it.

Use an Explore subagent to find where the login is handled. Just tell me the files and the lines.

The second sentence matters as much as the first. “Just tell me the files and the lines” tells the helper what to bring back. If you don't say it, you get a long summary that fills up the chat anyway.

Remember that Explore doesn't see your conversation, and it also starts without the project's CLAUDE.md file so it stays fast. So put what it needs in the phrase: what you're looking for, in which part of the app, and what you want back.

2. Three jobs at once

When I have several jobs that don't depend on each other, I launch them in parallel. Each helper has its own context and its own task, and at the end Claude puts the results together.

Launch three subagents in parallel: one finds where the login is handled, one reads the logs of the last error and tells me the cause, one writes the tests for the pricing page. When they're done, give me a summary of all three.

It works because the three jobs don't overlap: finding the login isn't needed to read the logs, and neither of them touches the pricing tests. If the second job needs the result of the first, it isn't a parallel job: do it afterwards.

3. Ctrl+B and /tasks

If a job is taking a while and blocking you, say a command that's been running for minutes, press Ctrl+B: it moves to the background and you keep typing. Ctrl+B works for both commands and helpers. If you use tmux, press it twice.

To see who's working, type:

/tasks

It shows you the session's background work: the commands that are running and the subagents, including the ones that just finished. From there you can open a helper's work and read what it did, or stop it if it went the wrong way.

4. A permanent helper

If you repeat a job often, a permanent helper is worth it. It's a file in the project's .claude/agents folder: at the top there's the name, a description of when to use it and the tools it can use, and below that the instructions in plain words. You don't need to write it by hand: you ask Claude.

Create a subagent in .claude/agents that reviews the code without changing anything, and call it code-reviewer.

The result looks something like this:

---
name: code-reviewer
description: Reviews the code and flags problems. Does not change any file.
tools: Read, Grep, Glob
---

You are a code reviewer. Read the changes I point you to and look for bugs, unhandled cases and unclear parts. For each problem, tell me the file, the line and how you would fix it. Don't change anything.

The line that matters is tools: those are the tools the helper can use. A reviewer only needs the ones for reading and searching, meaning Read, Grep and Glob. Write and Edit must not be there, and neither should Bash, because files can be changed from the terminal too. If you're not sure, ask:

Open the code-reviewer subagent's file and tell me which tools it can use. If anything there lets it change files, remove it.

Then you use it like this, once you've finished a piece of work:

Have the code-reviewer subagent check the latest changes.

You can also add a model line to the file to pick the model: haiku for simple, quick jobs, sonnet or opus for heavier ones, inherit to use the same one as the conversation.

A file in .claude/agents applies to that project. If you put it in ~/.claude/agents, you'll have it in all your projects. There's also the /agents command, but the simplest way is still to ask Claude or open the file.

5. When I don't launch them

• Small jobs: changing a piece of text, a color, a line. A helper starts from scratch and first has to understand the project: it takes longer than just doing it directly.
• Jobs that touch the same files: two helpers on the same file step on each other's toes. Run them one after the other, or each in its own copy of the project, the worktrees. For a permanent helper, just add the line isolation: worktree to its file.
• When I want to follow every step: the helper brings you the result at the end. If I need to correct it at every step, I stay in the main conversation.
• When it needs everything we've said so far: a helper like Explore starts with a clean context and doesn't see our chat. It has to be briefed from scratch, so explain it well in the phrase.

One rule

Every helper uses tokens of its own, and they count against the same usage limits as the main conversation. Three helpers with one clear task each, yes. Ten launched “just because”, no.

Common mistakes

• Launching a helper for a one-line change: do it directly, it's faster.
• Writing a vague phrase like “look at the login”: say what to look for, where, and what you want back.
• Assuming the helper knows what you've discussed: it doesn't see the chat, so put the context in the phrase.
• Putting two helpers on the same files at the same time: have them work one after the other, or each in its own worktree.
• Trusting a “read-only” reviewer without checking the tools line: open the file and make sure Write, Edit and Bash aren't there.
• Launching lots of them “just because”: each one uses tokens of its own, so only launch the ones with a clear task.

Checklist

• The job is big enough to be worth a helper
• The phrase says what to look for and what to bring back
• The context it needs is written in the phrase
• The parallel jobs don't touch the same files
• I know /tasks shows me who's working
• The permanent reviewer only has tools for reading

Frequently asked questions