|
| 1 | +# Terminal Shell Integration |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## What is Shell Integration? |
| 6 | + |
| 7 | +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: |
| 8 | + |
| 9 | +- Execute commands on your behalf through the [`execute_command`](/features/tools/execute-command) tool |
| 10 | +- Read command output in real-time without manual copy-pasting |
| 11 | +- Automatically detect and fix errors in running applications |
| 12 | +- Observe command exit codes to determine success or failure |
| 13 | +- Track working directory changes as you navigate your project |
| 14 | +- React intelligently to terminal output without user intervention |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +## Troubleshooting Shell Integration |
| 19 | + |
| 20 | +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: |
| 21 | + |
| 22 | +1. **Update VSCode/Cursor** to the latest version (VSCode 1.93+ required) |
| 23 | +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 |
| 24 | +3. **Windows PowerShell users**: Run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` then restart VSCode |
| 25 | +4. **WSL users**: Add `. "$(code --locate-shell-integration-path bash)"` to your `~/.bashrc` |
| 26 | + |
| 27 | +## Terminal Integration Settings |
| 28 | + |
| 29 | +Roo Code provides several settings to fine-tune shell integration. Access these in the Roo Code sidebar under Settings → Terminal. |
| 30 | + |
| 31 | +### Basic Settings |
| 32 | + |
| 33 | +#### Terminal Output Limit |
| 34 | +<img src="/img/shell-integration/shell-integration.png" alt="Terminal output limit slider set to 500" width="600" /> |
| 35 | + |
| 36 | +Controls the maximum number of lines captured from terminal output. When exceeded, lines are removed from the middle to save tokens. Default: 500 lines. |
| 37 | + |
| 38 | +#### Terminal Shell Integration Timeout |
| 39 | +<img src="/img/shell-integration/shell-integration-1.png" alt="Terminal shell integration timeout slider set to 15s" width="600" /> |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +#### Terminal Command Delay |
| 44 | +<img src="/img/shell-integration/shell-integration-2.png" alt="Terminal command delay slider set to 0ms" width="600" /> |
| 45 | + |
| 46 | +Adds a delay after command execution to ensure full output capture. Implemented using `PROMPT_COMMAND='sleep N'` in bash/zsh or `start-sleep` in PowerShell. Originally a workaround for VSCode bug #237208, may not be needed on most systems. Default: 0ms (disabled). |
| 47 | + |
| 48 | +### Advanced Settings |
| 49 | + |
| 50 | +#### PowerShell Counter Workaround |
| 51 | +<img src="/img/shell-integration/shell-integration-3.png" alt="PowerShell counter workaround checkbox" width="600" /> |
| 52 | + |
| 53 | +Appends a unique counter to PowerShell commands to prevent duplicate command issues. Enable this if PowerShell fails to execute identical consecutive commands. |
| 54 | + |
| 55 | +#### Clear ZSH EOL Mark |
| 56 | +<img src="/img/shell-integration/shell-integration-4.png" alt="Clear ZSH EOL mark checkbox" width="600" /> |
| 57 | + |
| 58 | +Sets `PROMPT_EOL_MARK=""` to clear ZSH end-of-line marks, preventing issues with command output when output ends with special characters like '%'. |
| 59 | + |
| 60 | +#### Oh My Zsh Integration |
| 61 | +<img src="/img/shell-integration/shell-integration-5.png" alt="Enable Oh My Zsh integration checkbox" width="600" /> |
| 62 | + |
| 63 | +Sets `ITERM_SHELL_INTEGRATION_INSTALLED="Yes"` to enable proper integration with Oh My Zsh. Experimental feature for users of Oh My Zsh. |
| 64 | + |
| 65 | +#### Powerlevel10k Integration |
| 66 | +<img src="/img/shell-integration/shell-integration-6.png" alt="Enable Powerlevel10k integration checkbox" width="600" /> |
| 67 | + |
| 68 | +Sets `POWERLEVEL9K_TERM_SHELL_INTEGRATION=true` to enable proper integration with the Powerlevel10k ZSH theme. |
| 69 | + |
| 70 | +#### ZDOTDIR Handling |
| 71 | +<img src="/img/shell-integration/shell-integration-7.png" alt="Enable ZDOTDIR handling checkbox" width="600" /> |
| 72 | + |
| 73 | +Creates a temporary directory for ZDOTDIR to handle ZSH shell integration properly while preserving your ZSH configuration. |
| 74 | + |
| 75 | +## How Shell Integration Works |
| 76 | + |
| 77 | +Shell integration uses terminal sequences to mark different stages of command execution: |
| 78 | + |
| 79 | +1. **Activation**: When you open a terminal, your shell sends an activation sequence (`\x1b]633;A\x07`). |
| 80 | + |
| 81 | +2. **Command Lifecycle**: VSCode tracks each command using Operating System Command (OSC) sequences: |
| 82 | + - OSC 633;A - Mark prompt start |
| 83 | + - OSC 633;B - Mark command start |
| 84 | + - OSC 633;C - Mark command executed |
| 85 | + - OSC 633;D - Mark command finished with exit code |
| 86 | + - OSC 633;E - Set command line |
| 87 | + - OSC 633;P - Set properties like current working directory |
| 88 | + |
| 89 | +3. **Shell-Specific Implementation**: |
| 90 | + |
| 91 | + | Shell | Initial Activation | Command Start | Command Stop | |
| 92 | + |-------|-------------------|---------------|--------------| |
| 93 | + | Bash | `PROMPT_COMMAND` | `trap DEBUG` | `PROMPT_COMMAND` | |
| 94 | + | Zsh | `precmd` | `preexec` | `precmd` | |
| 95 | + | PowerShell | `prompt` function | `PSConsoleHostReadLine` | `prompt` function | |
| 96 | + | Fish | `fish_prompt` | `fish_preexec` | `fish_prompt` | |
| 97 | + |
| 98 | +4. **Output Capture**: Roo Code captures command text, working directory, start/end times, exit codes, and output streams. |
| 99 | + |
| 100 | +## Troubleshooting Shell Integration |
| 101 | + |
| 102 | +### PowerShell Execution Policy (Windows) |
| 103 | + |
| 104 | +PowerShell restricts script execution by default. To configure: |
| 105 | + |
| 106 | +1. Open PowerShell as Administrator |
| 107 | +2. Check current policy: `Get-ExecutionPolicy` |
| 108 | +3. Set appropriate policy: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| 109 | + |
| 110 | +Common policies: |
| 111 | +- `Restricted`: No scripts allowed (default) |
| 112 | +- `RemoteSigned`: Local scripts can run; downloaded scripts need signing |
| 113 | +- `Unrestricted`: All scripts run with warnings |
| 114 | +- `AllSigned`: All scripts must be signed |
| 115 | + |
| 116 | +### Manual Shell Integration Installation |
| 117 | + |
| 118 | +If automatic integration fails, add the appropriate line to your shell configuration: |
| 119 | + |
| 120 | +**Bash** (`~/.bashrc`): |
| 121 | +```bash |
| 122 | +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)" |
| 123 | +``` |
| 124 | + |
| 125 | +**Zsh** (`~/.zshrc`): |
| 126 | +```bash |
| 127 | +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)" |
| 128 | +``` |
| 129 | + |
| 130 | +**PowerShell** (`$Profile`): |
| 131 | +```powershell |
| 132 | +if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" } |
| 133 | +``` |
| 134 | + |
| 135 | +**Fish** (`~/.config/fish/config.fish`): |
| 136 | +```fish |
| 137 | +string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish) |
| 138 | +``` |
| 139 | + |
| 140 | +### Terminal Customization Issues |
| 141 | + |
| 142 | +If you use terminal customization tools: |
| 143 | + |
| 144 | +**Powerlevel10k**: |
| 145 | +```bash |
| 146 | +# Add before sourcing powerlevel10k in ~/.zshrc |
| 147 | +typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true |
| 148 | +``` |
| 149 | + |
| 150 | +**Alternative**: Enable the Powerlevel10k Integration setting in Roo Code. |
| 151 | + |
| 152 | +### Verifying Shell Integration Status |
| 153 | + |
| 154 | +Confirm shell integration is active with these commands: |
| 155 | + |
| 156 | +**Bash**: |
| 157 | +```bash |
| 158 | +set | grep -i '[16]33;' |
| 159 | +echo "$PROMPT_COMMAND" | grep vsc |
| 160 | +trap -p DEBUG | grep vsc |
| 161 | +``` |
| 162 | + |
| 163 | +**Zsh**: |
| 164 | +```zsh |
| 165 | +functions | grep -i vsc |
| 166 | +typeset -p precmd_functions preexec_functions |
| 167 | +``` |
| 168 | + |
| 169 | +**PowerShell**: |
| 170 | +```powershell |
| 171 | +Get-Command -Name "*VSC*" -CommandType Function |
| 172 | +Get-Content Function:\Prompt | Select-String "VSCode" |
| 173 | +``` |
| 174 | + |
| 175 | +**Fish**: |
| 176 | +```fish |
| 177 | +functions | grep -i vsc |
| 178 | +functions fish_prompt | grep -i vsc |
| 179 | +``` |
| 180 | + |
| 181 | +Visual indicators of active shell integration: |
| 182 | +1. Shell integration indicator in terminal title bar |
| 183 | +2. Command detection highlighting |
| 184 | +3. Working directory updates in terminal title |
| 185 | +4. Command duration and exit code reporting |
| 186 | + |
| 187 | +## Known Issues and Workarounds |
| 188 | + |
| 189 | +### Ctrl+C Behavior |
| 190 | + |
| 191 | +**Issue**: If text is in the terminal when Roo runs a command, shell integration sends Ctrl+C first, breaking output capture. |
| 192 | + |
| 193 | +**Workaround**: Ensure terminal prompt is clean before letting Roo run commands. |
| 194 | + |
| 195 | +### Multi-line Command Issues |
| 196 | + |
| 197 | +**Issue**: Multi-line commands produce unexpected behavior with phantom output from previous commands. |
| 198 | + |
| 199 | +**Workaround**: Use command chaining with `&&` instead of multiple lines (e.g., `echo a && echo b`). |
| 200 | + |
| 201 | +### PowerShell-Specific Issues |
| 202 | + |
| 203 | +1. **Output Buffering**: PowerShell may emit completion markers before output is fully processed. |
| 204 | +2. **Duplicate Commands**: PowerShell fails to execute identical consecutive commands. |
| 205 | + |
| 206 | +**Workaround**: Enable the "PowerShell counter workaround" setting and set a terminal command delay of 150ms. |
| 207 | + |
| 208 | +### Incomplete Terminal Output |
| 209 | + |
| 210 | +**Issue**: VSCode may not capture complete command output. |
| 211 | + |
| 212 | +**Workaround**: Close and reopen the terminal, then run the command again. |
| 213 | + |
| 214 | +## Troubleshooting Resources |
| 215 | + |
| 216 | +- [VSCode Terminal Output Issue #237208](https://github.com/microsoft/vscode/issues/237208) |
| 217 | +- [VSCode Terminal Integration Test Repository](https://github.com/KJ7LNW/vsce-test-terminal-integration) |
| 218 | +- [Roo Code Shell Integration Architecture PR](https://github.com/RooVetGit/Roo-Code/pull/1365) |
| 219 | + |
| 220 | +## Support |
| 221 | + |
| 222 | +If you're still having issues: |
| 223 | + |
| 224 | +1. Check [Roo Code GitHub Issues](https://github.com/RooVetGit/Roo-Code/issues) |
| 225 | +2. Create a new issue with: |
| 226 | + - OS and VSCode version |
| 227 | + - Shell type |
| 228 | + - Steps to reproduce |
| 229 | + - Error messages |
| 230 | + |
| 231 | +For additional help, join our [Discord](https://discord.gg/roocode). |
0 commit comments