# 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:

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

```json
["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:

```typescript
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:

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