Claude Code Subagents

What Are Claude Code Subagents

Claude Code includes built-in agents and lets you define custom subagents. A custom definition can specify a description, prompt, tools, model, permission mode, skills, hooks, and optional worktree isolation. Project-level definitions live in .claude/agents/, while user-level definitions can be stored under ~/.claude/agents/.

Subagents are not miniature copies of the entire parent transcript. A normal subagent starts with a fresh context, a delegated task, relevant environment information, and applicable project memory. It reports its outcome back to the parent. This boundary is the reason subagents can preserve the main conversation's working context.

How Subagent Orchestration Works

The parent conversation decides what to delegate, prepares the task message, waits for the worker, and integrates the result. This is a hub-and-spoke model: ordinary subagents report back to the parent rather than coordinating through a shared team channel.

Use parallel delegation only when tasks are independent. Repository research by subsystem is a good fit; several workers editing the same module is not. For coordinated workers with a shared task list and direct messaging, Anthropic documents agent teams as a separate, experimental approach.

Spawning Subagents: Code Examples

Create a project agent file such as .claude/agents/test-reviewer.md:

~~~yaml --- name: test-reviewer description: Reviews changed tests for missing failure cases tools: Read, Grep, Glob model: haiku --- Inspect only the changed tests. Report untested failure paths and cite files. Do not modify the repository. ~~~

Then ask Claude to use the test-reviewer subagent. Claude can also choose it automatically when the description clearly matches the task. For one-off automation, the CLI supports --agents with JSON definitions, but committed Markdown files are easier to review and reuse.

Token & Rate Limits per Subagent

Anthropic does not publish a universal fixed token or request allowance for each subagent. Each worker has its own context, and concurrent work multiplies usage. The effective ceiling depends on the selected model, account plan or API limits, prompt size, tools, returned output, and current service rules.

Control cost by assigning the cheapest adequate model, limiting tools, keeping the delegated brief narrow, and asking for a concise return format. Do not claim that adding N subagents produces N times the throughput; provider rate limits and task dependencies may become the bottleneck.

Real-World Subagent Use Cases

• Ask separate read-only workers to map authentication, billing, and observability modules, then synthesize their findings.
• Isolate a noisy test run and return only failing cases with error messages.
• Use a security reviewer after implementation, with no write permission.
• Chain a code reviewer and an optimizer when the second step depends on the first report.
• Put an editing subagent in a worktree when its changes could overlap with another task.

Keep the parent conversation for work that needs rapid back-and-forth or shared context across planning, implementation, and testing. A subagent boundary is valuable only when the delegated work is meaningfully separable.

In Verdent

Claude Code subagents delegate work within a conversation. Verdent parallel agents are organized as product tasks and workspaces: each task has isolated conversation context, and separate workspaces use git worktrees for file isolation. Choose Claude Code subagents when a parent session should delegate and synthesize; choose Verdent workspaces when you want to run and inspect several independent coding tracks side by side.

Sources: Claude Code subagents, Parallel agent options, Verdent agents.