Sub-Agents

What Are Sub-Agents?

Sub-agents are specialized AI assistants designed to handle specific tasks. They have their own separate context window from the main Claude Code session and perform tasks independently.

Why Use Sub-Agents

• Task separation: Distribute complex tasks among multiple specialized agents
• Context savings: Avoid consuming the main session's context window
• Cost optimization: Use low-cost models (Haiku) for simple tasks
• Parallel processing: Run multiple sub-agents simultaneously
• Expertise: Provide domain-specific tools and instructions

5 Built-in Sub-Agents

Claude Code comes with 5 built-in sub-agents by default.

Explore (Haiku)

The main agent automatically uses this when analyzing codebase structure or locating specific files.

Plan

Activated when entering plan mode via the /plan command or Shift+Tab.

General-purpose

Used when the main agent delegates complex subtasks at its own discretion.

Bash

Claude Code Guide (Haiku)

Creating Custom Sub-Agents

Interactive Creation with the /agents Command

The easiest method is to use the /agents command.

/agents

An interactive interface appears where you can configure the name, description, tools, instructions, and more step by step.

Creating Directly with Markdown Files

Define sub-agents by creating Markdown files in the .claude/agents/ directory.

.claude/agents/
  code-reviewer.md
  test-writer.md
  doc-generator.md

Sub-Agent File Structure

Each file consists of YAML frontmatter and a Markdown body.

---
name: "Code Reviewer"
description: "A specialized reviewer that examines code quality, security, and performance"
tools:
  - Read
  - Grep
  - Glob
  - Bash(eslint)
  - Bash(npm test)
model: claude-sonnet-4-6
maxTurns: 30
---
 
# Code Review Guidelines
 
You are a code review expert. Review code based on the following criteria:
 
## Review Items
 
1. **Code quality**: Readability, naming conventions, duplicate code
2. **Security**: SQL injection, XSS, authentication bypass vulnerabilities
3. **Performance**: Unnecessary computations, N+1 queries, memory leaks
4. **Testing**: Test coverage, edge cases
5. **Type safety**: TypeScript strict mode compliance
 
## Output Format
 
Classify each issue by severity and report:
- CRITICAL: Requires immediate fix
- WARNING: Improvement recommended
- INFO: For reference

Full YAML Frontmatter Fields

Persistent Memory

Setting the memory field on a sub-agent allows it to retain information across sessions.

Memory Scopes

---
name: "Learning Assistant"
description: "An assistant that remembers the user's learning progress"
memory: user
---
 
Remembers the user's learning progress and preferences, and guides the
next lesson based on content learned in previous sessions.

Agents with memory retain conversation content and learning results from previous sessions, maintaining a continuous workflow.

Agent Scope Priority

When agents with the same name are defined in multiple locations, the following priority order applies:

1. CLI (--agents option)             ← Highest
2. Project (.claude/agents/)
3. User (~/.claude/agents/)
4. Plugins                           ← Lowest

Project agents take priority over user agents. Temporary agents passed via CLI have the highest priority.

Execution Modes

Foreground (Default)

The standard execution mode. The main session waits until the agent completes its task.

# Invoke an agent in conversation
"Review the src/ directory with the code reviewer agent"

Background

Set background: true to run the agent in the background. The main session can continue with other tasks.

---
name: "Test Runner"
background: true
tools:
  - Bash(npm test)
  - Read
---
 
Runs tests in the background and reports the results.

Parallel Execution

Multiple sub-agents can be run simultaneously. Claude Code automatically determines when to execute them in parallel.

"Review the frontend and backend directories simultaneously"

Chaining

Pass the output of one agent as input to another agent.

"First find issues with the code analysis agent, then pass the results to the refactoring agent"

Worktree Isolation

Setting isolation: worktree makes the agent work in a separate Git worktree.

---
name: "Experimental Refactoring"
description: "Safely attempt large-scale refactoring"
isolation: worktree
tools:
  - Read
  - Write
  - Edit
  - Bash
model: claude-opus-4-6
maxTurns: 50
---
 
Performs refactoring in a separate worktree.
Since it does not affect the main branch, you can experiment safely.
If the results are satisfactory, you can merge them into the main branch.

Benefits of Worktree Isolation

• Safe experimentation: No impact on the main working directory
• Independent branches: Work on a separate Git branch
• Conflict prevention: No conflicts even when multiple agents modify the same files simultaneously
• Easy rollback: If the results are unsatisfactory, simply delete the worktree

CLI Temporary Agents

You can define agents directly from the CLI using the --agents option. This is useful for one-time use without creating files.

# Define a temporary agent in JSON format
claude --agents '[{
  "name": "Quick Reviewer",
  "description": "Fast code review",
  "tools": ["Read", "Grep"],
  "model": "claude-haiku-4-5",
  "maxTurns": 10
}]' -p "Check the code quality of the src/ directory"

Temporary Agent Usage Examples

# Automated code review in CI/CD
claude --agents '[{
  "name": "ci-reviewer",
  "tools": ["Read", "Grep", "Glob", "Bash(eslint)"],
  "model": "claude-sonnet-4-6"
}]' -p "Review the code quality of changed files and write a report"
 
