description

Learn how Roo Code integrates with your shell to execute commands. Troubleshooting guide for terminal issues and shell configuration.

keywords

shell integration

terminal commands

command execution

shell configuration

troubleshooting

import Codicon from '@site/src/components/Codicon';

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 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
Stop running commands directly from the chat interface using the stop button that appears next to the command execution message.

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.

Terminal Integration Settings

Roo Code provides settings to fine-tune how it interacts with terminals. To access these settings:

Click the icon in the top-right corner of the Roo Code sidebar.
In the settings pane that opens, select the "Terminal" group from the left-hand menu.

Basic Settings

Terminal Output Limit

Truncates by lines. Roo keeps the beginning and end and drops the middle with an "[...N lines omitted...]" marker to stay under the limit. Mechanism: keeps approximately 20% of the head and 80% of the tail of the allowed line budget and inserts an omission marker, preserving a blank line before the tail for readability. Use when commands print many lines (e.g., long logs) and you mostly care about headers and final results. Avoid when important details are in the middle. Default: 500 lines.

Terminal Character Limit

Hard cap on total output size (characters). Roo keeps the beginning and end and omits the middle with an "[...N characters omitted...]" marker. Mechanism: takes precedence over the line limit; keeps ~20% of the head and ~80% of the tail of the character budget, overriding the line limit to prevent memory issues from very long lines. Use when commands print extremely long lines or massive blobs. Avoid when you need the exact full content.

Compress progress bar output

ON: Collapses progress bars/spinners by processing carriage returns (\r) and backspaces (\b) so only the final state is kept, then applies run-length encoding to collapse repeated lines. OFF: Keeps every update exactly as printed. Use when you don’t need intermediate spinner states (recommended ON). Disable only if you’re debugging step-by-step progress behavior.

Advanced Settings

Unless noted, these settings apply only when "Use Inline Terminal (recommended)" is OFF (i.e., using the VS Code terminal).

:::info Important Terminal restart required for these settings

Changes to advanced terminal settings only take effect after restarting your terminals. To restart a terminal:

