What are Claude Code Subagents and how do they work?

Imagine this. You’re working on three features at once, juggling code reviews, writing docs, and trying to remember what that bug report meant from last Thursday. You call in an AI assistant and it dumps everything into one giant chat. Helpful? Sort of. Frustrating? Absolutely.

Anthropic just rewrote the playbook. With Claude Code Subagents, developers no longer rely on one generic assistant. Instead, they get a team of AI specialists, each designed for a specific task like debugging, documentation, or system architecture. It feels less like using a tool and more like collaborating with a real team that understands what needs to get done.

It is a shift that makes AI feel less artificial and more like a natural part of the development process. This could be the most practical step yet toward how software will be built in the future.

What are claude code subagents?

Subagents are like a team of AI coworkers, each focused on one specific job. Instead of asking one assistant to do everything, you get a lineup of experts built for precision:

1. A code commenter that explains logic in plain English
2. A code formatter that keeps your style consistent
3. A code reuse finder that spots duplication across files
4. A JavaScript minifier that squeezes your code for production

Download 400 claude code subagents use cases here.

Each subagent comes with its own context, memory, and tools. That means they do not interrupt or confuse each other, and they stay focused on their one responsibility.

The hidden advantage is that subagents fix one of AI’s biggest flaws which is losing context. When a single prompt tries to do everything, it often gets overwhelmed or forgets what it was working on. Subagents keep each task separate and focused. That means better attention, faster results, and more reliable output. It mirrors how actual engineering teams work and points to a smarter way of building software with AI.

Now let’s talk about the key benefits of using subagents.

Benefits

1. Context preservation

Subagents keep their own memory and focus on a specific task without getting distracted or overwritten. Even if you’re working on multiple things, each subagent stays locked into its job. For example, one subagent can handle outdated dependency checks while another manages ESLint fixes and neither loses track.

2. Specialized expertise

Each subagent is designed to do one thing really well. Instead of trying to be a generalist, it becomes a domain expert. If you create a subagent for writing regular expressions, it will consistently perform better than a broad agent juggling multiple tasks.

3. Reusability

Subagents are easy to reuse. Once created, they can work across projects or be shared with others without rewriting anything. For example, a subagent that generates commit messages can be plugged into any repo and still produce clean, consistent commits every time.

4. Flexible permissions

You decide what each subagent can access. Some can read files but not write, others can run commands but stay sandboxed. This keeps things secure and under control. For instance, your test subagent might run tests in staging but have no access to production.

5. Modular scaling

Subagents work like building blocks. You can add new ones or remove old ones without breaking the system. Say you need a new subagent that formats GraphQL queries, just plug it in, and it runs alongside your existing agents without interfering.

---

Quick start

To create your first Claude Code Subagent, follow these steps:

1. Install Claude Code

You’ll need the Claude Code CLI to create and manage subagents (NodeJS 18+ required).

Install it globally using npm:

npm install -g @anthropic-ai/claude-code

2. Install the VS Code extension (Optional)

For a smoother editing experience, install the Claude Code extension in Visual Studio Code.

This extension provides:

• Auto-completion for claude specific commands and arguments
• Smooth editing experience inside your editor
• Configurable settings to enable IDE integrations like automatic diff viewing

Search for Claude Code for VSCode in the VS Code extensions tab and install it.

3. Open the Claude Code CLI

Once installed, open your terminal and run:

claude

This launches the interactive CLI.

4. Open the subagents interface

Inside the CLI, run the following command:

/agents

This opens the subagents dashboard where you can create, edit, or manage agents.

5. Create a new subagent

Select Create new agent and choose whether to create a project level or user/personal level subagent.

6. Customize your subagent

You can now describe what your subagent should do:

• Use Claude to generate a base version
• Write clear instructions for when and why the subagent should be used
• Choose what tools it can access (leave blank to inherit all tools)
• Press e to open and directly edit the system prompt in your editor

7. Save and use

Once saved, Claude will automatically decide when to use this subagent.

You can also manually activate it like this:

Use the code-reviewer subagent to check my recent changes

---

Managing and configuring subagents

Subagents are defined using Markdown files with YAML frontmatter. These files determine how each subagent behaves and when it should be invoked.

1. File location

You can store subagents in two locations:

• Project level subagents go inside .claude/agents/ and are only available within the current project.
• User/Personal level subagents go in ~/.claude/agents/ and are available across all your projects.

If both locations contain subagents with the same name, the project-level version takes priority.

2. File format

Each subagent file starts with YAML metadata that includes its name, description, and optional tool list. Below that, you can define the system prompt to instruct the subagent on how to behave.

Each subagent is defined in a Markdown file with this structure:

---
name: code-duplication-detector
description: Use this agent when you need to identify code duplication and opportunities for refactoring across your codebase. Examples: <example>Context: User has been working on multiple components and wants to check for duplicated logic before finalizing their work. user: 'I've been adding several new UI components and I'm worried there might be some duplicated code. Can you check for any patterns that could be refactored?' assistant: 'I'll use the code-duplication-detector agent to analyze your codebase for duplicated patterns and refactoring opportunities.' <commentary>The user is concerned about code duplication after adding multiple components, so use the code-duplication-detector agent to identify duplicated code patterns.</commentary></example> <example>Context: User is preparing for a code review and wants to clean up duplicated logic. user: 'Before I submit this PR, I want to make sure I haven't introduced any code duplication' assistant: 'Let me use the code-duplication-detector agent to scan for any duplicated code patterns in your recent changes.' <commentary>User wants to check for duplication before code review, so use the code-duplication-detector agent to identify potential issues.</commentary></example>
tools: Bash, Glob, Grep, LS, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch
model: sonnet
color: orange
---

