agent_1.md

Understanding Custom Modes in Roo Code

This document explains how custom modes are implemented in Roo Code, covering both the user experience and the technical implementation details.

What Are Custom Modes?

Custom modes in Roo Code allow you to define specialized versions of the AI assistant with specific capabilities, permissions, and behaviors. Each mode serves a particular purpose and has access to different tools.

Built-in Modes

Roo Code includes several built-in modes:

• Code (default): Full-featured development mode with access to all tools
• Architect: Planning and diagramming mode (limited to editing markdown files)
• Ask: Question-answering mode without code modification capabilities
• Debug: Specialized mode for systematic problem diagnosis and resolution

Creating Custom Modes

Custom modes can be configured in two ways:

1. Global Custom Modes: Available across all workspaces
2. Project-Specific Custom Modes: Configured for a specific project

Global Custom Modes

Global modes are stored in:

~/.roo/settings/custom_modes.json

Project-Specific Custom Modes

Project modes are stored in:

.roomodes

(In the root directory of your workspace)

When modes with the same slug exist in both files, the project-specific version takes precedence. This allows projects to override global modes or define project-specific modes.

Mode Configuration Structure

Both configuration files follow this JSON structure:

{
 "customModes": [
   {
     "slug": "designer",
     "name": "Designer",
     "roleDefinition": "You are Roo, a UI/UX expert specializing in design systems and frontend development. Your expertise includes:\n- Creating and maintaining design systems\n- Implementing responsive and accessible web interfaces\n- Working with CSS, HTML, and modern frontend frameworks\n- Ensuring consistent user experiences across platforms",
     "groups": [
       "read",
       "edit",
       "browser",
       "command"
     ],
     "customInstructions": "Additional instructions for the Designer mode"
    }
  ]
}

Required Fields

• slug: A unique identifier (lowercase letters, numbers, and hyphens)
• name: Display name for the mode
• roleDefinition: Detailed description of the mode's role and capabilities
• groups: Array of allowed tool groups (determines capabilities)

The customInstructions field is optional.

Available Tool Groups

Each mode can be configured with access to specific tool groups:

• read: File reading operations (read_file, search_files, etc.)
• edit: File modification operations (write_to_file, apply_diff)
• browser: Web browsing capabilities
• command: System command execution
• mcp: Model Context Protocol tools
• modes: Tools for mode management

File Restrictions

You can restrict which files a mode can edit by configuring the edit group with a regex pattern:

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

This example restricts the mode to only edit files with the .md extension (Markdown files).

Technical Implementation

The custom modes feature is implemented through several components:

1. Mode Configuration and Schema

The mode structure is defined in shared/modes.ts and validated using Zod schemas in schemas/index.ts. The ModeConfig interface includes:

interface ModeConfig {
  slug: string;
  name: string;
  roleDefinition: string;
  customInstructions?: string;
  groups: GroupEntry[];
  source?: "global" | "project";
}

2. Custom Modes Manager

The CustomModesManager class (in core/config/CustomModesManager.ts) manages:

• Loading custom modes from both global and project-specific files
• Merging modes with proper precedence (project overrides global)
• Updating and deleting modes
• Watching for file changes to reload configurations

3. Tool Permission System

The isToolAllowedForMode function in shared/modes.ts enforces permissions:

export function isToolAllowedForMode(
  tool: string,
  modeSlug: string,
  customModes: ModeConfig[],
  toolRequirements?: Record<string, boolean>,
  toolParams?: Record<string, any>,
): boolean {
  // Implementation checking if the tool is allowed
  // for the specified mode
}

This function throws a FileRestrictionError when a file operation violates mode constraints.

4. Mode Switching

Mode switching is handled through:

• The switchModeTool allowing the AI to request a mode switch
• The handleModeSwitch method in the ClineProvider class

5. System Prompt Generation

When a mode is activated, the system generates a custom prompt combining:

• The mode's role definition
• Custom instructions
• Mode-specific rules from .roo/rules-{mode}/ or .roorules-{mode}

Mode Override Hierarchy

1. Mode-specific system prompt file overrides everything
2. Project-specific modes override global modes
3. Custom mode prompts override built-in mode definitions
4. Built-in modes provide the base configuration

Best Practices

Creating Effective Modes

1. Be Specific: Define clear, focused roles for each mode
2. Use File Restrictions: Limit editing capabilities to prevent unintended changes
3. Custom Instructions: Include detailed instructions for complex behaviors

Project-Specific Modes

• Use .roomodes for project-specific configurations
• Include it in version control to share with team members
• Override global modes to customize behavior for specific projects

Switching Between Modes

• Let the AI recommend mode switches when appropriate
• Use the appropriate mode for the task at hand:
  • Architect for planning
  • Code for implementation
  • Ask for information retrieval
  • Debug for troubleshooting

Implementation Flow

1. Mode configurations are loaded from both global and project settings
2. Configurations are merged with project settings taking precedence
3. When a mode is selected, the appropriate tools are enabled/disabled
4. File operations are checked against mode restrictions
5. The system prompt is regenerated to reflect the current mode

This architecture provides a flexible system for users to define different AI assistant personas with specific capabilities, making Roo Code adaptable to different workflows and project requirements.

agent_2.md

Understanding Custom Modes in Roo Code

Custom modes in Roo Code allow you to create specialized AI personas for different tasks. This document explains how custom modes are implemented, how to create them, and how to use them effectively.

What Are Custom Modes?

Custom modes are specialized configurations that define how Roo behaves for specific tasks. Each mode has:

• A unique identity (slug and name)
• A specific role definition that shapes Roo's expertise and behavior
• Access to specific tool groups
• Optional file restrictions for editing capabilities
• Optional custom instructions for additional guidance

