# Subagents > Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management. Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. ## Why Use Subagents Subagents help you: - **Preserve context** by keeping exploration and implementation out of your main conversation - **Enforce constraints** by limiting which tools a subagent can use - **Reuse configurations** across projects with user-level subagents - **Specialize behavior** with focused system prompts for specific domains - **Control costs** by routing tasks to faster, cheaper models like Haiku Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it. ## Built-in Subagents Claude Code includes built-in subagents that Claude automatically uses when appropriate: ### Explore A fast, read-only agent optimized for searching and analyzing codebases. - **Model**: Haiku (fast, low-latency) - **Tools**: Read-only tools (denied access to Write and Edit tools) - **Purpose**: File discovery, code search, codebase exploration Claude delegates to Explore when it needs to search or understand a codebase without making changes. When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis. ### Plan A research agent used during plan mode to gather context before presenting a plan. - **Model**: Inherits from main conversation - **Tools**: Read-only tools (denied access to Write and Edit tools) - **Purpose**: Codebase research for planning ### General-purpose A capable agent for complex, multi-step tasks that require both exploration and action. - **Model**: Inherits from main conversation - **Tools**: All tools - **Purpose**: Complex research, multi-step operations, code modifications ### Other Built-in Agents | Agent | Model | When Claude uses it | | :---------------- | :------- | :------------------------------------------------------- | | Bash | Inherits | Running terminal commands in a separate context | | statusline-setup | Sonnet | When you run `/statusline` to configure your status line | | Claude Code Guide | Haiku | When you ask questions about Claude Code features | ## Creating Custom Subagents Subagents are defined in Markdown files with YAML frontmatter. You can create them manually or use the `/agents` command. ### Using the /agents Command Run `/agents` to: - View all available subagents (built-in, user, project, and plugin) - Create new subagents with guided setup or Claude generation - Edit existing subagent configuration and tool access - Delete custom subagents - See which subagents are active when duplicates exist ### Subagent Scope Store subagents in different locations depending on scope: | Location | Scope | Priority | How to create | | :--------------------------- | :---------------------- | :---------- | :------------------------------------ | | `--agents` CLI flag | Current session | 1 (highest) | Pass JSON when launching Claude Code | | `.claude/agents/` | Current project | 2 | Interactive or manual | | `~/.claude/agents/` | All your projects | 3 | Interactive or manual | | Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) | Installed with plugins | ### Writing Subagent Files Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown: ```markdown --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices. ``` ### Supported Frontmatter Fields | Field | Required | Description | | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Unique identifier using lowercase letters and hyphens | | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | Tools the subagent can use. Inherits all tools if omitted | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | | `model` | No | Model to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` | | `permissionMode` | No | Permission mode: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` | | `skills` | No | Skills to load into the subagent's context at startup | | `hooks` | No | Lifecycle hooks scoped to this subagent | ### Model Selection The `model` field controls which AI model the subagent uses: - **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku` - **inherit**: Use the same model as the main conversation - **Omitted**: Defaults to `inherit` ### Permission Modes | Mode | Behavior | | :------------------ | :----------------------------------------------------------------- | | `default` | Standard permission checking with prompts | | `acceptEdits` | Auto-accept file edits | | `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) | | `bypassPermissions` | Skip all permission checks (use with caution) | | `plan` | Plan mode (read-only exploration) | ### Preloading Skills Use the `skills` field to inject skill content into a subagent's context at startup: ```yaml --- name: api-developer description: Implement API endpoints following team conventions skills: - api-conventions - error-handling-patterns --- Implement API endpoints. Follow the conventions and patterns from the preloaded skills. ``` ## Working with Subagents ### Foreground vs Background Execution - **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions are passed through to you. - **Background subagents** run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. Claude decides whether to run subagents in the foreground or background based on the task. You can also: - Ask Claude to "run this in the background" - Press **Ctrl+B** to background a running task ### Common Patterns #### Isolate High-Volume Operations ``` Use a subagent to run the test suite and report only the failing tests with their error messages ``` #### Run Parallel Research ``` Research the authentication, database, and API modules in parallel using separate subagents ``` #### Chain Subagents ``` Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them ``` ### Resuming Subagents Each subagent invocation creates a new instance with fresh context. To continue an existing subagent's work: ``` Use the code-reviewer subagent to review the authentication module [Agent completes] Continue that code review and now analyze the authorization logic [Claude resumes the subagent with full context from previous conversation] ``` ### Disabling Specific Subagents Add subagents to the `deny` array in your settings: ```json { "permissions": { "deny": ["Task(Explore)", "Task(my-custom-agent)"] } } ``` Or use the CLI flag: ```bash claude --disallowedTools "Task(Explore)" ``` ## Subagent Hooks ### Hooks in Subagent Frontmatter Define hooks that run only while that specific subagent is active: ```yaml --- name: code-reviewer description: Review code changes with automatic linting hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-command.sh $TOOL_INPUT" PostToolUse: - matcher: "Edit|Write" hooks: - type: command command: "./scripts/run-linter.sh" --- ``` ### Project-level Hooks for Subagent Events Configure hooks in `settings.json` for subagent lifecycle events: ```json { "hooks": { "SubagentStart": [ { "matcher": "db-agent", "hooks": [ { "type": "command", "command": "./scripts/setup-db-connection.sh" } ] } ], "SubagentStop": [ { "matcher": "db-agent", "hooks": [ { "type": "command", "command": "./scripts/cleanup-db-connection.sh" } ] } ] } } ``` ## Example Subagents ### Code Reviewer ```markdown --- name: code-reviewer description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. tools: Read, Grep, Glob, Bash model: inherit --- You are a senior code reviewer ensuring high standards of code quality and security. When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately Review checklist: - Code is clear and readable - Functions and variables are well-named - No duplicated code - Proper error handling - No exposed secrets or API keys - Input validation implemented - Good test coverage - Performance considerations addressed ``` ### Debugger ```markdown --- name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. tools: Read, Edit, Bash, Grep, Glob --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works ``` ### Data Scientist ```markdown --- name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. tools: Bash, Read, Write model: sonnet --- You are a data scientist specializing in SQL and BigQuery analysis. Key practices: - Write optimized SQL queries with proper filters - Use appropriate aggregations and joins - Include comments explaining complex logic - Format results for readability - Provide data-driven recommendations ``` ## Best Practices - **Design focused subagents**: each subagent should excel at one specific task - **Write detailed descriptions**: Claude uses the description to decide when to delegate - **Limit tool access**: grant only necessary permissions for security and focus - **Check into version control**: share project subagents with your team ## Grid Integration Opportunities