Click the trash icon in the terminal panel to close the current terminal
Open a new terminal with Terminal → New Terminal or Ctrl+` (backtick)

Always restart all open terminals after changing any of these settings. :::

Use Inline Terminal (recommended)

Controls how Roo Code executes terminal commands.

ON (Use Inline Terminal): Runs commands with the Inline Terminal (in chat), bypassing shell profiles and VS Code shell integration for reliability and faster starts. Mechanism: uses a background “execa” provider and streams output directly (no VS Code OSC 633/133 markers).
*Inline Terminal active (Use Inline Terminal is ON).*
OFF (Use VS Code terminal): Uses the VS Code integrated terminal and your shell profile; may require shell integration and is more likely to hit “Shell Integration Unavailable” issues. Use this only when you specifically need terminal UI features or interactive profile behavior.

Decision guide: Inline Terminal ON vs OFF

Use ON when you want reliability, faster starts, or your shell profile causes issues.
Use OFF when you need terminal UI features or your shell prompt customizations to run.
Tip: If terminal commands fail or stall, switch ON and retry.

:::info Runtime Environment On macOS (and possibly other operating systems) the environment provided to VS Code, and consequently Roo Code, can differ depending on how VS Code is launched.

If launched from the command line with the code command, VS Code and Roo Code inherit the environment from the shell that launched it.

If launched from the Finder, Dock, or Spotlight, environment exported from .zshrc or .zprofile will likely be missing.

If you rely on environment variables from those files and they are missing in VS Code, move them to .zshenv, then log out and back in so the window manager picks up the new settings. :::

The following advanced settings apply only when this is OFF (i.e., when using the VS Code terminal):

Inherit environment variables

VS Code terminal only. Controls whether VS Code integrated terminals inherit environment variables from the parent VS Code process. Mirrors the VS Code setting [`terminal.integrated.inheritEnv`](https://code.visualstudio.com/docs/editor/integrated-terminal#_inherit-environment-variables). Note: Inline Terminal (“Use Inline Terminal (recommended)” ON) runs as a background process and always uses the extension’s Node process environment; this setting doesn’t affect it. Keep enabled (VS Code default) if you rely on PATH/proxy/auth variables provided by VS Code. Disable only for clean, reproducible integrated terminal sessions or when debugging environment conflicts.

Terminal shell integration timeout

How long Roo waits for VS Code shell integration to initialize and for the integration stream to start. If not ready within the timeout, a “no shell integration” event is emitted and execution will fall back to the Inline Terminal when retried. Use when your shell/profile has long startup times or you see “Shell Integration Unavailable” errors. Avoid increasing if you’re using the Inline Terminal (not applicable there). Default: 15s. Applies only when using the VS Code terminal.

Terminal command delay

Adds a small delay after each command to help VS Code terminals flush all output. Mechanism: sets `PROMPT_COMMAND='sleep N'` for bash/zsh and appends `start-sleep -milliseconds N` for PowerShell. Use when you see truncated/missing tail output or prompt races. Avoid when output captures look correct. Set to 0 to disable. Default: 0ms.

Enable PowerShell counter workaround

ON: Appends `; "(Roo/PS Workaround: N)" > $null` to each command to force a reliable post-execution signal and avoid missing or duplicated output on some setups. Use when using Windows PowerShell and output is incomplete or repeats, or when running the same command twice in a row fails. OFF: Runs PowerShell commands unchanged.

Clear ZSH EOL mark

ON: Omits Zsh’s end-of-line mark (%) so output is parsed correctly. Mechanism: sets `PROMPT_EOL_MARK=""`. Use when captured output ends with a stray % or parsing looks off. OFF: Leaves the default EOL mark (may confuse parsing on some setups).

Enable Oh My Zsh integration

For users of the popular Oh My Zsh framework for Zsh. Enable this if you use Oh My Zsh and experience general issues with terminal command execution or output rendering that aren't solved by other settings. This helps Roo Code align with Oh My Zsh's specific shell integration mechanisms by setting `ITERM_SHELL_INTEGRATION_INSTALLED=Yes`. Restarting the IDE might be necessary.

Enable Powerlevel10k integration

For users of the Powerlevel10k theme for Zsh. Enable this if your Powerlevel10k prompt (which can be quite complex) seems to interfere with Roo Code's ability to correctly detect command boundaries, parse output, or track the current working directory. This sets `POWERLEVEL9K_TERM_SHELL_INTEGRATION=true`.

Enable ZDOTDIR handling

ON: Uses a temporary ZDOTDIR so VS Code shell integration works with zsh while preserving your config. Mechanism: creates a temp dir with a `.zshrc` that sources VS Code’s shell integration script, then re-sources your original zsh files and resets ZDOTDIR; the temp dir is cleaned up after initialization. Use when zsh shell integration fails or conflicts with your dotfiles. OFF: Uses your normal ZDOTDIR.

How Shell Integration Works

Shell integration connects Roo to your terminal's command execution process in real-time:

Connection: When you open a terminal, VS Code establishes a special connection with your shell.
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
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.
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

Quick fixes

Update VS Code/Cursor to the latest version (VS Code 1.93+ required).
Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → “Terminal: Select Default Profile” → choose bash, zsh, PowerShell, or fish.
Windows PowerShell: run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, then restart VS Code.
WSL (bash): add . "$(code --locate-shell-integration-path bash)" to ~/.bashrc.

PowerShell Execution Policy (Windows)

PowerShell restricts script execution by default. To configure:

Open PowerShell as Administrator
Check current policy: Get-ExecutionPolicy
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):

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

Zsh (~/.zshrc):

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"

PowerShell ($Profile):

if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

Fish (~/.config/fish/config.fish):

string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

Terminal Customization Issues

If you use terminal customization tools:

Powerlevel10k:

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

set | grep -i '[16]33;'
echo "$PROMPT_COMMAND" | grep vsc
trap -p DEBUG | grep vsc

Zsh:

functions | grep -i vsc
typeset -p precmd_functions preexec_functions

PowerShell:

Get-Command -Name "*VSC*" -CommandType Function
Get-Content Function:\Prompt | Select-String "VSCode"

Fish:

functions | grep -i vsc
functions fish_prompt | grep -i vsc

Visual indicators of active shell integration:

Shell integration indicator in terminal title bar
Command detection highlighting
Working directory updates in terminal title
Command duration and exit code reporting

WSL: best-practice setup

When using Windows Subsystem for Linux (WSL), there are two distinct ways to use VS Code with WSL, each with different implications for shell integration:

Method 1: VS Code Windows with WSL Terminal

In this setup:

VS Code runs natively in Windows
You use the WSL terminal integration feature in VS Code
Shell commands are executed through the WSL bridge
May experience additional latency due to Windows-WSL communication
Shell integration markers may be affected by the WSL-Windows boundary: you must make sure that source "$(code --locate-shell-integration-path <shell>)" is loaded for your shell within the WSL environment because it may not get automatically loaded; see above.

Method 2: VS Code Running Within WSL

In this setup:

You launch VS Code directly from within WSL using code .
VS Code server runs natively in the Linux environment
Direct access to Linux filesystem and tools
Better performance and reliability for shell integration
Shell integration is loaded automatically since VS Code runs natively in the Linux environment
Recommended approach for WSL development

For optimal shell integration with WSL, we recommend:

Open your WSL distribution
Navigate to your project directory
Launch VS Code using code .
Use the integrated terminal within VS Code

Cygwin (bash, zsh)

Cygwin provides a Unix-like environment on Windows systems. To configure Cygwin as your terminal in VS Code:

Install Cygwin from https://www.cygwin.com/
Open VS Code settings:
- Select File > Preferences > Settings
- Click the "Open Settings (JSON)" icon in the top right corner

Add the following configuration to your settings.json (inside the top-level curly braces {}):

{
  "terminal.integrated.profiles.windows": {
    "Cygwin": {
      "path": "C:\\cygwin64\\bin\\bash.exe",
      "args": ["--login"],
      "env": {"CHERE_INVOKING": "1"}
    }
  },
  "terminal.integrated.defaultProfile.windows": "Cygwin"
}

Note: If you have 32-bit Cygwin installed, use "C:\\cygwin\\bin\\bash.exe" for the path.

Understanding the configuration:
- path: Points to the Bash executable in your Cygwin installation
- args: The --login flag ensures the shell reads profile files
- env: The CHERE_INVOKING environment variable tells Cygwin to use the current directory as the working directory
- terminal.integrated.defaultProfile.windows: Sets Cygwin as the default terminal profile
To open a new Cygwin terminal:
- Press Ctrl+Shift+(backtick) to open a new terminal, or
- Press F1, type "Terminal: Create New Terminal (with Profile)", and select "Cygwin"

While our testing shows that this works out of the box, if you encounter shell integration issues with Cygwin, ensure you have added the appropriate shell integration hooks to your Cygwin bash profile as described in the "Manual Shell Integration Installation" section.

VS Code Shell Integration for Fish + Cygwin on Windows

For fellow Windows users running Fish terminal within a Cygwin environment, here's how VS Code's shell integration works:

(Optional) Locate the Shell Integration Script: Open your Fish terminal within VS Code and run the following command:
```
code --locate-shell-integration-path fish
```
This will output the path to the shellIntegration.fish script. Note down this path.

Update Your Fish Configuration: Edit your config.fish file (usually located at ~/.config/fish/config.fish within your Cygwin home directory). Add the following line, preferably within an if status is-interactive block or at the very end of the file:

# Example config.fish structure
if status is-interactive
    # Your other interactive shell configurations...
    # automatic locate integration script:
    string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

    # Or if the above fails for you:
    # Source the VS Code shell integration script
    # IMPORTANT: Replace the example path below with the actual path you found in Step 1.
    # Make sure the path is in a format Cygwin can understand (e.g., using /cygdrive/c/...).
    # source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"
end

Remember to replace the example path with the actual path from Step 1, correctly formatted for Cygwin.

Configure VS Code Terminal Profile: Open your VS Code settings.json file (Ctrl+Shift+P -> "Preferences: Open User Settings (JSON)"). Update or add the Fish profile under terminal.integrated.profiles.windows like this:

{
  // ... other settings ...

  "terminal.integrated.profiles.windows": {
    // ... other profiles ...

    // Recommended: Use bash.exe to launch fish as a login shell
    "fish": {
      "path": "C:\\cygwin64\\bin\\bash.exe", // Or your Cygwin bash path
      "args": [
        "--login",
        "-i",
        "-c",
        "exec fish"
      ],
      "icon": "terminal-bash" // Optional: Use a recognizable icon
    },

    // Alternative (if the above fails): Launch fish directly
    "fish-direct": {
      "path": "C:\\cygwin64\\bin\\fish.exe", // Ensure this is in your Windows PATH or provide full path
      // Use 'options' here instead of 'args'; otherwise, you might encounter the error "terminal process terminated exit code 1".
      "options": ["-l", "-c"], // Example: login and interactive flags.
      "icon": "terminal-fish" // Optional: Use a fish icon
    }
  },

  // Optional: Set fish as your default if desired
  // "terminal.integrated.defaultProfile.windows": "fish", // or "fish-direct" depending what you use.

  // ... other settings ...
}

Note: Using bash.exe --login -i -c "exec fish" is often more reliable in Cygwin environments for ensuring the correct environment setup before fish starts. However, if that approach doesn't work, try the fish-direct profile configuration.

Restart VS Code: Close and reopen Visual Studio Code completely to apply the changes.
Verify: Open a new Fish terminal in VS Code. The shell integration features (like command decorations, better command history navigation, etc.) should now be active. You can test basic functionality by running simple commands like echo "Hello from integrated Fish!".

This setup works reliably on Windows systems using Cygwin, Fish, and the Starship prompt, and should assist users with similar configurations.

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

Premature Completion: PowerShell sometimes tells Roo a command is finished before all the output has been shown.
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.

Python Virtual Environment (venv) Issues

Issue: Disabling shell integration will disable venv; venv is VS Code–managed, Roo does not know anything about it because disabling shell integration uses a completely different mechanism for running commands (execa).

Workaround: If you need to use Python virtual environments with Roo Code, you might be able to:

killall code # closes all VS Code windows!
. venv/bin/activate
code

This way the environment is configured before code launches so Roo should inherit it.

Checking Debug Logs

When shell integration issues occur, check the debug logs:

Open Help → Toggle Developer Tools → Console
Set "Show All Levels" to see all log messages
Look for messages containing [Terminal Process]
Check preOutput content in error messages:
- Empty preOutput ('') means VS Code sent no data
- This indicates a potential VS Code shell integration issue, or an upstream bug that is out of our control
- The absence of shell integration markers may require adjusting settings to work around possible upstream bugs or local workstation configuration issues related to shell initialization and VS Code's loading of special shell integration hooks

Using the VS Code Terminal Integration Test Extension

The VS Code Terminal Integration Test Extension helps diagnose shell integration issues by testing different settings combinations:

When Commands Stall:
- If you see "command already running" warnings, click "Reset Stats" to reset the terminal state
- These warnings indicate shell integration is not working
- Try different settings combinations until you find one that works
- If it really gets stuck, restart the extension by closing the window and pressing F5
Testing Settings:
- Systematically try different combinations of:
  - Terminal Command Delay
  - Shell Integration settings
- Document which combinations succeed or fail
- This helps identify patterns in shell integration issues
Reporting Issues:
- Once you find a problematic configuration
- Document the exact settings combination
- Note your environment (OS, VS Code version, shell, and any shell prompt customization)
- Open an issue with these details to help improve shell integration

FAQ

Why does Roo press Ctrl+C first?
- To clear any partially typed command so it can run reliably without interrupting your process.
Can I run multi-line commands?
- Prefer chaining with && to avoid mixed output (e.g., echo a && echo b).
How do I use Python venv with Inline Terminal?
- Close VS Code, activate the venv in a shell, then launch VS Code so Roo inherits it.

What does “Command Execution Fallback” mean?
- Roo ran the command without full shell integration. How it works: if VS Code terminal integration can’t connect, Roo runs the command in a background process.
- What you’ll see: a chat notice that real-time streaming and exit‑code detection may be limited.
- Fix: turn ON Use Inline Terminal (recommended) or follow the Troubleshooting steps above to restore VS Code shell integration.

FilesExpand file tree

shell-integration.mdx

Latest commit

History