Subagents

About subagents

Subagents are custom agents that you can configure for specialized tasks, like code review or project bootstrapping. Each subagent has its own tools and capabilities that you can delegate specific tasks to. You can have local subagents or share them with your team by adding their configuration to your repository.

Subagents have their own context window independent from the main agent
Subagents have a custom prompt that is used to instruct the agent
Subagents run in parallel with other subagents
Subagents will show a summary of their current progress in the main thread

Auggie includes three built-in agents: general-purpose, explore, and plan. A custom agent with the same name overrides the built-in one.

Create a subagent

You can create a new subagent through the wizard by running /agents command in interactive mode. Or you can create the configuration file manually.

Create a subagent with the wizard

Run the /agents command in interactive mode
Select “Create new agent”
Select where you want the agent configuration to be stored: the project (.augment/agents/) or your user directory (~/.augment/agents/)
Choose a creation method:
- Generate with Auggie: Describe what the agent should do and give it a name. Auggie writes the configuration for you.
- Manual configuration: Enter the name, description, tools, model, thinking level, and prompt yourself.

/agents also lists running agents and available agent types.

Create a subagent manually

You can create a subagent manually by creating a configuration file. The configuration file should be a markdown file stored in either ~/.augment/agents/ (user only) or ./.augment/agents/ (shared). See the Subagent configuration reference for more details. Example subagent configuration:

---
name: code-review
description: Code review agent
model: sonnet
color: purple
---

You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory.

## Review Areas to focus on:

- **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems.
- **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive
- **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code.
- **API contract violations**
- **Database and schema errors**
- **High Value Typos**: typos that affect correctness, UX-strings, etc.

Running your subagent

Once you’ve configured the subagent, you can trigger it by sending a message that references the agent name. Augment will also automatically detect when a task is appropriate for a subagent and offer to use it.

> Use the code-review agent to review my staged changes

Subagent configuration reference

File locations

Subagents are configured in markdown files with YAML frontmatter. Subagents can be configured at the user level or the workspace level. User-level subagents are available in all workspaces, while workspace-level subagents are only available in the current workspace.

Scope	Location	Availability
User	`~/.augment/agents/`	Available in all workspaces
Workspace	`./.augment/agents/`	Available in current workspace only

Workspace agents override user agents with the same name.

Frontmatter configuration

Field	Required	Purpose
`name`	No	Name of the agent. Defaults to the filename without `.md`
`description`	No	Description of the agent, used to decide when to delegate to it
`color`	No	Label color: `red`, `blue`, `green`, `yellow`, `orange`, `purple`, `pink`, or `cyan`
`model`	No	Model to use for the agent. If not specified, the current model is used
`thinking`	No	Reasoning effort for the agent’s model
`tools`	No	Built-in tools the agent can use (allowlist). See Tool restrictions
`disabled_tools`	No	Tools the agent cannot use (denylist)
`max_turns`	No	Maximum number of turns before the agent stops
`replace_system_prompt`	No	`true` to use the prompt body as the whole system prompt instead of appending it. Default `false`
`skills`	No	Names of the skills to load for the agent. Defaults to all skills
`disable_skills`	No	`true` to load no skills
`disable_rules`	No	`true` to skip rules
`isolation`	No	`worktree` to run the agent in a separate git worktree
`run_in_background`	No	`true` to run the agent in the background by default
`enabled`	No	`false` to turn the agent off without deleting the file

Tool restrictions

You can control which tools a subagent has access to using either an allowlist or a denylist:

tools (allowlist): Only the listed built-in tools will be available: read, bash, edit, write, grep, find, ls, and web-fetch. Setting tools also removes all other tools, such as codebase-retrieval, web-search, integrations, and MCP tools.
disabled_tools (denylist): All tools except the listed ones will be available. This works for any tool, including MCP and integration tools.

Important notes:

If both are specified, a tool must be in tools and not in disabled_tools.
If neither is specified, the subagent has access to all tools the main agent has.
To keep codebase-retrieval or other non-built-in tools, use disabled_tools instead of tools.

Tool restrictions are useful for:

Security: Preventing a subagent from modifying files or running commands
Focus: Giving a subagent only the tools it needs for its specific task
Safety: Preventing subagents from performing destructive operations

Common tool names:

read - Read files
grep - Search file contents
find - Find files by glob
codebase-retrieval - Search the codebase
edit - Edit existing files
write - Create new files
bash - Run shell commands
github-api - Interact with GitHub
web-fetch - Fetch web content
web-search - Search the web

Example with YAML list format:

---
name: safe-reader
description: A safe file reader that cannot modify or execute
disabled_tools:
  - edit
  - write
  - bash
---

Example with comma-separated format:

---
name: explorer
description: A read-only explorer that can only search and view code
tools: read, grep, find, ls
---

Supported models

Subagents can use any model available in Auggie. To see a list of available models, run the following command:

auggie model list

Use a model name or part of one, such as sonnet or opus. Auggie picks the closest matching model.

Model availability may vary depending on your Augment subscription and organization settings.

