78 78
79Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` command.79Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` command.
80 80
81This walkthrough guides you through creating a user-level subagent with the `/agent` command. The subagent reviews code and suggests improvements for the codebase.81This walkthrough guides you through creating a user-level subagent with the `/agents` command. The subagent reviews code and suggests improvements for the codebase.
82 82
83<Steps>83<Steps>
84 <Step title="Open the subagents interface">84 <Step title="Open the subagents interface">
89 ```89 ```
90 </Step>90 </Step>
91 91
92 <Step title="Create a new user-level agent">92 <Step title="Choose a location">
93 Select **Create new agent**, then choose **User-level**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.93 Select **Create new agent**, then choose **Personal**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.
94 </Step>94 </Step>
95 95
96 <Step title="Generate with Claude">96 <Step title="Generate with Claude">
102 each issue, show the current code, and provide an improved version.102 each issue, show the current code, and provide an improved version.
103 ```103 ```
104 104
105 Claude generates the system prompt and configuration. Press `e` to open it in your editor if you want to customize it.105 Claude generates the identifier, description, and system prompt for you.
106 </Step>106 </Step>
107 107
108 <Step title="Select tools">108 <Step title="Select tools">
117 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.117 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.
118 </Step>118 </Step>
119 119
120 <Step title="Configure memory">
121 Select **Enable** to give the subagent a [persistent memory directory](#enable-persistent-memory) at `~/.claude/agent-memory/`. The subagent uses this to accumulate insights across conversations, such as codebase patterns and recurring issues. Select **None** if you don't want the subagent to persist learnings.
122 </Step>
123
120 <Step title="Save and try it out">124 <Step title="Save and try it out">
121 Save the subagent. It's available immediately (no restart needed). Try it:125 Review the configuration summary. Press `s` or `Enter` to save, or press `e` to save and edit the file in your editor. The subagent is available immediately. Try it:
122 126
123 ```text theme={null}127 ```text theme={null}
124 Use the code-improver agent to suggest improvements in this project128 Use the code-improver agent to suggest improvements in this project
318| `default` | Standard permission checking with prompts |322| `default` | Standard permission checking with prompts |
319| `acceptEdits` | Auto-accept file edits |323| `acceptEdits` | Auto-accept file edits |
320| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |324| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |
321| `bypassPermissions` | Skip all permission checks |325| `bypassPermissions` | Skip permission prompts |
322| `plan` | Plan mode (read-only exploration) |326| `plan` | Plan mode (read-only exploration) |
323 327
324<Warning>328<Warning>
325 Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval.329 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, and `.idea` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permissions#permission-modes) for details.
326</Warning>330</Warning>
327 331
328If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.332If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.
534 538
535Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.539Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.
536 540
537You can also request a specific subagent explicitly:541### Invoke subagents explicitly
542
543When automatic delegation isn't enough, you can request a subagent yourself. Three patterns escalate from a one-off suggestion to a session-wide default:
544
545* **Natural language**: name the subagent in your prompt; Claude decides whether to delegate
546* **@-mention**: guarantees the subagent runs for one task
547* **Session-wide**: the whole session uses that subagent's system prompt, tool restrictions, and model via the `--agent` flag or the `agent` setting
548
549For natural language, there's no special syntax. Name the subagent and Claude typically delegates:
538 550
539```text theme={null}551```text theme={null}
540Use the test-runner subagent to fix failing tests552Use the test-runner subagent to fix failing tests
541Have the code-reviewer subagent look at my recent changes553Have the code-reviewer subagent look at my recent changes
542```554```
543 555
556**@-mention the subagent.** Type `@` and pick the subagent from the typeahead, the same way you @-mention files. This ensures that specific subagent runs rather than leaving the choice to Claude:
557
558```text theme={null}
559@"code-reviewer (agent)" look at the auth changes
560```
561
562Your full message still goes to Claude, which writes the subagent's task prompt based on what you asked. The @-mention controls which subagent Claude invokes, not what prompt it receives.
563
564Subagents provided by an enabled [plugin](/en/plugins) appear in the typeahead as `<plugin-name>:<agent-name>`. You can also type the mention manually without using the picker: `@agent-<name>` for local subagents, or `@agent-<plugin-name>:<agent-name>` for plugin subagents.
565
566**Run the whole session as a subagent.** Pass [`--agent <name>`](/en/cli-reference) to start a session where the main thread itself takes on that subagent's system prompt, tool restrictions, and model:
567
568```bash theme={null}
569claude --agent code-reviewer
570```
571
572The subagent's system prompt replaces the default Claude Code system prompt entirely, the same way [`--system-prompt`](/en/cli-reference) does. `CLAUDE.md` files and project memory still load through the normal message flow. The agent name appears as `@<name>` in the startup header so you can confirm it's active.
573
574This works with built-in and custom subagents, and the choice persists when you resume the session.
575
576For a plugin-provided subagent, pass the scoped name: `claude --agent <plugin-name>:<agent-name>`.
577
578To make it the default for every session in a project, set `agent` in `.claude/settings.json`:
579
580```json theme={null}
581{
582 "agent": "code-reviewer"
583}
584```
585
586The CLI flag overrides the setting if both are present.
587
544### Run subagents in foreground or background588### Run subagents in foreground or background
545 589
546Subagents can run in the foreground (blocking) or background (concurrent):590Subagents can run in the foreground (blocking) or background (concurrent):
