# Creating Custom Modes in Roo Code: Quick Start
<div class="callout" data-callout="info">
<div class="callout-title">TLDR</div>
<div class="callout-content">
Custom modes in Roo Code let you create specialized AI agents with specific capabilities. The easiest way to create a mode is to simply ask Roo Code: "create a new mode that..." and describe what you want. For example, we created our research bot by asking "create a new mode that can gather and analyze technical documentation." Alternatively, you can manually add a JSON configuration to your Roo Code settings. Each mode needs a slug, name, role definition, and tool permissions. Switch between modes using `switch to [mode-name] mode`.
</div>
</div>
## Getting Started
<div class="topic-area">
### 1. Create a mode using natural language:
```
"Create a new mode that specializes in [your specific use case]"
```
### 2. Or manually add a configuration:
```json
{
"customModes": [{
"slug": "my-mode",
"name": "My Custom Mode",
"roleDefinition": "Describe the mode's expertise and purpose",
"groups": ["read", "edit", "browser"],
"customInstructions": "Add specific behavioral guidelines"
}]
}
```
### 3. Choose your tool groups:
<div class="quick-nav">
- `read`: Read files and analyze code
- `edit`: Modify files
- `browser`: Use web automation
- `command`: Run terminal commands
- `mcp`: Access external APIs
</div>
### 4. Add file restrictions (optional):
```json
["edit", {
"fileRegex": "\\.md
quot;,
"description": "Markdown files only"
}]
```
</div>
## Real Example: Research Bot Mode
<div class="callout" data-callout="success">
<div class="callout-title">Working Example</div>
<div class="callout-content">
We created our research bot by asking Roo Code to create a mode for technical documentation analysis. Here's the resulting configuration:
</div>
</div>
```json
{
"slug": "research-bot",
"name": "Research Bot",
"roleDefinition": "AI research assistant that can browse the web, read files, run commands, and use MCP tools to gather and synthesize information",
"groups": ["read", "edit", "browser", "command", "mcp"],
"customInstructions": "Focus on comprehensive research with citations"
}
```
## Technical Details
<div class="topic-area">
### Configuration Options
<div class="api-endpoint">
<span class="api-method">CONFIG</span> <span class="api-url">Configuration Locations</span>
- **Global**: Settings in your Roo Code configuration
- **Project-specific**: `.roomodes` file in project root
- **Tool restrictions**: Regex patterns
- **Context preservation**: Automatic between switches
</div>
### Limitations
<div class="callout" data-callout="warning">
<div class="callout-title">Known Limitations</div>
<div class="callout-content">
- No runtime permission changes
- Static file patterns only
- Token/memory constraints apply
</div>
</div>
</div>
## Best Practices
<div class="topic-area">
| # | Practice | Benefit |
|---|----------|---------|
| 1 | Define clear role boundaries | Focused AI behavior |
| 2 | Start with minimal permissions | Better security |
| 3 | Use specific file patterns | Prevent unwanted changes |
| 4 | Add detailed custom instructions | Consistent results |
</div>
## Quick Reference
<div class="topic-area">
### Switch modes:
<div class="terminal">
switch to research-bot mode
</div>
### Common tool groups:
```json
"groups": [
"read", // File reading
"edit", // File modification
"browser", // Web automation
"command", // Terminal access
"mcp" // External APIs
]
```
</div>
<div class="callout" data-callout="note">
<div class="callout-title">Meta Note</div>
<div class="callout-content">
*Created using our Research Bot mode for technical documentation and implemented using our custom modes system.*
</div>
</div>