AI Systems & ArchitectureMarch 21, 20253 min readshipped

Roo Code Custom Modes: Build a Specialized AI Agent in Minutes

Run this

claude "Following the AIXplore Roo Code custom-modes entry, draft a custom mode for a specialized agent: produce the JSON config (slug, name, roleDefinition, tool permissions) and explain when to switch into it."

claude code

Creating Custom Modes in Roo Code: Quick Start

TLDR

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`.

Getting Started

1. Create a mode using natural language:

"Create a new mode that specializes in [your specific use case]"

2. Or manually add a configuration:

{
  "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:

read: Read files and analyze code
edit: Modify files
browser: Use web automation
command: Run terminal commands
mcp: Access external APIs

4. Add file restrictions (optional):

["edit", { 
  "fileRegex": "\\.md$",
  "description": "Markdown files only" 
}]

Real Example: Research Bot Mode

Working Example

We created our research bot by asking Roo Code to create a mode for technical documentation analysis. Here's the resulting configuration:

{
  "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

Configuration Options

CONFIG Configuration Locations

Global: Settings in your Roo Code configuration
Project-specific: .roomodes file in project root
Tool restrictions: Regex patterns
Context preservation: Automatic between switches

Limitations

Known Limitations

No runtime permission changes
Static file patterns only
Token/memory constraints apply

Best Practices

#	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

Quick Reference

Switch modes:

switch to research-bot mode

Common tool groups:

"groups": [
  "read",      // File reading
  "edit",      // File modification
  "browser",   // Web automation
  "command",   // Terminal access
  "mcp"        // External APIs
]

Meta Note

*Created using our Research Bot mode for technical documentation and implemented using our custom modes system.*

About the Author: Justin Johnson builds AI systems and writes about practical AI development.

justinhjohnson.com | Twitter | LinkedIn | Run Data Run | Subscribe