diff --git a/docs/features/custom-modes.md b/docs/features/custom-modes.md index a9444507..9fd80cbd 100644 --- a/docs/features/custom-modes.md +++ b/docs/features/custom-modes.md @@ -1,27 +1,9 @@ # Customizing Modes -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). Each mode—including custom ones—features **Sticky Models**, automatically remembering and selecting the last model you used with it. This lets you assign different preferred models to different tasks without reconfiguration, as Roo switches between models when you change modes. +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). -:::info Mode-Specific Instruction File Locations -You can provide instructions for custom modes using dedicated files or directories within your workspace. This allows for better organization and version control compared to only using the JSON `customInstructions` property. - -**Preferred Method: Directory (`.roo/rules-{mode-slug}/`)** -``` -. -├── .roo/ -│ └── rules-docs-writer/ # Example for mode slug "docs-writer" -│ ├── 01-style-guide.md -│ └── 02-formatting.txt -└── ... (other project files) -``` - -**Fallback Method: Single File (`.roorules-{mode-slug}`)** -``` -. -├── .roorules-docs-writer # Example for mode slug "docs-writer" -└── ... (other project files) -``` -The directory method takes precedence if it exists and contains files. See [Mode-Specific Instructions via Files/Directories](#mode-specific-instructions-via-filesdirectories) for details. +:::tip Sticky Models for Efficient Workflow +Each mode—including custom ones—features **Sticky Models**. This means Roo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Roo switches between models when you change modes. ::: ## Why Use Custom Modes? @@ -31,93 +13,139 @@ The directory method takes precedence if it exists and contains files. See [Mode * **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes * **Team Collaboration:** Share custom modes with your team to standardize workflows - Overview of custom modes interface +Overview of custom modes interface + *Roo Code's interface for creating and managing custom modes.* ## What's Included in a Custom Mode? -Custom modes allow you to define: +Custom modes are defined by several key properties. Understanding these concepts will help you tailor Roo's behavior effectively before diving into the JSON configuration. -* **A unique name and slug:** For easy identification -* **A role definition:** Placed at the beginning of the system prompt, this defines Roo's core expertise and personality for the mode. This placement is crucial as it shapes Roo's fundamental understanding and approach to tasks -:::info Role Definition's First Sentence in System Prompt -The first sentence of the `roleDefinition` (up to the first period `.`) serves a dual purpose. When a mode is active, the *entire* definition appears at the beginning of the system prompt. Additionally, this first sentence is *always* included in a separate section of the system prompt that lists all available modes, providing Roo with context about each mode's capabilities even when it's not the active one. -::: -* **Custom instructions:** Added near the end of the system prompt, these provide specific guidelines that modify or refine Roo's behavior for the mode. You can define these using the `customInstructions` JSON property, and/or by adding instruction files to a dedicated directory (see below). The preferred method for file-based instructions is now using a **`.roo/rules-{mode-slug}/` directory**, which allows for better organization and takes precedence over the older `.roorules-{mode-slug}` file method. This structured placement allows for more nuanced control over Roo's responses. -* **Allowed tools:** Which Roo Code tools the mode can use (e.g., read files, write files, execute commands) -* **File restrictions:** (Optional) Limit file access to specific file types or patterns (e.g., only allow editing `.md` files) +| Property | Conceptual Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `slug` | A **unique internal identifier** for the mode. It's used by Roo Code to reference the mode, especially for associating [mode-specific instruction files](#mode-specific-instructions-via-filesdirectories). | +| `name` | The **display name** for the mode as it appears in the Roo Code user interface. This should be human-readable and descriptive. | +| `roleDefinition` | The **core identity and expertise** of the mode. This text is placed at the beginning of the system prompt to define Roo's personality and primary function for this mode.
- **Critical First Sentence:** The first sentence (up to the first period `.`) is vital. It serves as a concise summary for Roo to understand the mode's purpose, even when it's not the active one. The entire definition is used when the mode is active. | +| `groups` | Defines the **allowed toolsets and file access permissions** for the mode. You can specify which general categories of tools (like reading files, editing files, browsing, or executing commands) the mode can use. For editing, you can also specify restrictions on which file types are permissible. | +| `customInstructions` | **Specific behavioral guidelines** or rules for the mode. These instructions are added near the end of the system prompt to further refine Roo's behavior beyond the `roleDefinition`. This can be provided directly in the configuration or via separate instruction files. | -## Custom Mode Configuration (JSON Format) +## Methods for Creating and Configuring Custom Modes -Both global and project-specific configurations use the same JSON format. Each configuration file contains a `customModes` array of mode definitions: +You can create and configure custom modes in several ways: -```json -{ - "customModes": [ - { - "slug": "mode-name", - "name": "Mode Display Name", - "roleDefinition": "Mode's role and capabilities", - "groups": ["read", "edit"], - "customInstructions": "Additional guidelines" - } - ] -} +### 1. Ask Roo! (Recommended) + +You can quickly create a basic custom mode by asking Roo Code to do it for you. For example: ``` +Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files. +``` +Roo Code will guide you through the process, prompting for necessary information for the properties described in the [What's Included in a Custom Mode?](#whats-included-in-a-custom-mode) table. For fine-tuning or making specific adjustments later, you can use the Prompts tab or manual configuration. -### Required Properties +### 2. Using the Prompts Tab -#### `slug` -* A unique identifier for the mode -* Use lowercase letters, numbers, and hyphens -* Keep it short and descriptive -* Example: `"docs-writer"`, `"test-engineer"` +1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar. +2. **Create New Mode:** Click the button to the right of the Modes heading. +3. **Fill in Fields:** -#### `name` -* The display name shown in the UI -* Can include spaces and proper capitalization -* Example: `"Documentation Writer"`, `"Test Engineer"` +Custom mode creation interface in the Prompts tab +*The custom mode creation interface showing fields for name, slug, save location, role definition, available tools, and custom instructions.* -#### `roleDefinition` -* Detailed description of the mode's role and capabilities -* Defines Roo's expertise and personality for this mode -* Example: `"You are a technical writer specializing in clear documentation"` + The interface provides fields for `Name`, `Slug`, `Save Location`, `Role Definition`, `Available Tools`, and `Custom Instructions`. After filling these, click the "Create Mode" button. -#### `groups` -* Array of allowed tool groups -* Available groups: `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"` -* Can include file restrictions for the `"edit"` group +*Refer to the [What's Included in a Custom Mode?](#whats-included-in-a-custom-mode) table for conceptual explanations of each property. File type restrictions for the "edit" tool group can be added by asking Roo or through manual JSON configuration.* -##### File Restrictions Format -```json -["edit", { - "fileRegex": "\\.md$", - "description": "Markdown files only" -}] -``` +### 3. Manual Configuration and JSON Structure -### Understanding File Restrictions +You can directly edit the JSON configuration files to create or modify custom modes. This method offers the most control over all properties. -The `fileRegex` property uses regular expressions to control which files a mode can edit: +* **Global Modes:** Edit the `custom_modes.json` file. Access it via **Prompts Tab** > (Settings Menu) > "Edit Global Modes". +* **Project Modes:** Edit the `.roomodes` file in your project root. Access it via **Prompts Tab** > (Settings Menu) > "Edit Project Modes". + +Both files use the same JSON format. Each configuration file contains a `customModes` array, where each element is an object defining a single custom mode. + +```json +{ + "customModes": [ + { + "slug": "mode-slug-example", + "name": "Example Mode Display Name", + "roleDefinition": "This mode's role and capabilities are defined here.", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.txt$", "description": "Text files only" }] + ], + "customInstructions": "Additional guidelines for this example mode." + } + ] +} +``` -* `\\.md$` - Match files ending in ".md" -* `\\.(test|spec)\\.(js|ts)$` - Match test files (e.g., "component.test.js") -* `\\.(js|ts)$` - Match JavaScript and TypeScript files +#### JSON Property Details + +##### `slug` +* **Purpose:** A unique identifier for the mode. +* **Format:** Use lowercase letters, numbers, and hyphens. +* **Usage:** Used internally and in file/directory names for mode-specific rules (e.g., `.roo/rules-{slug}/`). +* **Recommendation:** Keep it short and descriptive. +* *JSON Example:* `"slug": "docs-writer"` + +##### `name` +* **Purpose:** The display name shown in the Roo Code UI. +* **Format:** Can include spaces and proper capitalization. +* *JSON Example:* `"name": "Documentation Writer"` + +##### `roleDefinition` +* **Purpose:** Detailed description of the mode's role, expertise, and personality. +* **Placement:** This text is placed at the beginning of the system prompt when the mode is active. +* **Critical First Sentence:** As noted in the table above, the first sentence is crucial for summarizing the mode's function. +* *JSON Example:* `"roleDefinition": "You are a technical writer specializing in clear documentation."` + +##### `groups` +* **Purpose:** Array defining which tool groups the mode can access and any file restrictions. +* **Available Tool Groups (Strings):** `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"`. +* **File Restrictions for "edit" group:** + * **Format:** To apply file restrictions, the "edit" entry becomes an array: `["edit", { "fileRegex": "your-regex-pattern", "description": "Optional description" }]` + * `fileRegex`: A JavaScript-style regular expression string to control which files the mode can edit. Remember to double-escape backslashes in the JSON string (e.g., `\\.` for a literal dot). + * *Example `fileRegex` values:* `"\\.md$"` (Markdown files), `"\\.(test\|spec)\\.(js\|ts)$"` (JS/TS test files). + * `description`: An optional string describing the restriction. + * For more complex patterns and detailed explanations, see [Understanding Regex in Custom Modes](#understanding-regex-in-custom-modes). +* *JSON Example:* + ```json + "groups": [ + "read", + ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] + ] + ``` -Common regex patterns: -* `\\.` - Match a literal dot -* `(a|b)` - Match either "a" or "b" -* `$` - Match the end of the filename +##### `customInstructions` +* **Purpose:** A string containing additional behavioral guidelines for the mode. +* **Placement:** This text is added near the end of the system prompt. +* **Supplementing:** Can be supplemented or replaced by instructions in [Mode-Specific Instructions via Files/Directories](#mode-specific-instructions-via-filesdirectories). +* *JSON Example:* `"customInstructions": "Focus on explaining concepts and providing examples."` -[Learn more about regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) +## Mode-Specific Instructions via Files/Directories -### Optional Properties +:::info Mode-Specific Instruction File Locations +You can provide instructions for custom modes using dedicated files or directories within your workspace. This allows for better organization and version control compared to only using the JSON `customInstructions` property. -#### `customInstructions` -* Additional behavioral guidelines for the mode -* Example: `"Focus on explaining concepts and providing examples"` +**Preferred Method: Directory (`.roo/rules-{mode-slug}/`)** +``` +. +├── .roo/ +│ └── rules-docs-writer/ # Example for mode slug "docs-writer" +│ ├── 01-style-guide.md +│ └── 02-formatting.txt +└── ... (other project files) +``` -### Mode-Specific Instructions via Files/Directories +**Fallback Method: Single File (`.roorules-{mode-slug}`)** +``` +. +├── .roorules-docs-writer # Example for mode slug "docs-writer" +└── ... (other project files) +``` +The directory method takes precedence if it exists and contains files. +::: In addition to the `customInstructions` property in JSON, you can provide mode-specific instructions via files in your workspace. This is particularly useful for: @@ -160,86 +188,6 @@ This means that project-specific configurations will override global configurati * **Note on Instruction Files:** Within the loading of mode-specific instructions from the filesystem, the directory `.roo/rules-{mode-slug}/` takes precedence over the single file `.roorules-{mode-slug}` found in the workspace root. -## Creating Custom Modes - -You have three options for creating custom modes: - -### 1. Ask Roo! (Recommended) - -You can quickly create a basic custom mode by asking Roo Code to do it for you. For example: -``` -Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files. -``` -Roo Code will guide you through the process. However, for fine-tuning modes or making specific adjustments, you'll want to use the Prompts tab or manual configuration methods described below. - -### 2. Using the Prompts Tab - -1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar -2. **Create New Mode:** Click the button to the right of the Modes heading -3. **Fill in Fields:** - - Custom mode creation interface in the Prompts tab - *The custom mode creation interface showing fields for name, slug, save location, role definition, available tools, and custom instructions.* - - * **Name:** Enter a display name for the mode - * **Slug:** Enter a lowercase identifier (letters, numbers, and hyphens only) - * **Save Location:** Choose Global (via `custom_modes.json`, available across all workspaces) or Project-specific (via `.roomodes` file in project root) - * **Role Definition:** Define Roo's expertise and personality for this mode (appears at the start of the system prompt) - * **Available Tools:** Select which tools this mode can use - * **Custom Instructions:** (Optional) Add behavioral guidelines specific to this mode (appears at the end of the system prompt) -4. **Create Mode:** Click the "Create Mode" button to save your new mode - -Note: File type restrictions can only be added through manual configuration. - -### 3. Manual Configuration - -You can configure custom modes by editing JSON files through the Prompts tab: - -Both global and project-specific configurations can be edited through the Prompts tab: - -1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar -2. **Access Settings Menu:** Click the button to the right of the Modes heading -3. **Choose Configuration:** - * Select "Edit Global Modes" to edit `custom_modes.json` (available across all workspaces) - * Select "Edit Project Modes" to edit `.roomodes` file (in project root) -4. **Edit Configuration:** Modify the JSON file that opens -5. **Save Changes:** Roo Code will automatically detect the changes - -## Example Configurations - -Each example shows different aspects of mode configuration: - -### Basic Documentation Writer -```json -{ - "customModes": [{ - "slug": "docs-writer", - "name": "Documentation Writer", - "roleDefinition": "You are a technical writer specializing in clear documentation", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] - ], - "customInstructions": "Focus on clear explanations and examples" - }] -} -``` - -### Test Engineer with File Restrictions -```json -{ - "customModes": [{ - "slug": "test-engineer", - "name": "Test Engineer", - "roleDefinition": "You are a test engineer focused on code quality", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts)$", "description": "Test files only" }] - ] - }] -} -``` - ## Overriding Default Modes You can override Roo Code's built-in modes (like `💻 Code`, `🪲 Debug`, `❓ Ask`, `🏗️ Architect`, `🪃 Orchestrator` (aka Boomerang Mode)) with customized versions that better suit your workflow. This is done by creating a custom mode with the same slug as a default mode (e.g., `code`, `debug`, `orchestrator`). @@ -313,58 +261,87 @@ By following these instructions, you can create and manage custom modes to enhan ## Understanding Regex in Custom Modes -Regex patterns in custom modes let you precisely control which files Roo can edit: +While basic file restrictions are covered under the `groups` property, this section provides a more detailed look at using regular expressions for advanced control over which files Roo can edit. -### Basic Syntax +:::tip +**Let Roo Build Your Regex Patterns** -When you specify `fileRegex` in a custom mode, you're creating a pattern that file paths must match: +Instead of writing complex regex patterns manually, you can ask Roo to create them for you! Simply describe which files you want to include or exclude: +``` +Create a regex pattern that matches JavaScript files but excludes test files +``` +Roo will generate the appropriate pattern with proper escaping for JSON configuration. +::: +When you specify `fileRegex` in a custom mode, you're creating a pattern that file paths must match. For example: ```json ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] ``` -### Important Rules - -- **Double Backslashes:** In JSON, backslashes must be escaped with another backslash. So `\.md$` becomes `\\.md$` -- **Path Matching:** Patterns match against the full file path, not just the filename -- **Case Sensitivity:** Regex patterns are case-sensitive by default +**Important Rules for `fileRegex`:** +* **Double Backslashes:** In JSON strings, backslashes (`\`) are special characters and must be escaped with another backslash. So, a regex pattern like `\.md$` becomes `"\\.md$"` in your JSON configuration. +* **Path Matching:** Patterns match against the full relative file path from your workspace root (e.g., `src/components/button.js`), not just the filename. +* **Case Sensitivity:** Regex patterns are case-sensitive by default. -### Common Pattern Examples +**Common Pattern Examples:** -| Pattern | Matches | Doesn't Match | -|---------|---------|---------------| -| `\\.md$` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` | -| `^src/.*` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` | -| `\\.(css\|scss)$` | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` | -| `docs/.*\\.md$` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` | -| `^(?!.*(test\|spec)).*\\.js$` | `app.js`, `utils.js` | `app.test.js`, `utils.spec.js` | +| Pattern | Matches | Doesn't Match | +| ------------------------------- | ----------------------------------------- | ------------------------------------- | +| `"\\.md$"` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` | +| `"^src/.*"` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` | +| `"\\.(css\|scss)$"` | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` | +| `"docs/.*\\.md$"` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` | +| `"^(?!.*(test\|spec))\\.(js\|ts)$"` | `app.js`, `utils.ts` | `app.test.js`, `utils.spec.js`, `app.jsx` | -### Pattern Building Blocks -- `\\.` - Match a literal dot (period) -- `$` - Match the end of the string -- `^` - Match the beginning of the string -- `.*` - Match any character (except newline) zero or more times -- `(a|b)` - Match either "a" or "b" -- `(?!...)` - Negative lookahead (exclude matches) +**Key Regex Building Blocks:** +* `\.`: Matches a literal dot (period). In JSON, use `"\\."`. +* `$`: Matches the end of the string (filename). +* `^`: Matches the beginning of the string (filepath). +* `.*`: Matches any character (except newline) zero or more times. +* `(a|b)`: Matches either "a" or "b". In JSON, use `"\\.(js|ts)$"` to match `.js` or `.ts`. +* `(?!...)`: Negative lookahead (asserts that the pattern does not match). For example, `^(?!.*(test\|spec))` ensures the path doesn't contain "test" or "spec". -### Testing Your Patterns +**Testing Your Patterns:** +Before applying a regex pattern: +1. Test it on sample file paths to ensure it behaves as expected. Online regex testers can be helpful. +2. Remember the double backslash rule for JSON. +3. Start with simpler patterns and build complexity gradually. -Before applying a regex pattern to a custom mode: - -1. Test it on sample file paths to ensure it matches what you expect -2. Remember that in JSON, each backslash needs to be doubled (`\d` becomes `\\d`) -3. Start with simpler patterns and build complexity gradually +## Example Configurations +Each example shows different aspects of mode configuration: -:::tip -### Let Roo Build Your Regex Patterns -Instead of writing complex regex patterns manually, you can ask Roo to create them for you! Simply describe which files you want to include or exclude: +### Basic Documentation Writer +```json +{ + "customModes": [{ + "slug": "docs-writer", + "name": "Documentation Writer", + "roleDefinition": "You are a technical writer specializing in clear documentation", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] + ], + "customInstructions": "Focus on clear explanations and examples" + }] +} ``` -Create a regex pattern that matches JavaScript files but excludes test files + +### Test Engineer with File Restrictions +```json +{ + "customModes": [{ + "slug": "test-engineer", + "name": "Test Engineer", + "roleDefinition": "You are a test engineer focused on code quality", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts)$", "description": "Test files only" }] + ] + }] +} ``` -Roo will generate the appropriate pattern with proper escaping for JSON configuration. -::: ## Community Gallery Ready to explore more? Check out the [Custom Modes Gallery](/community/#custom-modes-gallery) section on the main community page to discover and share custom modes created by the community! diff --git a/docs/features/shell-integration.md b/docs/features/shell-integration.md index 93a21dd9..7fd5067a 100644 --- a/docs/features/shell-integration.md +++ b/docs/features/shell-integration.md @@ -14,7 +14,8 @@ Shell integration is automatically enabled in Roo Code and connects directly to - React intelligently to terminal output without user intervention - Stop running commands directly from the chat interface using the stop button that appears next to the command execution message. - Stop Command Button in Chat UI +Stop Command Button in Chat UI + When you ask Roo to perform tasks like installing dependencies, starting a development server, or analyzing build errors, shell integration works behind the scenes to make these interactions smooth and effective. ## Troubleshooting Shell Integration @@ -35,8 +36,7 @@ Roo Code includes a fallback mechanism to ensure commands can still run even if - **Notification**: You'll see a notification in the chat if this fallback is used, indicating that the command is running without full shell integration features (like real-time output streaming or exit code detection might be limited). - **Resolution**: The notification will include links to help you troubleshoot the underlying shell integration issue if you wish to restore full functionality. Often, following the steps in this document resolves the problem. - Stop Command Button in Chat UI - +Stop Command Button in Chat UI Roo Code provides several settings to fine-tune shell integration. Access these in the Roo Code sidebar under Settings → Terminal. @@ -44,33 +44,11 @@ Roo Code provides several settings to fine-tune shell integration. Access these #### Terminal Output Limit Terminal output limit slider set to 500 -Controls the maximum number of lines captured from terminal output. When exceeded, it keeps 20% of the beginning and 80% of the end with a truncation message in between. This prevents excessive token usage while maintaining context. Default: 500 lines. -Controls the maximum number of lines captured from terminal output. When exceeded, lines are removed from the middle to save tokens. Default: 500 lines. - -#### Terminal Shell Integration Timeout -Terminal shell integration timeout slider set to 15s - -Maximum time to wait for shell integration to initialize before executing commands. Increase this value if you experience "Shell Integration Unavailable" errors. Default: 15 seconds. - -#### Terminal Command Delay -Terminal command delay slider set to 0ms - -Adds a small pause after running commands to help Roo capture all output correctly. This setting can significantly impact shell integration reliability due to VSCode's implementation of terminal integration across different operating systems and shell configurations: - -- **Default**: 0ms (as of Roo v3.11.13) -- **Common Values**: - * 0ms: Works best for some users with newer VSCode versions - * 50ms: Historical default, still effective for many users - * 150ms: Recommended for PowerShell users -- **Note**: Different values may work better depending on your: - * VSCode version - * Shell customizations (oh-my-zsh, powerlevel10k, etc.) - * Operating system and environment - -#### Disable Terminal Shell Integration -Disable terminal shell integration checkbox +Maximum number of lines to include in terminal output when executing commands. When exceeded lines will be removed from the middle, saving tokens. Default: 500 lines. -Enable this setting if terminal commands aren't working correctly or you encounter 'Shell Integration Unavailable' errors. When enabled, Roo Code uses a simpler, fallback method to execute commands, which bypasses some advanced terminal integration features but can improve reliability in problematic environments. +#### Compress progress bar output +Compress progress bar output checkbox +When enabled, processes terminal output with carriage returns (\\r) to simulate how a real terminal would display content like progress bars. This removes intermediate progress bar states, retaining only the final state, which conserves context space for more relevant information. ### Advanced Settings @@ -85,30 +63,43 @@ Changes to advanced terminal settings only take effect after restarting your ter Always restart all open terminals after changing any of these settings. ::: -#### PowerShell Counter Workaround -PowerShell counter workaround checkbox +#### Inherit environment variables +Inherit environment variables checkbox +When enabled, the terminal will inherit environment variables from VSCode's parent process, such as user-profile-defined shell integration settings. This directly toggles the VSCode global setting [`terminal.integrated.inheritEnv`](https://code.visualstudio.com/docs/editor/integrated-terminal#_inherit-environment-variables). -Helps PowerShell run the same command multiple times in a row. Enable this if you notice Roo can't run identical commands consecutively in PowerShell. +#### Disable terminal shell integration +Disable terminal shell integration checkbox +Enable this if terminal commands aren't working correctly or you see 'Shell Integration Unavailable' errors. This uses a simpler method to run commands, bypassing some advanced terminal features. -#### Clear ZSH EOL Mark -Clear ZSH EOL mark checkbox +The following settings are applicable when "Disable terminal shell integration" is **unchecked** (i.e., shell integration is enabled): -Prevents ZSH from adding special characters at the end of output lines that can confuse Roo when reading terminal results. +##### a. Terminal shell integration timeout +Terminal shell integration timeout slider set to 15s +Maximum time to wait for shell integration to initialize before executing commands. For users with long shell startup times, this value may need to be increased if you see 'Shell Integration Unavailable' errors in the terminal. Default: 15s (as shown in UI). -#### Oh My Zsh Integration -Enable Oh My Zsh integration checkbox +##### b. Terminal command delay +Terminal command delay slider set to 0ms +Delay in milliseconds to add after command execution. The default setting of 0 disables the delay completely. This can help ensure command output is fully captured in terminals with timing issues. In most terminals, it is implemented by setting `PROMPT_COMMAND='sleep N'` and Powershell appends `start-sleep` to the end of each command. Originally was workaround for VSCode bug [#237208](https://github.com/microsoft/vscode/issues/237208) and may not be needed. Default: 0ms. -Makes Roo work better with the popular Oh My Zsh shell customization framework. Turn this on if you use Oh My Zsh and experience terminal issues. +##### c. Enable PowerShell counter workaround +Enable PowerShell counter workaround checkbox +When enabled, adds a counter to PowerShell commands to ensure proper command execution. This helps with PowerShell terminals that might have issues with command output capture. -#### Powerlevel10k Integration -Enable Powerlevel10k integration checkbox +##### d. Clear ZSH EOL mark +Clear ZSH EOL mark checkbox +When enabled, clears the ZSH end-of-line mark by setting `PROMPT_EOL_MARK=''`. This prevents issues with command output interpretation when output ends with special characters like '%'. -Improves compatibility if you use the Powerlevel10k theme for ZSH. Turn this on if your fancy terminal prompt causes issues with Roo. +##### e. Enable Oh My Zsh integration +Enable Oh My Zsh integration checkbox +When enabled, sets `ITERM_SHELL_INTEGRATION_INSTALLED=Yes` to enable Oh My Zsh shell integration features. Applying this setting might require restarting the IDE. -#### ZDOTDIR Handling -Enable ZDOTDIR handling checkbox +##### f. Enable Powerlevel10k integration +Enable Powerlevel10k integration checkbox +When enabled, sets `POWERLEVEL9K_TERM_SHELL_INTEGRATION=true` to enable Powerlevel10k shell integration features. -Helps Roo work with custom ZSH configurations without interfering with your personal shell settings and customizations. +##### g. Enable ZDOTDIR handling +Enable ZDOTDIR handling checkbox +When enabled, creates a temporary directory for ZDOTDIR to handle zsh shell integration properly. This ensures VSCode shell integration works correctly with zsh while preserving your zsh configuration. ## How Shell Integration Works diff --git a/static/img/custom-modes/custom-modes-1.png b/static/img/custom-modes/custom-modes-1.png new file mode 100644 index 00000000..c9ad7a98 Binary files /dev/null and b/static/img/custom-modes/custom-modes-1.png differ diff --git a/static/img/shell-integration/shell-integration-10.png b/static/img/shell-integration/shell-integration-10.png new file mode 100644 index 00000000..22347adc Binary files /dev/null and b/static/img/shell-integration/shell-integration-10.png differ diff --git a/static/img/shell-integration/shell-integration-11.png b/static/img/shell-integration/shell-integration-11.png new file mode 100644 index 00000000..4aa836e2 Binary files /dev/null and b/static/img/shell-integration/shell-integration-11.png differ