Subagents

Specialized AI assistants with independent context for task-specific workflows

What are Subagents?

Subagents are independent Claude instances with their own context windows, tool access, and specialized instructions. They can explore code, execute plans, run in the background, and return summarized results without consuming your main session's context.

Specific Purpose

Each subagent has a defined expertise area

Own Context Window

Separate from main conversation

Configurable Tools

Specific tool access per subagent

Custom System Prompt

Tailored instructions for each agent

NEW in 2.1

New Subagent Features

⚡

Async Subagents

Run subagents asynchronously with Ctrl+B backgrounding

🔀

Context Fork

Use context: fork in skill frontmatter for isolated execution

🎯

Agent Hooks

Define PreToolUse, PostToolUse, and Stop hooks in agent frontmatter

🔄

Disable Agents

Use Task(AgentName) syntax in disallowedTools to disable specific agents

Built-in Subagents

Explore

Fast, read-only agent for searching and analyzing codebases

Model: Haiku (fast)

Tools: Read-only

Plan

Research agent used in plan mode to gather context

Model: Inherits

Tools: Read-only

general-purpose

Capable agent for complex, multi-step tasks

Model: Inherits

Tools: All tools

Agent Frontmatter Fields

Field	Description	Example
model	Override model selection	opus, sonnet, haiku, inherit
skills	Enable specific skills	["code-review", "testing"]
hooks	Define agent-specific hooks	["pre-review"]
permissionMode	Permission handling mode	inherit, default, bypassPermissions
apiKeyEnvVar	Custom API key env variable	CUSTOM_API_KEY
enableUndo	Enable undo capability	true, false
tools	Restrict available tools	["Read", "Edit", "Bash"]

agent.md frontmatter example

---
model: opus
skills:
  - code-review
hooks:
  - security-check
permissionMode: inherit
tools:
  - Read
  - Edit
  - Grep
---

Quick Start

1. Open Subagents Interface

/agents

2. Create New Agent

Choose "Create New Agent" and select project-level or user-level

3. Define the Agent

Describe the agent's purpose
Select tools to grant access
Customize the system prompt

4. Use Your Agent

> Use the code-reviewer subagent to review my changes

Example Subagents

Code Reviewer

Reviews code for quality, security, and best practices

Tools: Read, Grep, Glob, Bash

Debugger

Analyzes errors and implements fixes

Tools: Read, Edit, Bash, Grep

Test Automation

Creates and runs tests automatically

Tools: Read, Write, Bash

Best Practices

Design Focused Agents

Create subagents with single, clear responsibilities

Write Detailed Prompts

Include specific instructions and examples

Limit Tool Access

Only grant necessary tools for better security

Version Control

Check project subagents into version control

Ready to Create Your First Subagent?

Start automating specialized tasks with custom AI assistants tailored to your workflow

Get Started Usage Guide