📖 Living glossary
Core terms in this track. Come back here whenever you need to.
What are subagents
Imagine it this way: you are a project manager. Instead of doing everything yourself, you delegate specific tasks to team members, each with their own workspace. When they finish, they hand you the result. That’s exactly what subagents do.
So far, you’ve used Claude Code as a single agent, talking directly with it. But Claude Code has a powerful capability: it can launch other agents to run tasks in parallel. These child agents are called subagents.
Each subagent receives a specific instruction, works independently (with its own context and tools), and returns the result to the parent agent when it finishes. The parent doesn't have to wait for one subagent to finish before launching another. This allows you to multiply your work capacity from Claude Code without increasing the complexity of the main context.
In one sentence: subagents are independent Claude Code instances that the main agent launches to do work in parallel.
The Task tool
A Task tool is the mechanism Claude Code uses internally to create subagents. When Claude decides it needs to delegate a task, it invokes the Task tool with a description of what the subagent should do. The subagent receives that instruction, does the work, and returns the textual result to the parent.
In practice, you don't need to call the Task tool explicitly. Just instruct Claude with something like "do these three things in parallel" or "create a subagent to analyze the tests while you refactor the code". Claude understands and orchestrates automatically. The important point is that each Task creates a new context, with its own CLAUDE.md loaded, and it doesn’t share in-memory state with the parent.
How it works under the hood
1. The parent agent decides to delegate and invokes Task(prompt="...")
2. The system creates a new Claude Code session with the provided prompt
3. The subagent executes, using its own tools (Read, Edit, Bash...)
4. When it finishes, the text result returns to the parent as the Task output
5. The parent continues its work with this information
In one sentence: the Task tool creates a subagent with its own prompt, runs it in isolation, and returns the result to the parent.
Available agent types
Not every subagent needs full permissions. Claude Code lets you launch agents with different access levels, following the principle of least privilege: grant only the permissions needed for the task. This reduces risk and prevents a subagent from changing something it shouldn't.
Read-only
Only reads files and analyzes. Doesn't edit anything. Ideal for: codebase analysis, pattern searches, audits.
Full access
Reads, edits files, and runs commands. The standard for tasks that need to modify code.
Background
Runs in the background while the parent continues. Ideal for long tasks such as builds or test suites.
In one sentence: choose the agent type based on the required permission level: read-only, full write access, or background.
Parent-child communication
Communication between parent and child follows a simple model: the parent sends a instruction (the Task prompt) and the child returns a text result. There is no shared in-memory state between them. If the child needs information about the codebase, it searches for it using its own tools.
The key point: the Task prompt needs to be complete and self-contained. The subagent doesn’t have access to the parent’s conversation history. If you want it to follow a specific standard, include it in the prompt. Think of it as writing instructions for a coworker who just joined the project.
Common mistake
Assuming the subagent "knows" what the parent discussed earlier. The subagent starts from scratch. If the information is critical, pass it explicitly in the Task prompt.
In one sentence: the parent sends instructions, the child returns text; there is no shared memory between them.
Isolation and worktrees
When two agents edit the same files at the same time, conflicts arise. The solution is the isolation via worktrees. A git worktree is an extra working directory linked to the same repository, each with its own branch. Each subagent works in its own worktree without stepping on the others’ space.
Claude Code can automatically create worktrees when launching subagents. At the end, the worktree branches are merged back into the main branch. It's like each team member has their own copy of the project to work on, and then they put everything together.
In one sentence: worktrees give each subagent its own isolated workspace, preventing file conflicts.
When to use vs. not use
Subagents aren't free. Each one consumes tokens to load the context (CLAUDE.md, tools, etc.) and has startup overhead. For simple tasks that the main agent can handle in seconds, launching a subagent is wasteful. The practical rule: use subagents when the task is independent, substantial (more than 30 seconds of work) and parallelizable.
Use subagents when
- - Tasks are independent of each other
- - Each task takes more than 30 seconds
- - You want to protect the parent context
- - Need to edit different files in parallel
- - Want to specialize agents (tests vs. docs vs. lint)
Don't use subagents when
- - The task is trivial (rename a variable)
- - Tasks depend on each other's results
- - The context is almost at its limit
- - You need real-time interaction
- - The token cost isn’t justified
In one sentence: subagents are useful for independent, substantial tasks; not for everything.
🧾 Module Summary
Next module:
4.2 — Real Parallelism: Launching Multiple Agents and Collecting Results in Practice.