# Automate specific tasks in scripts
claude --agents '[{
  "name": "migrator",
  "tools": ["Read", "Write", "Edit", "Bash"],
  "model": "claude-opus-4-6",
  "maxTurns": 50
}]' -p "Convert all React class components to functional components"

Disabling Agents

To prohibit the use of a specific agent, configure permissions deny.

Disabling in settings.json

{
  "permissions": {
    "deny": [
      "agent:dangerous-agent"
    ]
  }
}

Restricting Specific Tools

You can also restrict an agent's use of specific tools.

{
  "permissions": {
    "deny": [
      "Bash(rm -rf)",
      "Write(*.env)"
    ]
  }
}

Practical Sub-Agent Examples

Test Writing Agent

---
name: "Test Writer"
description: "Automatically generates test code by analyzing source code"
tools:
  - Read
  - Write
  - Glob
  - Bash(npm test)
  - Bash(npx vitest)
model: claude-sonnet-4-6
maxTurns: 30
---
 
# Test Writing Guide
 
Analyzes source code and writes unit tests.
 
## Rules
- Use the Vitest framework
- Structure with describe/it pattern
- Include edge cases and error cases
- At least 3 test cases per function
- Use mocks minimally

Documentation Agent

---
name: "Documentation Assistant"
description: "Generates API documentation and comments by analyzing code"
tools:
  - Read
  - Write
  - Glob
  - Grep
model: claude-haiku-4-5
maxTurns: 20
memory: project
---
 
# Documentation Guidelines
 
Analyzes code to generate TSDoc/JSDoc comments and API documentation.
 
## Rules
- Add TSDoc comments to all exported functions
- Include parameter and return value descriptions
- Include usage example code
- Provide both Korean and English

Cost Estimation Guide

When using sub-agents, the most important thing is choosing the right model for the task. Using high-performance models for every task will cause costs to increase rapidly.

Cost Estimates by Task Type (Based on Direct API Usage)

Note: The costs above are rough estimates. Actual costs vary depending on codebase size, number of files, and number of conversation turns.

Cost Optimization Tips

1. Use Haiku for read-only tasks: Tasks that don't modify files, such as code exploration, searching, and structure analysis, are well-served by Haiku.

2. Mix models: Setting the main agent to Sonnet and exploration sub-agents to Haiku can significantly reduce costs.

3. Set maxTurns appropriately: This prevents agents from running indefinitely. Generally, 10 turns is suitable for exploration tasks and 20-30 turns for modification tasks.

4. Limit sub-agent tools to the minimum necessary: Allowing only required tools prevents unnecessary tool invocations.

5. Monitor costs: Use the /cost command to check the cumulative cost of the current session.

---
# Cost-optimized sub-agent configuration example
name: "Economical Code Explorer"
description: "Explore the codebase at low cost"
tools:
  - Read          # Only allow file reading
  - Grep          # Only allow text search
  - Glob          # Only allow file pattern search
model: claude-haiku-4-5   # Most affordable model
maxTurns: 10              # Limited to a maximum of 10 turns
---
 
Explores the codebase and provides summaries only. Does not modify files.

Debugging and Logging

When a sub-agent doesn't behave as expected, here's how to diagnose and resolve issues.

Checking Sub-Agent Activity

Claude Code displays the execution status of sub-agents in real time. You can monitor activity using the following methods:

# Check current session status (including running sub-agents)
# Enter /status in interactive mode
/status
 
# Check cost and token usage
/cost
 
# Check agent list and status
/agents

Common Errors and Solutions

1. "Agent not found" Error

This occurs when the sub-agent file cannot be found.

Error: Agent "code-reviewer" not found

Cause and Solution:

• Verify the file exists in the .claude/agents/ directory
• Confirm the file extension is .md (not .txt or .mdx)
• Check that the name field in the file's YAML frontmatter is correct

2. "Tool not permitted" Error

This occurs when a sub-agent attempts to use a tool that is not allowed.

Error: Tool "Bash" is not permitted for agent "read-only-agent"

Cause and Solution:

• Check that the required tools are included in the agent definition's tools field
• Verify the tool is not blocked in settings.json under permissions.deny

3. "Max turns exceeded" Error

This occurs when a sub-agent reaches its maxTurns limit.

Error: Agent reached maximum turns (10)

Cause and Solution:

• If the task is complex, increase the maxTurns value (e.g., to 20 or 30)
• Narrow the task scope and make instructions more specific so it can complete in fewer turns
• Review the instructions to ensure the agent hasn't fallen into an infinite loop

4. Sub-Agent Modifying Wrong Files

Cause and Solution:

• Remove Write and Edit from the tools field to restrict it to read-only
• Specify constraints in the instructions such as "do not modify" or "only modify files in a specific directory"
• Set permissionMode: "plan" to require approval before modifications

Debugging Checklist

When problems occur, check the following in order:

1. Verify agent file location: .claude/agents/agent-name.md
2. Check YAML frontmatter syntax: Indentation, spaces after colons, etc.
3. Verify tool names: Read, Write, Edit, Bash, Glob, Grep (case-sensitive)
4. Verify model names: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
5. Check permissions settings: Ensure the agent or tools are not blocked in settings.json
6. Check Claude Code version: Verify you're on the latest version with claude --version

By effectively utilizing sub-agents, you can automate repetitive tasks and efficiently distribute complex work.