Skip to content

Commit 04739b4

Browse files
author
Richard
committed
Refine documentation for creating and configuring custom modes
1 parent 153a818 commit 04739b4

File tree

1 file changed

+100
-14
lines changed

1 file changed

+100
-14
lines changed

‎docs/advanced-usage/custom-modes.md‎

Lines changed: 100 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Custom Modes
22

3-
Roo Code allows you to create **custom modes** that can be either global (available across all projects) or project-specific (defined within a single project). These modes let you tailor Roo's behavior to specific tasks or workflows by defining:
3+
Roo Code allows you to create **custom modes** to tailor Roo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project). They allow you to define:
44

55
* **A unique name and slug:** For easy identification.
66
* **A role definition:** A description of the mode's purpose and expertise.
@@ -15,7 +15,7 @@ Roo Code allows you to create **custom modes** that can be either global (availa
1515
* **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes.
1616
* **Team Collaboration:** Share custom modes with your team to standardize workflows.
1717

18-
## Creating a Custom Mode
18+
## Creating Custom Modes
1919

2020
You have three options for creating custom modes:
2121

@@ -40,29 +40,47 @@ Roo Code will guide you through the process.
4040

4141
Note: Adding/editing file type restrictions is not yet supported in the prompts tab UI.
4242

43-
### 3. Manual Configuration (Advanced)
43+
### 3. Manual Configuration
4444

45-
Custom modes can be configured in two locations:
45+
Custom modes can be configured by directly editing JSON files. There are two locations for custom mode configurations:
4646

47-
1. **Global Configuration:**
48-
- Located at `~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_custom_modes.json`
49-
- These modes are available across all projects
47+
1. **Global Configuration:**
48+
* Located at `~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_custom_modes.json`
49+
* These modes are available across all projects.
5050

51-
2. **Project-Specific Configuration:**
52-
- Located in `.roomodes` file in your project's root directory
53-
- These modes are only available within that specific project
54-
- Project-specific modes take precedence over global modes with the same slug
51+
2. **Project-Specific Configuration:**
52+
* Located in a `.roomodes` file in your project's root directory.
53+
* These modes are only available within that specific project.
54+
* **Project-specific modes take precedence over global modes with the same slug.** This means if you define a mode with the slug "code" in your `.roomodes` file, it will override the global "code" mode when you're working in that project.
5555

5656
To edit either configuration:
5757

5858
1. **Open the Prompts Tab:** Click the notebook icon in the Roo Code top menu bar.
59-
2. **Open the Settings File:** Click the code icon (`<>`) in the top right corner of the "Prompts" tab.
59+
2. **Open the Settings File:** Click the code icon (`<>`) in the top right corner of the "Prompts" tab. (This will open the global configuration file. To edit a project-specific configuration, you'll need to manually open the `.roomodes` file in your project's root directory.)
6060
3. **Edit the JSON:** Add or modify mode configurations within the `customModes` array, following the format described below.
6161
4. **Save the File:** Roo Code will automatically detect the changes.
6262

6363
## Custom Mode Configuration (JSON Format)
6464

65-
Both global and project-specific configuration files use the same JSON format. Here's an example:
65+
Both global and project-specific configuration files use the same JSON format. The configuration is a JSON object with a `customModes` key, which contains an array of mode definitions. Each mode definition is a JSON object with the following properties:
66+
67+
* `slug`: (Required) A unique identifier for the mode (lowercase letters, numbers, and hyphens). Shorter is better.
68+
* `name`: (Required) The display name for the mode.
69+
* `roleDefinition`: (Required) A detailed description of the mode's role and capabilities.
70+
* `groups`: (Required) An array of allowed tool groups. Each group can be specified either as a string (e.g., `"edit"` to allow editing any file) or with file restrictions (e.g., `["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }]` to only allow editing markdown files).
71+
* Available tool groups are: `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"`.
72+
* **Understanding `fileRegex`:** The `fileRegex` property uses a *regular expression* (or *regex*) to define which files the mode is allowed to edit. A regular expression is a sequence of characters that specifies a search pattern. Here's a breakdown of some common regex components used in the examples:
73+
* `\.`: Matches a literal dot (`.`). The backslash is used to "escape" the dot, since a dot has a special meaning in regular expressions (matching any character).
74+
* `(test|spec)`: Matches either "test" or "spec". The parentheses create a *capturing group*, and the pipe (`|`) acts as an "or".
75+
* `(js|ts|jsx|tsx)`: Matches "js", "ts", "jsx", or "tsx".
76+
* `$`: Matches the end of the string. This ensures that the entire filename matches the pattern, not just a part of it.
77+
* For example, `\\.md$` matches any filename that ends with ".md". `\\.(test|spec)\\.(js|ts|jsx|tsx)$` matches filenames like "myComponent.test.js", "utils.spec.ts", etc.
78+
* You can learn more about regular expressions on websites like [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).
79+
* `customInstructions`: (Optional) Additional instructions for the mode.
80+
81+
Here are some examples:
82+
83+
**Example 1: A simple documentation writer mode (could be global or project-specific):**
6684

6785
```json
6886
{
@@ -76,7 +94,16 @@ Both global and project-specific configuration files use the same JSON format. H
7694
"read",
7795
["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }]
7896
]
79-
},
97+
}
98+
]
99+
}
100+
```
101+
102+
**Example 2: A test engineer mode (could be global or project-specific):**
103+
104+
```json
105+
{
106+
"customModes": [
80107
{
81108
"slug": "test-engineer",
82109
"name": "Test Engineer",
@@ -90,6 +117,65 @@ Both global and project-specific configuration files use the same JSON format. H
90117
}
91118
```
92119

120+
**Example 3: Adding a new mode in a `.roomodes` file (project-specific):**
121+
122+
```json
123+
{
124+
"customModes": [
125+
{
126+
"slug": "data-scientist",
127+
"name": "Data Scientist",
128+
"roleDefinition": "You are Roo, a data scientist with expertise in data analysis, machine learning, and statistical modeling.",
129+
"groups": [
130+
"read",
131+
"edit",
132+
"command"
133+
],
134+
"customInstructions": "Focus on data analysis and machine learning tasks."
135+
}
136+
]
137+
}
138+
```
139+
140+
**Example 4: Overriding an existing mode in a `.roomodes` file (project-specific):**
141+
142+
```json
143+
{
144+
"customModes": [
145+
{
146+
"slug": "code", // Overrides the global "code" mode
147+
"name": "Code (Project-Specific)",
148+
"roleDefinition": "You are Roo, a highly skilled software engineer. In this project, you have limited file access.",
149+
"groups": [
150+
"read",
151+
["edit", { "fileRegex": "\\.(js|ts)$", "description": "JavaScript and TypeScript files only" }]
152+
],
153+
"customInstructions": "Focus on JS and TS files in this project."
154+
}
155+
]
156+
}
157+
```
158+
159+
**Example 5: Mode with File Restrictions (can be used in global or .roomodes)**
160+
```json
161+
{
162+
"customModes": [
163+
{
164+
"slug": "markdown-editor",
165+
"name": "Markdown Editor",
166+
"roleDefinition": "You are Roo, a markdown editor with expertise in editing and formatting markdown files.",
167+
"groups": [
168+
"read",
169+
["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }],
170+
"browser"
171+
],
172+
"customInstructions": "Focus on editing and formatting markdown files."
173+
}
174+
]
175+
}
176+
```
177+
By following these instructions, you can create and manage custom modes to enhance your workflow with Roo-Code.
178+
93179
## Community Gallery
94180

95181
Ready to explore more? Check out the [Custom Modes Gallery](../community#custom-modes-gallery) to discover and share custom modes created by the community!

0 commit comments

Comments
 (0)