You are a Code Duplication Detection Expert, specializing in identifying redundant code patterns and providing actionable refactoring recommendations. Your expertise lies in recognizing both exact duplicates and semantic similarities that indicate opportunities for consolidation.

When analyzing code for duplication, you will:

1. **Scan Systematically**: Examine the codebase methodically, focusing on:
   - Similar function implementations across files
   - Repeated code blocks with minor variations
   - Duplicated utility functions and helper methods
   - Similar component structures and patterns
   - Repeated configuration or constant definitions
   - Similar error handling patterns
   - Duplicated validation logic

2. **Categorize Findings**: Classify duplications by:
   - **Exact Duplicates**: Identical code that can be immediately extracted
   - **Near Duplicates**: Similar code with minor variations that could be parameterized
   - **Semantic Duplicates**: Different implementations achieving the same goal
   - **Structural Patterns**: Similar architectural patterns that could be abstracted

3. **Provide Detailed Analysis**: For each duplication found, include:
   - File locations and line numbers of all instances
   - Percentage of similarity between code blocks
   - Brief description of what the duplicated code does
   - Impact assessment (lines of code that could be reduced)

4. **Recommend Refactoring Strategies**: Suggest specific approaches such as:
   - Extract common functions to utility modules
   - Create reusable components or classes
   - Use configuration objects for repeated patterns
   - Implement higher-order functions or decorators
   - Create shared constants or enums
   - Establish common base classes or interfaces

5. **Prioritize by Impact**: Rank findings by:
   - Amount of code that could be eliminated
   - Frequency of duplication
   - Maintenance burden reduction potential
   - Risk level of refactoring (low/medium/high)

6. **Consider Context**: Take into account:
   - Project architecture and existing patterns
   - Framework-specific conventions (especially Astro patterns)
   - Whether duplication might be intentional for isolation
   - Performance implications of consolidation

7. **Provide Implementation Guidance**: Include:
   - Suggested file locations for extracted code
   - Example refactored code snippets
   - Step-by-step refactoring approach
   - Potential breaking changes to consider

Your analysis should be thorough yet practical, focusing on duplications that provide meaningful benefits when eliminated. Always consider the trade-offs between DRY principles and code clarity, and flag cases where duplication might be preferable for maintainability or performance reasons.

Format your findings in a clear, actionable report that developers can immediately act upon, with duplications sorted by priority and impact.

Each configuration requires a name (a unique identifier in lowercase with hyphens) and a description (a natural language summary of the subagent’s purpose and when to use it).

Optionally, you can also specify tools as a comma-separated list to restrict access; otherwise, it defaults to full access.

3. Manage subagents

The /agents command provides a comprehensive interface for subagent management:

/agents

Here you can:

• You can view all available subagents, whether they are built-in, personal, or project-specific.

• You can create new subagents using a guided setup that helps you define their purpose, behavior, and tools.

• Select an existing subagent and click on Edit agent to update its name, description, instructions, or capabilities.

  You’ll then see options such as:

  • Open in editor
  • Edit tools
  • Edit model
  • Edit color

• You can delete subagents that are no longer needed.

• If multiple subagents share the same name, you will be prompted to either rename one or select the intended agent, helping you resolve naming conflicts easily.

• You can also manage tool access by choosing which tools each subagent is allowed to use from the full list available.

4. Available tools

Subagents can access Claude Code’s internal tools by either omitting the tools field thereby inheriting all tools from the main thread (including MCP tools) or by specifying a comma-separated list of tools for more granular access control.

The /agents command provides an interactive interface to help you view and select from all available tools, including those from connected MCP servers.

5. Automatic delegation

Claude Code can automatically delegate tasks to subagents based on your request. It looks at the task description, the description field in each subagent’s configuration, and the tools available in the current context.

To increase the chances of a subagent being triggered automatically, include strong signals in its description field such as must be used or use proactively. This helps Claude determine which subagents are best suited for the job without manual instruction.

6. Explicit invocation

If you want to directly assign a task to a specific subagent, you can do so by naming it in your command.

For example:

Use the code-reviewer subagent to check my recent changes
Use the test-runner subagent to fix failing tests
Ask the debugger subagent to find this error

This ensures the right subagent is called without relying on Claude’s judgment, which can be useful when you want full control or are working with a complex prompt.

---

Final thoughts

Claude’s subagent system adds a simple but powerful way to break down work. Instead of handling everything in one place, you can define small, focused agents to take care of specific tasks. These agents don’t just follow instructions, Claude uses their descriptions and scopes to decide when and how to use them. This means better decisions, cleaner outputs, and fewer repeated prompts.

Once you get the hang of it, you’ll start to see how much faster and clearer things become. Claude handles more behind the scenes so you can focus on your project.