Agent prompt

The agent prompt is the main body of the markdown file. The prompt is used to instruct the agent on its role and capabilities. The prompt can include any information that you want to be available to the agent, including specific tools or instructions. The prompt is rendered as markdown and supports code blocks, lists, and other formatting.

Best practices for subagents

Subagents are most effective when they have a specific and focused task. It is better to create multiple subagents for different tasks rather than trying to create a single agent for multi-step, long-running, or complex tasks.
Subagents should have a detailed prompt. The prompt should clearly define the agent’s role, capabilities, and expected behavior. Include specific instructions, task lists, examples, and expected output. Take advantage of markdown formatting to make the prompt as clear as possible.
Share your subagents with your team. Subagents are a great way to share custom workflows with your team. Store your subagents in your projects ./.augment/agents/ directory to make them available to everyone.

Example subagents

Code review agent

---
name: code-review
description: Code review agent
model: sonnet
color: purple
---

You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory.

Review Areas to focus on:

- **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems.
- **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive
- **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code.
- **API contract violations**
- **Database and schema errors**
- **High Value Typos**: typos that affect correctness, UX-strings, etc.

Review Areas to avoid:

- **Style nags**: e.g. prefer `const` over `let`, prefer template strings, etc.
- **Opinionated suggestions**: e.g. prefer `map` over `forEach`, etc.
- **Low value typos**: e.g. spelling errors in comments, etc.

Read-only code reviewer (with tool restrictions)

This example shows how to create a code review agent that can examine code but cannot make modifications:

---
name: read-only-reviewer
description: A read-only code reviewer that cannot modify files
model: sonnet
color: orange
disabled_tools: edit, write, bash
---

You are a read-only code review agent. You can examine code and provide feedback,
but you cannot make any modifications to files.

Review the code and provide feedback on:
- Code quality and best practices
- Potential bugs and issues
- Suggestions for improvement

Test generation agent

---
name: test-generation
description: Generates and runs tests for new or modified code
model: sonnet
color: green
---

You are an agentic test generation AI assistant. You are responsible for writing thorough and high quality automated tests for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal.

Your goals:

1. Analyze recent code changes or diffs to identify new or modified functions, classes, or modules.
2. Determine which parts of the changes are missing test coverage.
3. Generate clear, idiomatic unit or integration tests using the project's existing testing framework and conventions.
4. Write test files or append tests to existing files in appropriate locations.
5. Run the test suite and summarize results, including:
   - Number of tests added or updated
   - Any failures or skipped tests
   - Edge cases or scenarios still untested
6. If a test fails immediately, analyze the likely cause and propose fixes or clarifications.

Guidelines:

- Favor readability, determinism, and minimal mocking.
- Reuse existing helper utilities and fixtures if present.
- Match the naming conventions and import patterns found in the repository.
- Always include at least one negative test (an example where the function should fail).

API designer agent

---
name: api-designer
description: Use for designing REST/GraphQL APIs, OpenAPI specs, and API documentation
model: sonnet
color: blue
---

You are an API design specialist focused on creating well-structured, intuitive, and maintainable APIs. You are responsible for designing and documenting APIs for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal.

## Design Principles

- Use consistent naming conventions (plural nouns for resources)
- Implement proper HTTP methods and status codes
- Design for idempotency where appropriate
- Include pagination for list endpoints
- Provide filtering, sorting, and field selection
- Follow HATEOAS principles for discoverability
- Implement rate limiting considerations

## API Patterns

**REST Best Practices:**

- `/api/v1/resources` - Collection endpoint
- `/api/v1/resources/{id}` - Single resource
- `/api/v1/resources/{id}/relationships` - Nested resources
- Use query params for filtering: `?status=active&sort=-created_at`

**Error Responses:**

- Return consistent error format with code, message, details
- Use appropriate HTTP status codes (400, 401, 404, 422, 500)

## Documentation Style

- Generate or update OpenAPI 3.0+ spec
- Include examples for all endpoints

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

About subagents

Create a subagent

Create a subagent with the wizard

Create a subagent manually

Running your subagent

Subagent configuration reference

File locations

Frontmatter configuration

Tool restrictions

Supported models

Agent prompt

Best practices for subagents

Example subagents

Code review agent

Read-only code reviewer (with tool restrictions)

Test generation agent

API designer agent

​About subagents

​Create a subagent

​Create a subagent with the wizard

​Create a subagent manually

​Running your subagent

​Subagent configuration reference

​File locations

​Frontmatter configuration

​Tool restrictions

​Supported models

​Agent prompt

​Best practices for subagents

​Example subagents

​Code review agent

​Read-only code reviewer (with tool restrictions)

​Test generation agent

​API designer agent

About subagents

Create a subagent

Create a subagent with the wizard

Create a subagent manually

Running your subagent

Subagent configuration reference

File locations

Frontmatter configuration

Tool restrictions

Supported models

Agent prompt

Best practices for subagents

Example subagents

Code review agent

Read-only code reviewer (with tool restrictions)

Test generation agent

API designer agent