diff --git a/docs/community.md b/docs/community.md index 512ccd3c..48d1092c 100644 --- a/docs/community.md +++ b/docs/community.md @@ -181,7 +181,7 @@ This mode is an orchestrator who gets things done by delegating subtasks to the "slug": "orchestrator", "name": "Orchestrator", "roleDefinition": "You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.", - "customInstructions": "Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes.\n\n2. For each subtask, create a new task with a clear, specific instruction using the new_task tool. Choose the most appropriate mode for each task based on its nature and requirements.\n\n3. Track and manage the progress of all subtasks. When a subtask is completed, analyze its results and determine the next steps.\n\n4. Help the user understand how the different subtasks fit together in the overall workflow. Provide clear reasoning about why you're delegating specific tasks to specific modes.\n\n5. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n6. You can also manage custom modes by editing cline_custom_modes.json and .roomodes files directly. This allows you to create, modify, or delete custom modes as part of your orchestration capabilities.\n\n7. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n8. Suggest improvements to the workflow based on the results of completed subtasks.", + "customInstructions": "Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes.\n\n2. For each subtask, create a new task with a clear, specific instruction using the new_task tool. Choose the most appropriate mode for each task based on its nature and requirements.\n\n3. Track and manage the progress of all subtasks. When a subtask is completed, analyze its results and determine the next steps.\n\n4. Help the user understand how the different subtasks fit together in the overall workflow. Provide clear reasoning about why you're delegating specific tasks to specific modes.\n\n5. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n6. You can also manage custom modes by editing custom_modes.json and .roomodes files directly. This allows you to create, modify, or delete custom modes as part of your orchestration capabilities.\n\n7. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n8. Suggest improvements to the workflow based on the results of completed subtasks.", "groups": [ "read", ["edit", { "fileRegex": "\\.roomodes$|cline_custom_modes\\.json$", "description": "Mode configuration files only" }] @@ -209,7 +209,7 @@ This orchestrator excels at managing large, complex projects by maintaining clea "slug": "advanced-orchestrator", "name": "Advanced Orchestrator", "roleDefinition": "You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.", - "customInstructions": "Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes:\n - Create specific, clearly defined, and scope-limited subtasks\n - Ensure each subtask fits within context length limitations\n - Make subtask divisions granular enough to prevent misunderstandings and information loss\n - Prioritize core functionality implementation over iterative development when task complexity is high\n\n2. For each subtask, create a new task with a clear, specific instruction using the new_task tool:\n - Choose the most appropriate mode for each task based on its nature and requirements\n - Provide detailed requirements and summaries of completed work for context\n - Store all subtask-related content in a dedicated prompt directory\n - Ensure subtasks focus on their specific stage while maintaining compatibility with other modules\n\n3. Track and manage the progress of all subtasks:\n - Arrange subtasks in a logical sequence based on dependencies\n - Establish checkpoints to validate incremental achievements\n - Reserve adequate context space for complex subtasks\n - Define clear completion criteria for each subtask\n - When a subtask is completed, analyze its results and determine the next steps\n\n4. Facilitate effective communication throughout the workflow:\n - Use clear, natural language for subtask descriptions (avoid code blocks in descriptions)\n - Provide sufficient context information when initiating each subtask\n - Keep instructions concise and unambiguous\n - Clearly label inputs and expected outputs for each subtask\n\n5. Help the user understand how the different subtasks fit together in the overall workflow:\n - Provide clear reasoning about why you're delegating specific tasks to specific modes\n - Document the workflow architecture and dependencies between subtasks\n - Visualize the workflow when helpful for understanding\n\n6. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n7. You can also manage custom modes by editing cline_custom_modes.json and .roomodes files directly. This allows you to create, modify, or delete custom modes as part of your orchestration capabilities.\n\n8. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n9. Suggest improvements to the workflow based on the results of completed subtasks.", + "customInstructions": "Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes:\n - Create specific, clearly defined, and scope-limited subtasks\n - Ensure each subtask fits within context length limitations\n - Make subtask divisions granular enough to prevent misunderstandings and information loss\n - Prioritize core functionality implementation over iterative development when task complexity is high\n\n2. For each subtask, create a new task with a clear, specific instruction using the new_task tool:\n - Choose the most appropriate mode for each task based on its nature and requirements\n - Provide detailed requirements and summaries of completed work for context\n - Store all subtask-related content in a dedicated prompt directory\n - Ensure subtasks focus on their specific stage while maintaining compatibility with other modules\n\n3. Track and manage the progress of all subtasks:\n - Arrange subtasks in a logical sequence based on dependencies\n - Establish checkpoints to validate incremental achievements\n - Reserve adequate context space for complex subtasks\n - Define clear completion criteria for each subtask\n - When a subtask is completed, analyze its results and determine the next steps\n\n4. Facilitate effective communication throughout the workflow:\n - Use clear, natural language for subtask descriptions (avoid code blocks in descriptions)\n - Provide sufficient context information when initiating each subtask\n - Keep instructions concise and unambiguous\n - Clearly label inputs and expected outputs for each subtask\n\n5. Help the user understand how the different subtasks fit together in the overall workflow:\n - Provide clear reasoning about why you're delegating specific tasks to specific modes\n - Document the workflow architecture and dependencies between subtasks\n - Visualize the workflow when helpful for understanding\n\n6. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n7. You can also manage custom modes by editing custom_modes.json and .roomodes files directly. This allows you to create, modify, or delete custom modes as part of your orchestration capabilities.\n\n8. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n9. Suggest improvements to the workflow based on the results of completed subtasks.", "groups": [ "read", ["edit", { "fileRegex": "\\.roomodes$|cline_custom_modes\\.json$", "description": "Mode configuration files only" }] diff --git a/docs/faq.md b/docs/faq.md index 0d9a93fb..046d3344 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -104,7 +104,7 @@ Yes, if you are using a provider with a model that support web browsing. Be mind ### Can Roo Code run commands in my terminal? -Yes, Roo Code can execute commands in your VS Code terminal. You will be prompted to approve each command before it's executed, unless you've enabled auto-approval for commands. Be extremely cautious about auto-approving commands. If you're experiencing issues with terminal commands, see the [Shell Integration Guide](/troubleshooting/shell-integration) for troubleshooting. +Yes, Roo Code can execute commands in your VS Code terminal. You will be prompted to approve each command before it's executed, unless you've enabled auto-approval for commands. Be extremely cautious about auto-approving commands. If you're experiencing issues with terminal commands, see the [Shell Integration Guide](/features/shell-integration) for troubleshooting. ### How do I provide feedback to Roo Code? diff --git a/docs/features/custom-modes.md b/docs/features/custom-modes.md index 400af9d6..12ec03a1 100644 --- a/docs/features/custom-modes.md +++ b/docs/features/custom-modes.md @@ -114,11 +114,6 @@ Common regex patterns: * Additional behavioral guidelines for the mode * Example: `"Focus on explaining concepts and providing examples"` -#### `apiConfiguration` -* Optional settings to customize the AI model and parameters for this mode -* Allows optimizing the model selection for specific tasks -* Example: `{"model": "gpt-4", "temperature": 0.2}` - ### Mode-Specific Instructions via Files/Directories In addition to the `customInstructions` property in JSON, you can provide mode-specific instructions via files in your workspace. This is particularly useful for: diff --git a/docs/features/shell-integration.md b/docs/features/shell-integration.md new file mode 100644 index 00000000..9be1012f --- /dev/null +++ b/docs/features/shell-integration.md @@ -0,0 +1,234 @@ +# Terminal Shell Integration + +Terminal Shell Integration is a key feature that enables Roo Code to execute commands in your terminal and intelligently process their output. This bidirectional communication between the AI and your development environment unlocks powerful automation capabilities. + +## What is Shell Integration? + +Shell integration is automatically enabled in Roo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Roo to: + +- Execute commands on your behalf through the [`execute_command`](/features/tools/execute-command) tool +- Read command output in real-time without manual copy-pasting +- Automatically detect and fix errors in running applications +- Observe command exit codes to determine success or failure +- Track working directory changes as you navigate your project +- React intelligently to terminal output without user intervention + +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 + +Shell integration is built into Roo Code and works automatically in most cases. If you see "Shell Integration Unavailable" messages or experience issues with command execution, try these solutions: + +1. **Update VSCode/Cursor** to the latest version (VSCode 1.93+ required) +2. **Ensure a compatible shell is selected**: Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) → "Terminal: Select Default Profile" → Choose bash, zsh, PowerShell, or fish +3. **Windows PowerShell users**: Run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` then restart VSCode +4. **WSL users**: Add `. "$(code --locate-shell-integration-path bash)"` to your `~/.bashrc` + +## Terminal Integration Settings + +Roo Code provides several settings to fine-tune shell integration. Access these in the Roo Code sidebar under Settings → Terminal. + +### Basic Settings + +#### Terminal Output Limit +Terminal output limit slider set to 500 + +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 is helpful if Roo seems to miss parts of command output or reacts before commands finish. Default: 0ms (disabled). + +### Advanced Settings + +:::info Important +**Terminal restart required for these settings** + +Changes to advanced terminal settings only take effect after restarting your terminals. To restart a terminal: + +1. Click the trash icon in the terminal panel to close the current terminal +2. Open a new terminal with Terminal → New Terminal or Ctrl+` (backtick) + +Always restart all open terminals after changing any of these settings. +::: + +#### PowerShell Counter Workaround +PowerShell counter workaround checkbox + +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. + +#### Clear ZSH EOL Mark +Clear ZSH EOL mark checkbox + +Prevents ZSH from adding special characters at the end of output lines that can confuse Roo when reading terminal results. + +#### Oh My Zsh Integration +Enable Oh My Zsh integration checkbox + +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. + +#### Powerlevel10k Integration +Enable Powerlevel10k integration checkbox + +Improves compatibility if you use the Powerlevel10k theme for ZSH. Turn this on if your fancy terminal prompt causes issues with Roo. + +#### ZDOTDIR Handling +Enable ZDOTDIR handling checkbox + +Helps Roo work with custom ZSH configurations without interfering with your personal shell settings and customizations. + +## How Shell Integration Works + +Shell integration connects Roo to your terminal's command execution process in real-time: + +1. **Connection**: When you open a terminal, VS Code establishes a special connection with your shell. + +2. **Command Tracking**: VS Code monitors your terminal activities by detecting: + - When a new prompt appears + - When you enter a command + - When the command starts running + - When the command finishes (and whether it succeeded or failed) + - What directory you're currently in + +3. **Different Shells, Same Result**: Each shell type (Bash, Zsh, PowerShell, Fish) implements this slightly differently behind the scenes, but they all provide the same functionality to Roo. + +4. **Information Gathering**: Roo can see what commands are running, where they're running, how long they take, whether they succeed, and their complete output - all without you having to copy and paste anything. + +## Troubleshooting Shell Integration + +### PowerShell Execution Policy (Windows) + +PowerShell restricts script execution by default. To configure: + +1. Open PowerShell as Administrator +2. Check current policy: `Get-ExecutionPolicy` +3. Set appropriate policy: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` + +Common policies: +- `Restricted`: No scripts allowed (default) +- `RemoteSigned`: Local scripts can run; downloaded scripts need signing +- `Unrestricted`: All scripts run with warnings +- `AllSigned`: All scripts must be signed + +### Manual Shell Integration Installation + +If automatic integration fails, add the appropriate line to your shell configuration: + +**Bash** (`~/.bashrc`): +```bash +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)" +``` + +**Zsh** (`~/.zshrc`): +```bash +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)" +``` + +**PowerShell** (`$Profile`): +```powershell +if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" } +``` + +**Fish** (`~/.config/fish/config.fish`): +```fish +string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish) +``` + +### Terminal Customization Issues + +If you use terminal customization tools: + +**Powerlevel10k**: +```bash +# Add before sourcing powerlevel10k in ~/.zshrc +typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true +``` + +**Alternative**: Enable the Powerlevel10k Integration setting in Roo Code. + +### Verifying Shell Integration Status + +Confirm shell integration is active with these commands: + +**Bash**: +```bash +set | grep -i '[16]33;' +echo "$PROMPT_COMMAND" | grep vsc +trap -p DEBUG | grep vsc +``` + +**Zsh**: +```zsh +functions | grep -i vsc +typeset -p precmd_functions preexec_functions +``` + +**PowerShell**: +```powershell +Get-Command -Name "*VSC*" -CommandType Function +Get-Content Function:\Prompt | Select-String "VSCode" +``` + +**Fish**: +```fish +functions | grep -i vsc +functions fish_prompt | grep -i vsc +``` + +Visual indicators of active shell integration: +1. Shell integration indicator in terminal title bar +2. Command detection highlighting +3. Working directory updates in terminal title +4. Command duration and exit code reporting + +## Known Issues and Workarounds + +### Ctrl+C Behavior + +**Issue**: If text is already typed in the terminal when Roo tries to run a command, Roo will press Ctrl+C first to clear the line, which can interrupt running processes. + +**Workaround**: Make sure your terminal prompt is empty (no partial commands typed) before asking Roo to execute terminal commands. + +### Multi-line Command Issues + +**Issue**: Commands that span multiple lines can confuse Roo and may show output from previous commands mixed in with current output. + +**Workaround**: Instead of multi-line commands, use command chaining with `&&` to keep everything on one line (e.g., `echo a && echo b` instead of typing each command on a separate line). + +### PowerShell-Specific Issues + +1. **Premature Completion**: PowerShell sometimes tells Roo a command is finished before all the output has been shown. +2. **Repeated Commands**: PowerShell may refuse to run the same command twice in a row. + +**Workaround**: Enable the "PowerShell counter workaround" setting and set a terminal command delay of 150ms in the settings to give commands more time to complete. + +### Incomplete Terminal Output + +**Issue**: Sometimes VS Code doesn't show or capture all the output from a command. + +**Workaround**: If you notice missing output, try closing and reopening the terminal tab, then run the command again. This refreshes the terminal connection. + +## Troubleshooting Resources + +- [VSCode Terminal Output Issue #237208](https://github.com/microsoft/vscode/issues/237208) +- [VSCode Terminal Integration Test Repository](https://github.com/KJ7LNW/vsce-test-terminal-integration) +- [Roo Code Shell Integration Architecture PR](https://github.com/RooVetGit/Roo-Code/pull/1365) + +## Support + +If you're still having issues: + +1. Check [Roo Code GitHub Issues](https://github.com/RooVetGit/Roo-Code/issues) +2. Create a new issue with: + - OS and VSCode version + - Shell type + - Steps to reproduce + - Error messages + +For additional help, join our [Discord](https://discord.gg/roocode). \ No newline at end of file diff --git a/docs/troubleshooting/shell-integration.md b/docs/troubleshooting/shell-integration.md deleted file mode 100644 index 35422ac3..00000000 --- a/docs/troubleshooting/shell-integration.md +++ /dev/null @@ -1,443 +0,0 @@ -# Terminal Shell Integration - -## What is Shell Integration? - -Shell integration is a [new feature in VSCode 1.93](https://code.visualstudio.com/updates/v1_93#_terminal-shell-integration-api) that allows extensions like Roo Code to run commands in your terminal and read their output. Command output allows Roo Code to react to the result of the command on its own, without you having to handhold by copy-pasting the output in yourself. It's also quite powerful when running development servers as it allows Roo Code to fix errors as the server logs them. - -## Getting Started with Shell Integration - -If you're seeing "Shell Integration Unavailable" messages or Roo Code can't see command output, follow these quick steps: - -### For All Users - -1. **Update VSCode/Cursor** to the latest version -2. **Select a supported shell**: Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) → "Terminal: Select Default Profile" → Choose bash, zsh, PowerShell, or fish - -### For Windows Users - -**PowerShell users**: Set execution policy to RemoteSigned: - ```powershell - Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - ``` -Then **Restart VSCode completely** - -### For WSL Users - -1. **Running VSCode From _Inside_ WSL**: Run `code .` or `code-insiders .` from your WSL terminal -2. **Running VSCode From Windows with WSL Terminal**: Install WSL extension and add to your `~/.bashrc`: - ```bash - . "$(code --locate-shell-integration-path bash)" - ``` -or - ```bash - . "$(code-insiders --locate-shell-integration-path bash)" - ``` - -Notice: if you have a very large `.bash_profile` or `.bashrc` then you might want to put the code/code-insiders script sourcing toward the top so that shell integration does not time out. - -If you're still having issues after these steps, see the detailed troubleshooting sections below. - - -## How Shell Integration Works - -Shell integration uses special terminal sequences (like ANSI escape codes) to mark different stages of command execution in your terminal. Here's how it works: - -1. **Activation**: When you open a terminal in VSCode, your shell sends an activation sequence (`\x1b]633;A\x07`) to initialize shell integration. - -2. **Command Lifecycle**: VSCode shell integration uses OSC (Operating System Command) sequence 633 to track each command's lifecycle: - - OSC 633 ; A - Mark prompt start - - OSC 633 ; B - Mark command start - - OSC 633 ; C - Mark command executed (pre-output) - - OSC 633 ; D [; ``] - Mark command finished with optional exit code - - OSC 633 ; E ; `` [; ``] - Explicitly set command line with optional nonce - - OSC 633 ; P ; `=` - Set properties like current working directory - -3. **Shell Integration Hooks**: Each shell uses specific hooks for different stages of command execution: - - - Bash: - * Initial activation: `PROMPT_COMMAND` (sets up initial environment) - * Command start: `trap DEBUG` (triggers before command execution) - * Command stop: `PROMPT_COMMAND` (triggers after command completion) - - - Zsh: - * Initial activation: `precmd` (sets up initial environment) - * Command start: `preexec` (triggers before command execution) - * Command stop: `precmd` (triggers after command completion) - - - PowerShell: - * Initial activation: `prompt` function (sets up initial environment) - * Command input: `PSConsoleHostReadLine` (captures command input) - * Command start/stop: `prompt` function (handles both command start and completion) - - - Fish: - * Initial activation: `fish_prompt` (sets up initial environment) - * Command start: `fish_preexec` (triggers before command execution) - * Command stop: `fish_prompt` (triggers after command completion) - -> **Note:** This hook implementation information was discovered through AI inspection of the VSCode source tree. If you find any inaccuracies, please submit a pull request with corrections. - -These hooks emit OSC (Operating System Command) sequences that VSCode recognizes to track: - - Prompt start/end positions - - Command start/execution/finish events - - Current working directory changes - - Command line content and execution status - -4. **Output Capture**: When a command runs, VSCode captures: - - Command text and working directory - - Start and end times - - Exit codes - - Output streams (stdout/stderr) - -This allows VSCode and extensions like Roo Code to: -- Know exactly when commands start and finish -- Capture command output reliably -- Track command success/failure -- Update the terminal UI with command status -- React to command results automatically -- Track the current working directory - -## How to Fix "Shell Integration Unavailable" - -### Step 1: Update VSCode or Cursor - -First, make sure you're using the latest version of VSCode or Cursor: - -1. Open VSCode or Cursor -2. Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux) -3. Type "Check for Updates" (VSCode) or "Attempt Update" (Cursor) and select it -4. Restart VSCode/Cursor after the update - -### Step 2: Configure VSCode to Use the Correct Shell - -1. Open VSCode -2. Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux) -3. Type "Terminal: Select Default Profile" and choose it -4. Select one of the supported shells: zsh, bash, fish, or PowerShell. - -### Step 3: Configure PowerShell Execution Policy (Windows) - -Windows users **must** configure PowerShell execution policy before shell integration will work. Follow the instructions in the [Understanding PowerShell Execution Policies](#understanding-powershell-execution-policies) section to set up `RemoteSigned` policy, or another policy that works for you and meets your security requirements. - -### Step 4: Restart VSCode - -After making these changes: - -1. Quit VSCode completely -2. Reopen VSCode -3. Start a new Roo Code session (you can resume your previous task and try to run the command again, this time with Roo Code being able to see the output) - -## Additional Troubleshooting for Windows Users - -If you're using Windows and still experiencing issues with shell integration after trying the previous steps, it's recommended you use Git Bash. - -### Git Bash - -Git Bash is a terminal emulator that provides a Unix-like command line experience on Windows. To use Git Bash, you need to: - -1. Download and run the Git for Windows installer from [https://git-scm.com/downloads/win](https://git-scm.com/downloads/win) -2. Quit and re-open VSCode -3. Press `Ctrl + Shift + P` to open the Command Palette -4. Type "Terminal: Select Default Profile" and choose it -5. Select "Git Bash" - -### PowerShell - -If you'd still like to use PowerShell, make sure you're using an updated version (at least v7+). - - Check your current PowerShell version by running: `$PSVersionTable.PSVersion` - - If your version is below 7, [update PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/whats-new/migrating-from-windows-powershell-51-to-powershell-7?view=powershell-7.4#installing-powershell-7). - -#### Understanding PowerShell Execution Policies - -PowerShell uses execution policies to determine which scripts can run on your system. Here are the most common policies: - -- `Restricted`: No PowerShell scripts can run. This is the default setting. -- `AllSigned`: All scripts, including local ones, must be signed by a trusted publisher. -- `RemoteSigned`: Scripts created locally can run, but scripts downloaded from the internet must be signed. -- `Unrestricted`: No restrictions. Any script can run, though you will be warned before running internet-downloaded scripts. - -For development work in VSCode, the `RemoteSigned` policy is generally recommended. It allows locally created scripts to run without restrictions while maintaining security for downloaded scripts. To learn more about PowerShell execution policies and understand the security implications of changing them, visit Microsoft's documentation: [About Execution Policies](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies). - -#### Steps to Change the Execution Policy - -1. Open PowerShell as an Administrator: Press `Win + X` and select "Windows PowerShell (Administrator)" or "Windows Terminal (Administrator)". - -2. Check Current Execution Policy by running this command: - ```powershell - Get-ExecutionPolicy - ``` - - If the output is already `RemoteSigned`, `Unrestricted`, or `Bypass`, you likely don't need to change your execution policy. These policies should allow shell integration to work. - - If the output is `Restricted` or `AllSigned`, you may need to change your policy to enable shell integration. - -3. Change the Execution Policy by running the following command: - ```powershell - Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - ``` - - This sets the policy to `RemoteSigned` for the current user only, which is safer than changing it system-wide. - -4. Confirm the Change by typing `Y` and pressing Enter when prompted. - -5. Verify the Policy Change by running `Get-ExecutionPolicy` again to confirm the new setting. - -6. Restart VSCode and try the shell integration again. - -## Manual Shell Integration Installation - -If you're still experiencing issues after trying the basic troubleshooting steps, you can try manually installing shell integration: - -### Installation Instructions - -For Bash users: -1. Run `code ~/.bashrc` in the terminal to open your bash configuration file. -2. Add the following line to your `~/.bashrc`: -```bash -[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)" -``` - -For Zsh users: -1. Run `code ~/.zshrc` in the terminal to open your zsh configuration file. -2. Add the following line to your `~/.zshrc`: -```bash -[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)" -``` - -For PowerShell users: -1. Run `code $Profile` in the terminal to open your PowerShell profile. -2. Add the following line to the file: -```powershell -if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" } -``` - -For Fish users: -1. Run `code ~/.config/fish/config.fish` in the terminal to open your fish configuration file. -2. Add the following line to your `~/.config/fish/config.fish`: -```fish -string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish) -``` - -### About the Shell Integration Path Command - -The `code --locate-shell-integration-path` command returns the path to shell-specific integration scripts. It supports four shell types: -- bash - returns path to `shellIntegration-bash.sh` -- zsh - returns path to `shellIntegration-rc.zsh` -- pwsh - returns path to `shellIntegration.ps1` -- fish - returns path to `shellIntegration.fish` - -Any other value will throw an error: "Error using `--locate-shell-integration-path`: Invalid shell type". - -## Unusual Terminal Output - -If you're seeing unusual output with rectangles, lines, escape sequences, or control characters, it may be related to terminal customization tools. Common culprits include: - -- Powerlevel10k: A zsh theme that adds visual elements to the prompt. If using Powerlevel10k, you must set `typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true` in your `~/.zshrc` before sourcing the theme. This enables proper integration with VSCode's shell integration, which differs from the integration provided by VSCE. -- Oh My Zsh: A framework for managing zsh configurations -- Fish shell themes - -To troubleshoot: - -1. For Powerlevel10k users: - ```bash - # Add this line before sourcing powerlevel10k in ~/.zshrc - typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true - ``` - -2. If issues persist, temporarily disable these tools in your shell configuration file (e.g., `~/.zshrc` for Zsh) -3. If the issue resolves, gradually re-enable features to identify the conflicting component - -## Advanced Troubleshooting - -### Shell Integration Not Available - -Shell integration activation sequence (`\x1b]633;A\x07`) was not received. Shell integration features are disabled. Verify you are using a supported shell (Bash, Zsh, PowerShell, Fish) and shell integration is enabled in settings. - -### Command Stream Not Available - -Command stream failed: missing start sequence (`\x1b]633;C\x07`) or command already ended (`\x1b]633;D\x07`). Command output cannot be captured. Check if the command started correctly or has completed execution. - -### Verifying Shell Integration Status - -Run these commands to verify shell integration sequences are installed: - -#### Bash -```bash -# View all shell integration sequences -set | grep -i '[16]33;' - -# Should show VSCode shell integration functions like: -# printf '\e]633;E;%s;%s\a' - Command line set -# printf '\e]633;C\a' - Command executed -# printf '\e]633;D\a' - Command finished -# printf '\e]633;B\a' - Command start -# printf '\e]633;A\a' - Shell integration activated -# printf '\e]633;P;Prompt=%s\a' - Prompt marker - -# Check for PROMPT_COMMAND and DEBUG trap -echo "$PROMPT_COMMAND" | grep vsc -trap -p DEBUG | grep vsc -``` - -#### Zsh -```zsh -# List all VSCode shell integration functions -functions | grep -i vsc # Should show __vsc_precmd, __vsc_preexec, etc. - -# Verify shell integration hooks are installed -typeset -p precmd_functions preexec_functions # Should include __vsc_precmd and __vsc_preexec - -# Check Powerlevel10k integration (if installed) -(( ${+functions[p10k]} )) && typeset -p POWERLEVEL9K_TERM_SHELL_INTEGRATION # Should show "true" -``` - -#### PowerShell -```powershell -# View shell integration functions -Get-Command -Name "*VSC*" -CommandType Function - -# Check prompt function -Get-Content Function:\Prompt | Select-String "VSCode" -``` - -#### Fish -```fish -# Check for shell integration functions -functions | grep -i vsc - -# Verify fish_prompt and fish_preexec hooks -functions fish_prompt | grep -i vsc -functions fish_preexec | grep -i vsc -``` - -Visual indicators of active shell integration: -1. Shell integration indicator in terminal title bar -2. Command detection highlighting -3. Working directory updates in terminal title -4. Command duration reporting -5. Exit code reporting for failed commands - -## Troubleshooting Terminal Execution Failures - -If commands that previously worked suddenly stop working: -1. Close the current terminal -2. Let Roo Code open a new terminal for you -3. Try your command again - -This often resolves temporary shell integration issues. However, if you experience persistent terminal execution failures and can reliably reproduce the problem, please [open a ticket](https://github.com/RooVetGit/Roo-Code/issues/new) with: -- A step-by-step reproduction of the problem -- Your operating system and VSCode/Cursor version -- The shell you're using (Bash, Zsh, PowerShell, Fish) -- Any relevant error messages or terminal output - -This will help us investigate and fix the underlying issue. - -## Known Upstream VSCode Shell Integration Issues - -See also: https://github.com/microsoft/vscode/issues/237208 - -### Ctrl+C Behavior Breaking Command Capture - -When shell integration believes there is a command that should be cancelled before running the requested command, the `^C` behavior breaks capture of the subsequent command output. Only `\x1B]633;C\x07` is received, with no actual command output. - -To reproduce: -1. Run any command -2. Type text in terminal (making shell integration think `^C` is needed) -3. Run another command - output will not be captured - -Example: -``` -~]$ echo a # first command works -a -~]$ ^C -~]$ echo a -a -``` - -The second `echo a` command produces no output in shell integration (only `\x1B]633;C\x07` is received) even though the terminal shows the output. - -**Work-around to avoid this issue:** Always ensure your terminal prompt is clean (no partial commands or text) before letting Roo run commands. This prevents shell integration from thinking it needs to send a Ctrl+C. - - -### Multi-line Command Output Issues - -Multi-line commands can produce unexpected behavior with shell integration escape codes: - -1. First command execution works correctly -2. Second execution produces phantom/partial output from previous command -3. Terminal displays spurious text unrelated to actual command output - -This occurs with: -- Commands preceded by comments -- Invalid commands followed by valid ones -- Multiple valid commands in sequence - -The issue appears when two non-empty lines are passed to shell integration. - -If your AI model attempt to execute following two-line command: - -```sh -# Get information about the commit -echo "Commit where version change was detected:" -``` - -it will produce phantom output: - -``` -]$ # Get information about the commit -hange was detected:" -]$ echo "Commit where version change was detected:" -Commit where version change was detected: -``` - -The second invocation shows phantom text `hange was detected:"` that was not part of the actual command output. - -**Work-around:** If your model attempts this make sure you provide system instructions to ensure that it does not split commands across multiple lines, command should be chained like `echo a && echo b` and not as: -```sh -echo a -echo b # because this one will not provide output. -``` - -### Incomplete Terminal Output - -There is an ongoing issue in VSCode where terminal command output may not be completely captured by extensions like Roo Code. This can result in: -- Missing portions of command output -- Incomplete error messages -- Delayed or missing command completion signals - -If you experience this issue, try: -1. Closing and reopening the terminal -2. Running the command again -3. If the problem persists, you may need to manually copy-paste relevant output to Roo Code - -### Memory Leak Leading to VSCode Crashes - -There is a potential memory leak in the upstream shell integration that can cause VSCode to crash unexpectedly. When this occurs, VSCode and all related windows will close completely without warning. - -**Work-around:** there is no known workaround, but I do not hit this problem until gigabytes of terminal output, so it may not affect you. - -### PowerShell Command Output Issues - -PowerShell in Windows environments has two critical command execution issues: -1. Output buffering: PowerShell may emit the ]633;D completion marker before command output is fully processed by VSCE, resulting in missing or truncated output -2. Duplicate command bug: PowerShell fails to execute identical subsequent commands, treating them as duplicates even when they should run independently - -These issues affect command execution reliability in Windows environments using PowerShell. - -**Work-around:** Roo Code automatically handles both issues when [PR #1585](https://github.com/RooVetGit/Roo-Code/pull/1585) is merged by: -- Adding a 150ms delay after command execution to ensure output capture -- Appending a unique counter to each command to prevent duplicate command issues - -See [#1585](https://github.com/RooVetGit/Roo-Code/pull/1585) for implementation details. - -## Troubleshooting Resources - -- [VSCode Terminal Output Issue #237208](https://github.com/microsoft/vscode/issues/237208): Tracking the incomplete terminal output capture issue (ongoing as of March 8, 2025) -- [VSCode Terminal Integration Test Repository](https://github.com/KJ7LNW/vsce-test-terminal-integration): A tool for validating shell integration functionality in your environment -- [Shell Integration Improvements PR](https://github.com/cline/cline/pull/1089): Enhanced shell integration behavior (merged in Roo Code as of March 8, 2025, pending merge in Cline) -- [Roo Code Shell Integration Architecture PR](https://github.com/RooVetGit/Roo-Code/pull/1365): Detailed discussion and proposed architectural changes for more reliable shell integration (pending as of March 8, 2025) - -## Support - -If you've followed these steps and are still experiencing problems, please: - -1. Check the [Roo Code GitHub Issues](https://github.com/RooVetGit/Roo-Code/issues) to see if others have reported similar problems -2. If not, create a new issue with details about your operating system, VSCode/Cursor version, and the steps you've tried - -For additional help, join our [Discord](https://discord.gg/roocode). diff --git a/docs/update-notes/index.md b/docs/update-notes/index.md index dadf00fd..82ca344b 100644 --- a/docs/update-notes/index.md +++ b/docs/update-notes/index.md @@ -4,9 +4,12 @@ This section contains notes about recent updates to Roo Code, listed by version ## Version 3.11 +* [3.11.13](/update-notes/v3.11.13) (2025-04-11) +* [3.11.12](/update-notes/v3.11.12) (2025-04-09) +* [3.11.11](/update-notes/v3.11.11) (2025-04-09) * [3.11.10](/update-notes/v3.11.10) (2025-04-08) * [3.11.9](/update-notes/v3.11.9) (2025-04-07) -* [3.11.8](/update-notes/v3.11.8) (2025-04-08) +* [3.11.8](/update-notes/v3.11.8) (2025-04-05) * [3.11.7](/update-notes/v3.11.7) (2025-04-04) * [3.11.6](/update-notes/v3.11.6) (2025-04-04) * [3.11.5](/update-notes/v3.11.5) (2025-04-03) diff --git a/docs/update-notes/v3.11.11.md b/docs/update-notes/v3.11.11.md new file mode 100644 index 00000000..9f602c25 --- /dev/null +++ b/docs/update-notes/v3.11.11.md @@ -0,0 +1,21 @@ +# Roo Code 3.11.11 Release Notes (2025-04-09) + +This release includes fixes for UI interactions, improved OpenAI-compatible provider options, parser updates, and other enhancements. + +## Bug Fixes + +* Fix highlighting interaction with mode/profile dropdowns (thanks atlasgong!) +* Fixes to terminal working directory logic (thanks KJ7LNW!) + +## Improvements + +* Add the ability to set Host header and legacy OpenAI API in the OpenAI-compatible provider for better proxy support +* Improvements to TypeScript, C++, Go, Java, Python tree-sitter parsers (thanks KJ7LNW!) +* Improve `readFileTool` XML output format (thanks KJ7LNW!) +* Follow symlinked rules files/directories to allow for more flexible rule setups +* Focus Roo Code in the sidebar when running tasks in the sidebar via the API +* Improve subtasks UI + +## Provider Updates + +* Add o1-pro support (thanks arthurauffray!) \ No newline at end of file diff --git a/docs/update-notes/v3.11.12.md b/docs/update-notes/v3.11.12.md new file mode 100644 index 00000000..1e5c99cc --- /dev/null +++ b/docs/update-notes/v3.11.12.md @@ -0,0 +1,11 @@ +# Roo Code 3.11.12 Release Notes (2025-04-09) + +This release enables Grok3 streaming via OpenAI Compatible providers and improves diff editing tolerance. + +## Provider Updates + +* Make Grok3 streaming work with OpenAI Compatible (thanks amittell!) + +## Improvements + +* Tweak diff editing logic to make it more tolerant of model errors \ No newline at end of file diff --git a/docs/update-notes/v3.11.13.md b/docs/update-notes/v3.11.13.md new file mode 100644 index 00000000..42487da3 --- /dev/null +++ b/docs/update-notes/v3.11.13.md @@ -0,0 +1,36 @@ +# Roo Code 3.11.13 Release Notes (2025-04-11) + +This release includes several terminal enhancements, improved diff error display, file context tracking, and various fixes. + +## New Terminal Settings (thanks KJ7LNW!) + +Six new configurable settings were added to improve terminal reliability: + +* **Terminal command delay setting** - Adds a small pause after running commands to fix output capture issues in some terminals. Useful if Roo has trouble seeing command results. +* **PowerShell counter workaround setting** - Helps PowerShell run identical commands multiple times without failing. Turn this on if Roo struggles with repeated commands. +* **Clear ZSH EOL mark setting** - Prevents ZSH from adding special characters that can confuse Roo when reading terminal output. +* **Oh My Zsh integration setting** - Makes Roo work better with the popular Oh My Zsh shell customization framework. (experimental) +* **Powerlevel10k integration setting** - Improves compatibility with the Powerlevel10k ZSH theme. (experimental) +* **ZDOTDIR handling setting** - Helps Roo work with custom ZSH configurations without interfering with your personal settings. (experimental) + +For detailed information about these settings and shell integration troubleshooting, see [Terminal Shell Integration](/features/shell-integration). + +Terminal enhancements settings panel showing command delay, PowerShell counter, and ZSH options + +## Diff Error Display Improvements + +Improved diff error display interface with copy mechanism + +* Enhanced visibility of diff errors +* Added easy copying mechanism for error details + +## Improvements + +* Added file context tracking system so Roo better remembers which files you're working with (thanks samhvw8 and canvrno!) +* Renamed AWS Bedrock to Amazon Bedrock for consistency with official naming (thanks ronyblum!) +* Updated extension title and description for clarity (thanks StevenTCramer!) + +## Bug Fixes + +* - Fixes to .vscodeignore (thanks @franekp!) +* Fixed Chinese (zh-CN) translation for model capabilities (thanks zhangtony239!) \ No newline at end of file diff --git a/docs/update-notes/v3.11.8.md b/docs/update-notes/v3.11.8.md index 9a1e0f79..9ac2a706 100644 --- a/docs/update-notes/v3.11.8.md +++ b/docs/update-notes/v3.11.8.md @@ -1,4 +1,4 @@ -# Roo Code 3.11.8 Release Notes (2025-04-08) +# Roo Code 3.11.8 Release Notes (2025-04-05) This patch release includes performance improvements and UI updates. diff --git a/docs/update-notes/v3.11.md b/docs/update-notes/v3.11.md index e42e1920..59482c17 100644 --- a/docs/update-notes/v3.11.md +++ b/docs/update-notes/v3.11.md @@ -1,4 +1,4 @@ -# Roo Code 3.11 Release Notes (2025-04-08) +# Roo Code 3.11 Release Notes (2025-03-30) This update focuses on performance enhancements, improved provider integration, and usability refinements based on community feedback. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9440483d..f758618c 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -152,6 +152,10 @@ const config: Config = { to: '/features/mcp/mcp-vs-api', from: ['/mcp/mcp-vs-api'], }, + { + to: '/features/shell-integration', + from: ['/troubleshooting/shell-integration'], + }, ], }, ], diff --git a/sidebars.ts b/sidebars.ts index b9d169dd..42ab9297 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -36,6 +36,7 @@ const sidebars: SidebarsConfig = { 'features/model-temperature', 'features/settings-management', 'features/suggested-responses', + 'features/shell-integration', { type: 'category', label: 'Tool Use', @@ -79,7 +80,7 @@ const sidebars: SidebarsConfig = { 'features/experimental/experimental-features', ], }, - 'features/more-features' + 'features/more-features', ], }, { @@ -129,13 +130,6 @@ const sidebars: SidebarsConfig = { 'community', ], }, - { - type: 'category', - label: 'Troubleshooting', - items: [ - 'troubleshooting/shell-integration', - ], - }, { type: 'category', label: 'Update Notes', @@ -145,6 +139,9 @@ const sidebars: SidebarsConfig = { type: 'category', label: '3.11', items: [ + { type: 'doc', id: 'update-notes/v3.11.13', label: '3.11.13' }, + { type: 'doc', id: 'update-notes/v3.11.12', label: '3.11.12' }, + { type: 'doc', id: 'update-notes/v3.11.11', label: '3.11.11' }, { type: 'doc', id: 'update-notes/v3.11.10', label: '3.11.10' }, { type: 'doc', id: 'update-notes/v3.11.9', label: '3.11.9' }, { type: 'doc', id: 'update-notes/v3.11.8', label: '3.11.8' }, diff --git a/static/img/shell-integration/shell-integration-1.png b/static/img/shell-integration/shell-integration-1.png new file mode 100644 index 00000000..d089be39 Binary files /dev/null and b/static/img/shell-integration/shell-integration-1.png differ diff --git a/static/img/shell-integration/shell-integration-2.png b/static/img/shell-integration/shell-integration-2.png new file mode 100644 index 00000000..e55a5116 Binary files /dev/null and b/static/img/shell-integration/shell-integration-2.png differ diff --git a/static/img/shell-integration/shell-integration-3.png b/static/img/shell-integration/shell-integration-3.png new file mode 100644 index 00000000..24c8532a Binary files /dev/null and b/static/img/shell-integration/shell-integration-3.png differ diff --git a/static/img/shell-integration/shell-integration-4.png b/static/img/shell-integration/shell-integration-4.png new file mode 100644 index 00000000..6faa30e5 Binary files /dev/null and b/static/img/shell-integration/shell-integration-4.png differ diff --git a/static/img/shell-integration/shell-integration-5.png b/static/img/shell-integration/shell-integration-5.png new file mode 100644 index 00000000..f80ba0dc Binary files /dev/null and b/static/img/shell-integration/shell-integration-5.png differ diff --git a/static/img/shell-integration/shell-integration-6.png b/static/img/shell-integration/shell-integration-6.png new file mode 100644 index 00000000..c9e34f0b Binary files /dev/null and b/static/img/shell-integration/shell-integration-6.png differ diff --git a/static/img/shell-integration/shell-integration-7.png b/static/img/shell-integration/shell-integration-7.png new file mode 100644 index 00000000..3011004e Binary files /dev/null and b/static/img/shell-integration/shell-integration-7.png differ diff --git a/static/img/shell-integration/shell-integration.png b/static/img/shell-integration/shell-integration.png new file mode 100644 index 00000000..87749d1a Binary files /dev/null and b/static/img/shell-integration/shell-integration.png differ diff --git a/static/img/v3.11.13/v3.11.13-1.png b/static/img/v3.11.13/v3.11.13-1.png new file mode 100644 index 00000000..27bb8e46 Binary files /dev/null and b/static/img/v3.11.13/v3.11.13-1.png differ diff --git a/static/img/v3.11.13/v3.11.13.png b/static/img/v3.11.13/v3.11.13.png new file mode 100644 index 00000000..631a95d1 Binary files /dev/null and b/static/img/v3.11.13/v3.11.13.png differ