Terminal Integration Troubleshooting Guide

​

Quick Diagnosis Flowchart

​

Common Issues & Quick Solutions

​

1. Shell Integration Unavailable

• Message: “Shell Integration Unavailable”
• Commands execute but Cline can’t read output
• Terminal works fine manually but not with Cline

​

macOS

• Switch to bash
  1. Go to Cline Settings
  2. Left-Click the “Terminal Settings” tab
  3. Navigate to “Default Terminal Profile” and select “bash” from the drop-down menu
• Disable Oh-My-Zsh temporarily:
  1. If using zsh, enter mv ~/.zshrc ~/.zshrc.backup into the terminal
  2. Restart VSCode
• Set environment: 1.a For Zsh users, use one of the following Zsh commands to edit your shell profile:
  • nano ~/.zshrc
  • vim ~/.zshrc
  • code ~/.zshrc
  1.b For Bash users
  • nano ~/.bash_profile
  2. Add the following to your shell config: export TERM=xterm-256color
  3. Save your configuration

​

Windows

• Use PowerShell 7
  1. Install from Microsoft Store
  2. Go to Cline Settings
  3. Left-Click the “Terminal Settings” tab
  4. Navigate to “Default Terminal Profile” and select “PowerShell 7” from the drop-down menu
• Disable Windows ConPTY
  1. Navigate to your VSCode Settings
  2. Enter “Integrated: Windows Enable Conpty” into the Settings searchbar
  3. Uncheck the option
• Try Command Prompt
  1. Go to Cline Settings
  2. Left-Click the “Terminal Settings” tab
  3. Navigate to “Default Terminal Profile” and select “Command Prompt” from the drop-down menu

​

Linux

• Use bash
  1. Go to Cline Settings
  2. Left-Click the “Terminal Settings” tab
  3. Navigate to “Default Terminal Profile” and select “bash” from the drop-down menu
• Check permissions
  1. Ensure VSCode has terminal access permissions
• Disable custom prompts
  1. Comment out prompt customizations in .bashrc

​

2. Command Output Not Visible

• Cline states in chat: “[Command is running but producing no output]”
• Commands complete but Cline doesn’t see results
• Commands work sometimes but not consistently

• Increase Shell Integration Timeout
  1. Within Cline, left-click the Settings button in the top right-hand corner of the chat window
  2. Once in the Settings window, left-click the “Terminal Settings” tab from the left-hand column
  3. Navigate to “Shell integration timeout (seconds)” and enter “10” into the text field
• Disable Terminal Reuse
  1. Within Cline, left-click the Settings button in the top right-hand corner of the chat window
  2. Once in the Settings window, left-click the “Terminal Settings” tab from the left-hand column
  3. Look for “Enable aggressive terminal reuse”, and uncheck this option
• Check for interfering extensions
  1. Disable other terminal-related VSCode extensions

​

3. Character Filtering Issues

• Commas missing from output (JSON appears corrupted)
• Special characters stripped from terminal output
• Syntax errors that don’t appear when running manually

• Recommend AI to use file output instead
  1. Tell Cline in chat or Cline rules, to use command > output.txt before reading the file/s

​

4. Long-Running Commands & Progress Bars

• Docker builds never complete in Cline
• Progress bars consume thousands of tokens
• The Cline button “Proceed while running” doesn’t work properly in chat

​

Terminal Settings Explained

​

Default Terminal Profile

• What it does: Selects which shell Cline uses for commands
• When to change: If experiencing shell integration issues with your default shell
• Recommended: - macOS: bash (if zsh has issues) - Windows: PowerShell 7 - Linux: bash

​

Shell Integration Timeout

• What it does: How long Cline waits for the terminal to be ready
• Default: 4 seconds
• When to increase:
  • Slow shell startup (heavy .zshrc/.bashrc)
  • WSL environments
  • SSH connections
• Recommended: - Start with 10 seconds if having issues

​

Enable Aggressive Terminal Reuse

• What it does: Reuses existing terminals even if not in the correct directory
• When to disable:
  • Commands execute in wrong directory
  • Virtual environment issues
  • Terminal state corruption
