Hugging Face's logo

Context Course documentation

Using Subagents

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Using Subagents

The approach differs between Claude Code, Codex, and Pi, but the core idea is the same: a parent agent delegates a scoped task to a child, often in parallel.

Fan-out fan-in pattern where a parent agent spawns parallel subagents

Invoking Subagents

Claude Code
Codex
Pi

Conversational Invocation

The simplest way to use subagents in Claude Code is conversational:

I need to compare 5 ML frameworks. Use subagents to research each one in parallel.
For each framework, find:
  - GitHub metrics (stars, contributors)
  - Download popularity (PyPI, npm)
  - Community sentiment (GitHub discussions)

Claude Code automatically recognizes this as work suitable for subagents and:

  1. Spawns 5 parallel subagents
  2. Each researches one framework
  3. Aggregates results into comparison report

Claude handles the subagent logic behind the scenes.

Custom Agents

For more control, define custom agents in .claude/agents/*.md with YAML frontmatter:

---
name: researcher
description: Research-focused agent for deep file exploration
tools: Read, Grep, Glob, WebFetch
model: sonnet
---
You are an expert researcher. Your job is to thoroughly explore files,
extract key information, and provide well-sourced insights.

Invoke it explicitly:

Use the researcher subagent to explore our auth system and report on security practices.

Claude Code launches the researcher subagent with the specified tools and system prompt.

Multiple custom agents:

<!-- architect.md -->
---
name: architect
description: System design specialist
tools: Read, Glob
model: sonnet
---
You design systems. You think about scalability, reliability, and maintainability.

<!-- security-reviewer.md -->
---
name: security-reviewer
description: Security-focused code reviewer
tools: Read, Grep
model: sonnet
---
You are a security expert. Review code for vulnerabilities.

Use them:

Have the architect review our system and the security-reviewer check for vulnerabilities.

CLAUDE.md Policies

Define reusable policies in .claude/CLAUDE.md for when subagents should be used:

# Project Guidelines

## Code Review Policy

All code reviews use a read-only security-reviewer subagent:

When a user proposes a change to core auth/ or security/ code, automatically:
1. Spawn a read-only security-reviewer subagent
2. Give it Read and Grep access (no Write)
3. Have it review for vulnerabilities
4. Report findings to user before commit

## Research Policy

Research tasks (10+ files) always use subagents to explore independently.
Each subagent focuses on one subsystem to avoid context overflow.

Claude Code can use these policies as guidance. They make delegation more consistent, but explicit requests are still the strongest signal when you need a specific subagent to run.

Skills in Subagents

You can invoke skills directly in subagent tasks:

Use a subagent to run the "hf-api-search" skill to find all BERT models

Or define which subagent should run which skill:

---
name: hf-researcher
description: Hugging Face specialist
skills: 
	- hf-api-search 
	- hf-dataset-fetch
model: sonnet
---
You are an expert at finding and evaluating models on Hugging Face.

Hooks and Lifecycle Events

Claude Code supports hooks via hooks.json format (see code.claude.com/docs/en/hooks). Hooks can trigger commands on events like PostToolUse, but automatic subagent spawning from hooks is not a built-in feature.

Instead, define CLAUDE.md policies to guide when Claude should use subagents:

.claude/CLAUDE.md:

# Project Guidelines

## Code Review Policy

When proposing changes to core auth/ or security/ code:
- Use a read-only security-reviewer subagent
- Have it check for SQL injection, token leakage, privilege escalation
- Report findings before committing

## Testing Policy

Large test suites (10+ files):
- Use a worker subagent to run tests in parallel
- Report coverage and failures
- Recommend fixes before commit

Claude Code reads these policies as guidance and can use subagents when appropriate. This is more flexible than rigid hooks, but it is still guidance rather than a guaranteed trigger. When you need a specific subagent, ask for it explicitly.

Background Execution (Ctrl+B)

When a subagent task is running, press Ctrl+B to send it to the background:

Researching 10 files...  [Press Ctrl+B]
✓ Sent to background. You can continue working.

Check running tasks:

/tasks

The /tasks view lists active background tasks and lets you bring a selected task back to the foreground.

Subagent Results

Subagents report back with:

  • Structured findings
  • Source files and line numbers
  • Confidence levels
  • Recommendations for parent agent

Parent agent uses these results to:

  • Combine findings
  • Make decisions
  • Generate final output
  • Handle conflicts or contradictions

Example: Research + Review Pipeline

Main task: "Design a new authentication system for our app"

Claude Code automatically:
1. [Spawns researcher subagent]
   Task: "Explore our current auth system in 15+ files"
   Tools: Read, Grep, Glob
   Result: Current architecture, pain points
   
2. [Spawns architect subagent]
   Task: "Design new auth using research from step 1"
   Tools: Read (no Write)
   Result: Proposed design
   
3. [Spawns security-reviewer subagent]
   Task: "Review proposed design for security issues"
   Tools: Read (read-only)
   Result: Vulnerability report, recommendations
   
4. [Parent combines]
   Input: Research, design, security review
   Output: Final design proposal with risks noted

Best Practices in Claude Code

Start with conversational invocation — let Claude decide when subagents help. Define custom agents for specialist roles like security-reviewer or performance-tester. Use read-only tools for review agents to prevent accidental writes. Leverage CLAUDE.md policies for consistent rules across your team, monitor background tasks with /tasks, and let the parent agent resolve conflicts when subagents disagree.

Worktree Isolation (Claude Code)

When using subagents for parallel edits, use git worktrees to prevent conflicts:

# Main workspace
git worktree add ../feature-a
git worktree add ../feature-b

# Subagent A works in feature-a/
# Subagent B works in feature-b/
# No conflicts—separate directories

Tell subagents where to work:

Subagent A: Create feature A in ../feature-a/ directory
Subagent B: Create feature B in ../feature-b/ directory
Then parent merges both features

Real-World Example: Code Review Pipeline

Task: “Review a proposed payment system for security issues and performance problems”

Claude Code
Codex
Pi 
Main Agent:
  Task: Review payment system proposal
  
  1. Spawn security-reviewer subagent (read-only)
     Tools: Read, Grep
     Task: Find vulnerabilities
  
  2. Spawn performance-reviewer subagent (read-only)
     Tools: Read, Grep
     Task: Identify bottlenecks
  
  3. [Both run in parallel]
  
  4. Main agent combines findings
     Output: Final review with risks

Conversationally:

Use subagents to do a security and performance review of the payment system.
Have security-reviewer look for SQL injection, token leakage, etc.
Have performance-reviewer look for database queries, caching opportunities.
Run both in parallel.

Key Takeaways

In Claude Code, use conversational invocation, custom agents in .claude/agents/, CLAUDE.md policies, and background execution with Ctrl+B. In Codex, request subagents in natural language with three built-in types (default, worker, explorer), define custom TOML agents, monitor with /agent, and use CSV batch jobs for parallel work. In Pi, install a subagent extension, define agents in .pi/agents/, and drive orchestration through prompt templates or explicit requests. All three approaches help when you have many files, several independent tasks, or need a fresh perspective. For parallel file edits, isolate work with git worktrees.

Next, a hands-on multi-agent workflow.

Update on GitHub

←Subagent Patterns Quiz 1: Subagent Concepts→