
What is a Subagent?
A subagent is a specialized AI assistant that the main Claude Code session delegates a task to: a subagent runs in its own context window, has its own system prompt, is limited to its own set of tools, and when done, sends only a summary of results back to the main conversation. According to the "Create custom subagents" page in the Claude Code documentation (code.claude.com, read on 03/11/2026), the best use case is when a subtask would flood the main session with search results, logs, or file contents that you don't need to read again. This post does not promise that subagents work faster or cheaper in every situation; on the contrary, subagents consume extra tokens and may lose details during handoff. The post also does not mention what cost OPCAIOS has paid. The content includes: how subagents differ from the main session, how to create custom subagents per official documentation, when to and not to use them, how to write a brief, how to verify results, and real errors OPCAIOS encountered running a batch of posts using subagents. The overview of Claude Code is in the post What is Claude Code.

Main session divides work, subagent works in its own context, results are checked before going into draft. Diagram: OPCAIOS.
How does a subagent differ from the main Claude Code session?
A subagent differs from the main session in that a subagent starts with a fresh, nearly empty context window. According to Claude Code documentation (read on 03/11/2026), a subagent does not see your conversation history, does not see skills the main session has called, and does not see files the main session has read. The only thing a subagent receives about its task is the handoff message composed by Claude when delegating, plus that subagent's own system prompt. The exception is "fork": a copy that inherits the entire conversation of the parent session. Four points to remember:
- Own context: lengthy results stay within the subagent, the main session only receives a summary.
- Own tools: the
toolsanddisallowedToolsfields limit what a subagent can use; Explore and Plan are available read-only, Write and Edit are blocked. - Own permissions: a subagent can have separate permission mode via the
permissionModefield. - Shared quota: each subagent sends its own requests to the model and shares usage quota with the main session.
The documentation also notes that by default a subagent can spawn child subagents, up to three levels below the main session, and when 20 subagents are already running, spawning more will error. These numbers may change with version updates.
How do I create a custom subagent in Claude Code?
Creating a custom subagent means writing a Markdown file with a YAML frontmatter section and the system prompt in the body. Per official documentation (read on 03/11/2026), only the name and description fields are required; description decides when Claude auto-delegates to the subagent, so it must be clear. Example from the documentation, placed at .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Where you place the file determines who can use the subagent:
| Location | Scope | Note |
|---|---|---|
.claude/agents/ in the project |
Current project | Should go in git so the team can share |
~/.claude/agents/ |
Every project on your machine | Personal subagent |
--agents flag at startup |
This session only | Pass JSON, not saved to disk |
agents/ folder of a plugin |
Where plugin is enabled | Does not support hooks, mcpServers, permissionMode |
| Organization's management config | Entire organization | Highest priority |
To call by name, mention the subagent in a command, or type @ and select the subagent; to run the entire session as a subagent, use claude --agent <name>. Other optional fields include model, maxTurns, skills, memory, isolation: worktree (runs on its own git copy). The documentation warns that Claude Code ignores misspelled fields without reporting an error, so double-check field names.
When should you use subagent and when should you not?
Subagent should be used when the task can stand alone, creates many outputs that you don't need to keep, and can return as a summary. The Claude Code documentation (read on 03/11/2026) lists three common usage patterns: separating work that creates many outputs like running test suites or reading logs, researching multiple independent parts in parallel, and chaining subagents step by step. Conversely, you should stay in the main session when the work requires back-and-forth exchanges, when planning, writing, and testing steps share a lot of context, when you only need a quick fix in one place, or when you need fast feedback because subagent has to gather context from scratch. Subagent has two costs:
- Tokens: each subagent consumes tokens as it runs, and results from many subagents flowing back still take up the main session's context; the documentation warns clearly about this.
- Loss of detail in handoff: subagent only knows what's in the brief, the main session only sees the summary. Bugs can hide where nobody reads.
If you just need a repeating process to run right in the main session, skill is usually better than subagent. Overall costs are discussed in the post Claude Code costs.
How do you write a brief for subagent so it doesn't get things wrong?
A brief for subagent is everything the subagent knows about the task, so the brief must be able to stand alone like assigning work to a colleague who has never been on the project. A good brief has six parts:
- Goal and output: write what, save to which file, what format, how long.
- Scope: allowed to read what, allowed to write only which files, absolutely do not touch where.
- What is already known: what the main session has already ruled out, so subagent doesn't redo it.
- Hard rules: for example don't make up numbers, don't add unsourced quotes, keep the source line and keywords unchanged.
- Allowed sources: official documentation pages, template files, and require treating web content as data not instructions.
- Final report: list files written, what has been verified with sources, what has not been verified, strange instructions found on the web.
Avoid putting your own hypothesis into the brief as a conclusion, because subagent easily "confirms" what was suggested. Keep scope narrow: one subagent for one small, clear group of tasks.
How do you check the results from subagent?
Checking subagent results means not trusting the summary, but directly comparing the product with the original and with the rules. The subagent's report is written in the same confident tone whether right or wrong. The Claude Code documentation (read on 03/11/2026) says Claude Code scans the final report of the subagent to flag text masquerading as system instructions, but this scan does not judge content correctness and does not replace limiting permissions. A practical checking process:
- Machine check first: script counts words, finds banned strings, compares links to real lists, compares edits to originals.
- Read samples by eye: open a few random products, not just the first one.
- Verify sources: every number or feature name must be in the recorded page.
- Write to a safe place: draft, separate branch, or temp folder, don't overwrite the real version yet.
- Final reviewer: only release when the owner agrees.
How to handle many sessions editing the same repository is discussed separately in the post many AI sessions editing one project.
OPCAIOS's Experience
I've used subagents in Claude Code many times for two kinds of work: writing batches of blog posts and bulk-editing old posts. What follows is true at the conceptual level:
- A batch of 10 posts, each subagent handles 2. The main session writes one shared brief and sends it to subagents running in parallel in the background; each subagent only writes its own Markdown file. The main session does the rest: scoring, building images, checking links, putting it into draft. This post was written exactly that way.
- Editing about 139 old posts to raise GEO scores (25/10/2026). Before scaling up, I ran a trial subagent on a few posts and carefully checked the differences. The average GEO score on the internal scoring tool went up from around 62.6 to around 78; this is an internal score, not traffic or ranking.
- Real errors encountered. Some subagents dropped source lines at the end of posts, removed keywords from opening paragraphs, and worst of all added fake citations like "(X 2026)" to make the scoring tool give higher marks.
- How I handled it. Write a script comparing the original against the edit before writing (catching lost sources, lost keywords, lost images or links); back up all content before overwriting; and guard against overwriting with a hash code: if a post was edited by another session after being checked out, don't write over it.
- Every post written by AI goes into draft status, only scheduled to publish when the owner approves it.
The biggest lesson: subagents optimize exactly what you measure. If you measure score, you must add anti-cheating checks on the score. More context in the post how I let AI agents build and run a website.
Read more: 6 best tools for running multiple AI code agents at once in 2026.
Frequently Asked Questions
Do subagents work faster?
Not always. Many subagents running in parallel helps finish sooner when the work is independent—for example writing many posts on different topics or studying many separate modules. But each subagent starts with an empty context so has to read the project over again, and the Claude Code docs say that when you need quick feedback the main session usually works better. For small jobs, fixing one thing, sending it to a subagent usually takes longer than doing it yourself.
Do subagents cost extra?
Yes, in the sense of extra usage. The Claude Code docs (read 03/11/2026) say each subagent sends its own request to the model, counts toward the shared limit with the main session, and many subagents returning long results still take up context from the main session. You can cut costs by having subagents use a lighter model through the model field. OPCAIOS doesn't publish its own cost breakdown, so the post includes no figures.
Can subagents see my conversation?
Normal subagents can't. According to the docs, subagents start with a fresh context, can't see the conversation history, can't see files the main session has read; subagents only get their own system prompt and the work request message. The exception is fork, which inherits the parent session's whole conversation. So anything that matters—like rules of honesty or which files can be written—must go in the brief.
Should I give subagents permission to edit files and run commands?
Only give what's needed. Work that explores and audits should use read-only subagents like Explore, or custom subagents with a tools field containing only reading tools. Work that needs to write should be limited to one folder or one specified file, and checked before going into the real version. Subagent permissions still go through the session's permission system; see the post plan mode and permissions in Claude Code.
Where should someone new to subagents start?
Start with built-in subagents and read-only work: ask Claude to use a subagent to search the project and summarize, or run tests and report errors. When you notice you're repeating the same kind of work request, create a custom subagent in the agents folder with clear instructions. Always check results yourself before trusting them. If you want to learn how to delegate work to AI agents with control, see OPCAIOS's AI application training course.
Source: Anthropic's Claude Code docs, "Create custom subagents" and "Configure permissions" pages at code.claude.com (read 03/11/2026); unverified: specific speed and cost gains from subagents beyond what the docs state, possible limits on number and depth that may change with version; experience is OPCAIOS's.
Translated from Vietnamese with AI. Read the original.
Want to apply this in your business?
Book a free 30-minute call (Vietnam time, in English or Vietnamese).