• Trade-off: - Disabling creates more terminals but ensures clean state

​

Terminal Output Line Limit

• What it does: Limits how many lines Cline reads from terminal output
• Default: 500 lines
• When to adjust:
  • Increase for verbose build outputs
  • Decrease if hitting token limits
  • Set to 100 for commands with progress bars

​

Platform-Specific Solutions

​

macOS Issues

​

Oh-My-Zsh Conflicts

1. Create a minimal .zshrc for VSCode:
   Copy

   Ask AI

   # ~/.zshrc-vscode
   export TERM=xterm-256color
   export PAGER=cat
   # Minimal PATH and environment setup
   

2. Configure VSCode to use it:
   Copy

   Ask AI

   {
   	"terminal.integrated.env.osx": {
   		"ZDOTDIR": "~/.zshrc-vscode"
   	}
   }
   

​

macOS 15+ Issues

1. System Preferences → Privacy & Security → Developer Tools
2. Add Visual Studio Code
3. Restart VSCode completely

​

Windows Issues

​

Git Bash

1. Download and run the Git for Windows installer from 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

• Check your current PowerShell version by running: $PSVersionTable.PSVersion
• If your version is below 7, update PowerShell.

​

Understanding PowerShell Execution 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.

​

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

   Ask AI

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

   Ask AI

   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.

​

WSL Integration

1. Use WSL extension for VSCode
2. Open folder in WSL: code . from WSL terminal
3. Select “WSL Bash” as terminal profile in Cline

​

Path Issues

1. Use forward slashes in Cline: C:/Users/...
2. Quote paths with spaces: "C:/Program Files/..."
3. Avoid ~ - use full paths

​

Linux/SSH/Container Issues

​

SSH Connections

1. Install Cline on the remote machine, not locally
2. Use SSH extension’s integrated terminal
3. Increase timeout to 15+ seconds

​

Docker Containers

1. Install Cline in the container
2. Use Dev Containers extension
3. Ensure shell integration scripts are available

​

Shell-Specific Fixes

​

Zsh

# Add to ~/.zshrc
export TERM=xterm-256color
export PAGER=cat
# Disable fancy prompts for VSCode
if [[ "$TERM_PROGRAM" == "vscode" ]]; then
    PS1="%n@%m %1~ %# "
fi

​

Bash

# Add to ~/.bashrc
export TERM=xterm-256color
export PAGER=cat
# Simple prompt for VSCode
if [[ "$TERM_PROGRAM" == "vscode" ]]; then
    PS1='\u@\h:\w\$ '
fi

​

Fish

# Add to ~/.config/fish/config.fish
set -x TERM xterm-256color
set -x PAGER cat
# Disable fancy features in VSCode
if test "$TERM_PROGRAM" = "vscode"
    function fish_prompt
        echo (whoami)'@'(hostname)':'(pwd)'> '
    end
end

​

PowerShell

# Add to $PROFILE
$env:PAGER = "cat"
# Disable progress bars
$ProgressPreference = 'SilentlyContinue'

​

Advanced Troubleshooting

​

Debug Mode

1. Open VSCode Command Palette (Cmd/Ctrl+Shift+P)
2. Run: “Developer: Set Log Level…”
3. Choose “Trace”
4. Check Output panel → “Cline” for terminal logs

​

Manual Shell Integration Test

# In VSCode terminal
echo $TERM_PROGRAM  # Should show "vscode"
echo $VSCODE_SHELL_INTEGRATION  # Should be "1"

​

FAQ

​

Why does Cline create so many terminals?

​

Can I use my custom shell (nushell, xonsh, etc.)?

​

Why do some commands work but others don’t?

​

How do I know if shell integration is working?

​

Still Having Issues?

1. Collect Debug Info:
   Copy

   Ask AI

   echo "Shell: $SHELL"
   echo "Term: $TERM"
   echo "VSCode: $TERM_PROGRAM"
   which bash
   bash --version
   

2. Report the Issue:
   • Use /reportbug in Cline github issues
   • Include your debug info
   • Mention which solutions you tried