A Claude Code subagent is a secondary AI assistant that runs in its own context window, with its own system prompt, its own tool list, and its own permissions. Some side tasks (digging through the codebase, reviewing a diff, looking something up) can flood your main conversation with output you will never read again. Claude hands that work to a subagent instead: the subagent does it separately and sends back only the summary. So Claude Code subagents do two jobs at once. They keep your context clean, and they let you hand a subtask to a specialized worker you can constrain (limited tools, a cheaper model). Here's what a subagent is, how to create one, when to choose a subagent over a skill or a hook, and three concrete use cases for solo builders.
What is a Claude Code subagent?
A subagent is a worker Claude calls in for a specific job and dismisses once the job is done. What sets it apart from Claude itself comes down to one word: isolation. Every Claude Code subagent has its own context window. Everything it reads, searches, and tests stays on its side. Your main conversation receives only its conclusion.
This solves a very practical problem. When you ask Claude "where is authentication handled in this project?", it opens ten files, reads three thousand lines, and all of that stays in your context, even after you've moved on. An Explore subagent runs the same search in its own bubble and hands you three lines: the file, the function, the entry point.
Claude Code ships with built-in subagents:
- Explore: a fast, read-only agent for searching and understanding a codebase. It has no access to Write or Edit.
- Plan: a research agent used in plan mode to gather context before proposing a plan. Also read-only.
- general-purpose: a full agent with every tool, for tasks that mix exploration and changes.
Beyond these three, you can write your own. A custom subagent lets you control four things Claude won't tune on its own: which model it uses, which tools it may call, which permissions it gets, and how it behaves (through its system prompt). Want a code reviewer that can't modify anything and runs on a cheap model? Describe it in a file and it exists.
It's also a cost lever. Routing a mechanical task to a faster, cheaper model like Haiku, instead of running it on the model driving your session, takes a single line of config. When you're counting every euro of API spend, that line matters.
Subagent vs skill vs hook: which to use when
Claude Code has three extension mechanisms that people often mix up, and they do very different things. Table first, explanation after.
| Mechanism | Definition | Context | When to use it |
|---|---|---|---|
| Subagent | A delegated AI worker with its own context window | Isolated from yours | A heavy subtask (research, review) where you only want the result |
| Skill | Instructions or a procedure that Claude loads | In your main context | Teaching Claude how to do something recurring |
| Hook | A script triggered automatically on an event | Outside the AI, deterministic | Guaranteeing an action (formatting, blocking) every single time |
You decide along two axes: context isolation and degree of control.
A skill lives in your context. It loads instructions that Claude applies during your conversation. It's an on-demand capability, but it reasons alongside you, in the same bubble. If the task generates a lot of noise (logs, files), the skill dumps it all on your side.
A subagent lives next door. It can follow the same procedure, but it runs it in its own window and returns only the summary. The simple rule: if you just want Claude to know how to do something, use a skill. If you want it to go do the thing elsewhere and come back with the answer, use a subagent. The two also combine: a subagent can preload a skill as reference material.
A hook isn't AI at all. It's a script Claude Code runs automatically at a specific moment (before a tool runs, after an edit). It simply executes, with no decision-making involved. A subagent is a smart but fallible collaborator, while a hook is a mechanical guarantee: it fires every time, with zero judgment. Want a formatter to run after every edit, without exception? Use a hook.
Structuring and creating a subagent
A subagent is just a Markdown file with YAML frontmatter. The frontmatter configures the agent, and the body becomes its system prompt. You can create one in two ways: ask Claude to write it for you (the fastest option), or write the file by hand.
Here's what a code reviewer looks like, saved to ~/.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and give specific, actionable feedback on quality, security, and best practices.
Only two fields are required: name and description. The description is what tells Claude when to delegate, exactly as with a skill. Location sets the scope: .claude/agents/ for a project-level subagent (commit it so your team benefits), ~/.claude/agents/ for a personal subagent available across all your projects. One gotcha worth knowing: if the agents/ folder didn't exist when the session started, restart Claude Code so it picks it up. Otherwise detection is instant: edit an existing agent file, and the next delegation uses the updated version within seconds, with no restart.
An important point about how this works. A subagent receives only its system prompt (the body of the file) plus a few environment details such as the working directory. It inherits neither your conversation history nor Claude Code's full system prompt. That's exactly what makes it lightweight and predictable: it starts clean, with only the instructions you give it. The flip side is that the body of the file has to stand on its own. A vague system prompt produces a vague agent.
The model field deserves a mention too. By default a subagent inherits your session's model, but you can pin it: model: sonnet for a careful reviewer, model: haiku for a grunt-work agent you don't want to pay premium rates for. That single line is your main cost control.
Automatic vs manual invocation
A subagent can be triggered in two ways. Automatic: Claude reads its description and delegates on its own when the task matches ("review my changes" wakes up the code-reviewer). Manual: you call it explicitly, by mentioning it with @ or writing "use the code-reviewer agent on this project". The rule that matters: a good description, written with the words you'd actually use, is what makes a subagent fire at the right moment. Write a vague description and Claude will ignore it.
Scoping tools (principle of least privilege)
By default, a subagent inherits every tool from the main conversation. That's rarely what you want. You have two settings to rein it in:
toolsworks as an allowlist: you list only what it's allowed to use. Our code-reviewer only hasRead, Grep, Glob, so it can't modify anything. A review can never turn into an unwanted rewrite.disallowedToolsworks as a denylist: you start from everything and strip out the dangerous parts.
This habit of giving each agent exactly what it needs is plain operational common sense. An agent that can't write can't break your code by accident. A research agent you deny shell access will never run a bad command.
Also note that some tools are never available to a subagent, even if listed in tools: the ones that depend on your session's interface, such as the ability to ask you a question live. A subagent works autonomously. It can't pause midway to ask your opinion, so it carries its task through to the end and returns its result. Keep that constraint in mind when you write its system prompt: give it enough to make decisions on its own, and leave it no reason to hesitate.
3 concrete founder use cases
Here are three practical uses for a founder coding solo, where a subagent saves real time.
Parallel code review
You're the only developer, with nobody to review your pull requests. A read-only code-reviewer subagent on a decent model handles that job: it reads your diff and flags missing error handling, hardcoded values, and tests that need updating. It works in its own corner, your main context stays clean, and you get an actual review instead of merging blind.
Researching your codebase in parallel
You're building a feature and need to understand how another module works, without cluttering your current session. An Explore subagent digs, reads, and maps things out in its own bubble, then hands you the essentials: the relevant files, the logic, the entry point. You keep your train of thought while the research happens on the side. Good to know: when Claude calls Explore, it picks a depth level based on the need, from a targeted lookup to a very thorough analysis. You don't have to set it by hand, but you can ask for it explicitly when you want an exhaustive exploration before a big architecture decision.
Grunt work on a cheap model
The third use is the most underrated. Generating repetitive tests, renaming across files, producing docs: hand all of that to a subagent running model: haiku. You save your powerful model for architecture, and you stop paying top rates for chores. On a startup API budget, it shows up on the monthly bill.
Moving on to Agent Teams
Subagents have one limit: they work within a single session, and Claude delegates one subtask at a time before taking back control. That's enough most of the time. But when you take on a project that needs sustained parallelism, with several workers moving forward on different pieces at once or agents that need to talk to each other, you've outgrown subagents.
That's where Agent Teams take over: a separate Claude Code feature where each worker has its own independent context window and agents can message one another. The good news is that your subagent definitions carry over. When you set up a team, you can reference an existing subagent type, and the teammate picks up its tools and model. The effort you put into structuring your subagents is never wasted, since they become the building blocks of your teams.
The logical progression for a founder: start with one or two subagents (a reviewer, a researcher), build the delegation habit, and move up to Agent Teams only when a single session can no longer carry the project.
Further reading
FAQ
What is a subagent in Claude Code?
A subagent is a specialized AI assistant that runs in its own context window, with a custom system prompt, specific tools, and independent permissions. Claude delegates a subtask to it (research, review, debugging), the subagent runs it separately and returns only the summary. This keeps your main conversation clean and lets you tightly control what the agent can do.
What's the difference between a subagent and a skill?
A skill loads instructions into your main context: it teaches Claude how to do something. A subagent runs the task in an isolated context and returns only the result. Simple rule: if you want Claude to know how to do something, use a skill; if you want it to go do it elsewhere and come back with the answer, use a subagent. The two combine, since a subagent can preload a skill.
How do I create a Claude Code subagent?
The fastest way is to ask Claude to write it for you, describing what you want and where to save it. Otherwise, create a Markdown file with YAML frontmatter by hand in ~/.claude/agents/ (personal, all projects) or .claude/agents/ (a single project). Only name and description are required; add tools, model, and a system prompt in the body.
How do I limit a subagent's tools?
Use the tools field as an allowlist to permit only certain tools (for example Read, Grep, Glob for a read-only agent), or disallowedTools as a denylist to remove dangerous tools. Without these fields, the subagent inherits every tool in the session. The principle of least privilege keeps an agent from breaking your code by accident.
Subagents or Agent Teams: which should I choose?
Subagents are enough to delegate one subtask at a time within a single session. Move to Agent Teams when you need several workers running in parallel, on independent contexts, communicating with each other. Your subagent definitions can be reused as building blocks for a team.
