Sub-agents

Claude Code can delegate tasks to autonomous sub-agents. Each sub-agent runs in its own isolated context, which protects your main thread and allows multiple tasks to run in parallel.

What is a sub-agent?

A sub-agent is a secondary Claude Code instance, invoked by the main thread to handle a specific task. It has its own context: it does not see the parent conversation history, and its actions (reading files, running commands) do not pollute the main context.

Two concrete advantages:

• Isolation: an exploratory task (reading 50 files to understand an architecture) consumes context window. Handing it off to a sub-agent protects the main thread's context for what comes next.
• Specialization: each sub-agent can have a defined role: explore, refactor, write tests, draft documentation. The main thread orchestrates, the sub-agents execute.

Launching an ad hoc sub-agent

You do not need any prior configuration to use a sub-agent. Just ask for it in your prompt:

Launch a sub-agent to explore the src/ folder and give me a summary of the architecture. Do not modify anything.

Claude Code will create a sub-agent, pass the task to it, and return the result in your thread. The sub-agent disappears once the task is done.

You can also parallelize multiple tasks in a single request:

Launch two sub-agents in parallel: the first lists all direct dependencies in package.json with their versions, the second searches for TODO files in the project.

The /agents menu

The /agents slash command lists all sub-agents available in your session, including any you have configured (see the next section).

$/agents

This menu shows you available agents, their descriptions, and the tools they have access to. Use it to verify that a custom agent was loaded correctly at startup.

Configuring a custom sub-agent

For recurring tasks (writing tests, validating SQL, reviewing documentation), you can define a persistent sub-agent. Configuration is done via a Markdown file in .claude/agents/.

Agent file structure

Create a file .claude/agents/test-writer.md with this format:

---
name: test-writer
description: Writes unit tests for TypeScript functions passed as input. Use when the user asks to test a function or module.
tools:
  - Read
  - Write
  - Bash
model: sonnet
---

You are an expert in TypeScript unit testing with Vitest.
For each function received:
1. Identify the nominal cases and edge cases.
2. Write the tests in a `*.test.ts` file adjacent to the source.
3. Run `pnpm test --run` to verify the tests pass.

The frontmatter fields:

• name: kebab-case identifier. This is what you use to invoke the agent (use test-writer for this function).
• description: describes when to use this agent. Claude reads this description to decide whether to invoke the agent automatically when relevant.
• tools: list of allowed tools. Restricting tools reduces the risk surface.
• model (optional): model to use. sonnet is the right choice for most secondary agents.

File body

Everything after the frontmatter is the agent's system prompt. This is where you define its behavior, constraints, and response style.