How Custom Modes Are Implemented

Storage Locations

Custom modes can be configured in two places:

1. Globally: Settings stored in the extension's global storage

   • Available across all workspaces
   • Located at settings/custom-modes.json in the extension's storage

2. Per-workspace: Settings stored in a .roomodes file

   • Specific to the current workspace
   • Located in the workspace root directory
   • Takes precedence over global settings with the same slug

Mode Configuration Structure

Each mode is defined by a ModeConfig object with the following properties:

{
  "slug": "designer",           // Unique identifier (lowercase letters, numbers, hyphens)
  "name": "Designer",           // Display name for the mode
  "roleDefinition": "You are Roo, a UI/UX expert specializing in design systems...", 
  "customInstructions": "Additional instructions for the Designer mode", // Optional
  "groups": [                   // Tool groups the mode can access
    "read",                     // Read files group
    "edit",                     // Edit files group (allows editing any file)
    ["edit", {                  // Edit group with file restrictions
      "fileRegex": "\\.md$",    // Only allow editing markdown files
      "description": "Markdown files only"
    }],
    "browser",                  // Browser group
    "command",                  // Command group
    "mcp"                       // MCP group
  ],
  "source": "project"           // Where the mode is defined (global or project)
}

Available Tool Groups

Custom modes can be granted access to specific tool groups:

• read: Tools for reading files (read_file, fetch_instructions, search_files, etc.)
• edit: Tools for modifying files (apply_diff, write_to_file)
• browser: Tools for browser interactions (browser_action)
• command: Tools for executing commands (execute_command)
• mcp: Tools for Model Context Protocol integration (use_mcp_tool, access_mcp_resource)
• modes: Tools for managing modes

File Restrictions

For the "edit" tool group, you can specify file restrictions using regex patterns:

["edit", {
  "fileRegex": "(__tests__/.*|__mocks__/.*|\\.test\\.(ts|tsx|js|jsx)$)",
  "description": "Test files, mocks, and Jest configuration"
}]

This allows you to create modes that can only edit specific types of files, enhancing security and specialization.

Creating Custom Modes

Through the UI

1. Click on the Prompts button in the Roo Code sidebar
2. Navigate to the Modes tab
3. Click the "+" button to create a new mode
4. Fill in the required fields:
   • Name: Display name for the mode
   • Slug: Unique identifier (auto-generated from name)
   • Save Location: Global or project-specific
   • Role Definition: Description of the mode's expertise
   • Available Tools: Select which tool groups the mode can access
   • Custom Instructions: Optional additional guidance

By Editing Configuration Files

You can directly edit the configuration files:

1. Global modes: Edit the global custom modes file
2. Project modes: Create or edit a .roomodes file in your workspace root

Example .roomodes file:

{
  "customModes": [
    {
      "slug": "test",
      "name": "Test",
      "roleDefinition": "You are Roo, a testing expert...",
      "groups": [
        "read",
        "browser",
        "command",
        ["edit", {
          "fileRegex": "(__tests__/.*|__mocks__/.*|\\.test\\.(ts|tsx|js|jsx)$)",
          "description": "Test files, mocks, and Jest configuration"
        }]
      ],
      "customInstructions": "When writing tests:\n- Always use describe/it blocks for clear test organization\n- Include meaningful test descriptions\n- Use beforeEach/afterEach for proper test isolation\n- Implement proper error cases\n- Add JSDoc comments for complex test scenarios\n- Ensure mocks are properly typed\n- Verify both positive and negative test cases"
    }
  ]
}

By Asking Roo

You can also ask Roo to create a custom mode for you. Simply request something like:

"Create a custom mode for security auditing that can only read files and run commands."

Roo will use the fetch_instructions tool to get the mode creation instructions and guide you through the process.

How Custom Modes Are Processed

1. Loading: Modes are loaded from both global settings and the workspace .roomodes file
2. Merging: Project-specific modes take precedence over global modes with the same slug
3. Resolution: When a mode is requested, the system checks custom modes first, then falls back to built-in modes
4. Tool Access Control: Each tool request is checked against the mode's allowed tool groups
5. File Restrictions: For edit operations, file paths are checked against any regex restrictions

Custom Instructions

Custom modes can have additional instructions that modify their behavior. These can come from:

1. The mode definition itself (customInstructions field)
2. Global custom instructions
3. Project-specific instructions in .roo/rules-${mode}/ directories

These instructions are combined to create the final behavior guidance for the mode.

Use Cases for Custom Modes

Custom modes are ideal for creating specialized personas for different tasks:

• Security Auditor: Limited to reading files and running specific commands
• Documentation Writer: Can only edit markdown and documentation files
• Test Engineer: Focused on writing and editing test files
• UI Designer: Specialized in frontend code and styling files
• Database Expert: Focused on database-related files and queries

Best Practices

1. Be Specific: Define clear role definitions that explain the mode's expertise
2. Limit Access: Only grant access to the tool groups the mode actually needs
3. Use File Restrictions: For editing modes, restrict to relevant file types
4. Add Custom Instructions: Provide specific guidelines for how the mode should behave
5. Use Project-Specific Modes: For project-specific requirements, use .roomodes instead of global settings

Switching Between Modes

You can switch between modes:

1. Using the mode selector dropdown in the chat interface
2. Using keyboard shortcuts
3. Asking Roo to switch modes for you

Conclusion

Custom modes provide a powerful way to create specialized AI personas for different tasks. By defining clear roles, tool access, and file restrictions, you can create modes that are perfectly tailored to specific development tasks, enhancing both productivity and security.