Claude Code subagents: the honest use case

TL;DR: A Claude Code subagent is the same Claude with a fresh context window, a tighter job description, and no memory of your main conversation – not a fancier model, and that constraint is the feature. I used subagents for months without ever setting one up: I asked for them in plain words, and that’s still how most of it works. Reach for one when a task generates reading you don’t want to wade through, repeats often enough to deserve a fixed prompt, or should run in parallel with other work. Hooks are the smaller sibling – I run exactly one.

What is a Claude Code subagent?

A Claude Code subagent is a separate Claude that your session hands a task to. The built-in ones need zero setup – that’s how I used them for months. When you want a specialist, you define your own as a small markdown file with a name, a description of when it should be invoked, and instructions for what to do; those files live in .claude/agents/. The handoff happens three ways: your main Claude decides on its own that the task matches a subagent’s description, you ask it to use one, or you’ve made it standing practice for certain kinds of work. The subagent runs in a fresh context window – its own clean working memory, separate from your conversation – does the job, and returns only the result.

Your main session never sees the mess. That’s the point.

Can a subagent see your main conversation?

No – a subagent cannot see your main conversation, and that’s important. No memory of what you asked earlier, what you decided ten turns ago, which file you were arguing about. It gets its instructions, gets the task, hands back the answer.

That constraint is the feature. It’s why a subagent’s output is often sharper than the same task run in your main session: the main session was too full of context to think clearly about a narrow question. (If your problem is the opposite – the main session itself is rotting and you’re deciding whether to compact or hand off – that’s a different move, and it has its own decision tree.)

How I started using subagents (before they had names)

Until recently, I didn’t have a single officially-set-up subagent, and no hooks either. My system worked anyway.

But I’ve been using subagents since very early in my wiki’s life – by asking. The first time, I had a whole pile of papers to ingest, and I told Claude: here’s all this stuff – why don’t you deploy a bunch of subagents to bring it in, in batches? Otherwise I’m going to wait forever for you to do it one by one. It said: yeah, sure, I can do that. It tried it, and it worked – so it deployed a few of them and brought in all the papers at once. From my side you don’t see much: the AI prompts some agents to do something, and the results come back.

From there the pattern grew. Working on a piece, I’d say: wait a minute – could you stop and get a subagent’s opinion? Could you ask someone with expertise in this aspect of the piece? That became a habit: can you spawn some subagents to do this task, run that check, get an opinion. No setup, no files – a plain-language request, every time.

The officially named ones came only recently, when I moved part of my wiki into a separate vault, and that’s when it occurred to me to name the recurring ones and make them consistent. Today there’s a research agent, a reviewer whose instructions are to push back instead of agreeing with our text, a fact-checking reviewer (whose verdicts I take with a grain of salt – checking the checker is still my job), and sometimes an SEO reviewer. Whatever the work needs.

When should you use a subagent?

Use a subagent in four cases, from my actual practice:

1. The task uses a different tool than the conversation. Web search, PDF extraction, a database query. Load the tool into the subagent and the tool’s overhead never touches your main context.
2. The task generates a lot of reading you don’t need to see. A research pass across twenty pages, a scan across a whole folder. The subagent does the reading; I get the synthesis.
3. The task repeats and deserves a fixed prompt. Audits, research reports, drafting under constraints. The subagent file is the fixed prompt – written once, invoked forever.
4. You want several running at once. Two or three research angles in parallel, each with its own scope, none contaminating the others.

What does a real subagent look like? The one I use most

The one I lean on most is the research agent. And here’s the part people picture wrong: I don’t hand the subagent anything. I hand my main chat the question, and it deploys the subagents that go do the searching and the reading – my main agent does the prompting for me. What comes back to my session is the findings, not the twenty pages that got waded through. My conversation stays clean, and I stay in charge of what the findings mean.

The reviewers work the same way but in the other direction: they read what we made. The point of the not-going-to-agree reviewer is exactly that instruction – I don’t need a second yes, I need the objection I didn’t think of. And the fact-checker earns its grain of salt: it catches real things, and it can’t tell a plausible receipt from a true one. Only I can.

Can you run Claude Code subagents in parallel?

Yes – my paper-ingest batches were exactly that, several subagents running at once. The rule that keeps it safe is boring: parallel is for genuinely independent tasks. If two tasks would touch the same target, run them one at a time. (The day parallel sessions – a related but bigger move – made my whole wiki look broken is part of How I built an AI that actually knows my work.)

What are Claude Code hooks?

A hook is a shell command Claude Code runs automatically when a specific event fires – before a file gets edited, after a session ends, when a session starts. Where a subagent is a fresh Claude you delegate to, a hook is a tripwire with a script attached.

For most of my wiki’s life I had no hooks, and the system worked anyway – Claude reading the wiki at the start of every session worked, all on its own. But sometimes it felt like one of the files hadn’t been read, and that’s why I finally installed the one hook I run: it guarantees the read happens at session start, every time, no trusting required. I didn’t write it from scratch; I described what I wanted, and Claude wired it.

If you don’t have a suspicion like that to close, skip hooks for now. Subagents return more per hour of setup.

How do you create your first subagent?

Pick one task you already do repeatedly with Claude – a research pass, a document audit, a summarization – and write a subagent for it this week. Under 300 words: name it (.claude/agents/researcher.md works), describe when it should run, write the instructions, save. Next session, ask for the task in plain words, and watch the delegation happen on its own. That first automatic handoff is where subagents click.

The mental model behind all of this – instructions as plain files your AI reads – is the same one as the memory folder. And remember where I started: no files at all, nothing but asking. You can begin there today.