Terminal Integration Troubleshooting Guide

This guide helps you resolve terminal integration issues in Cline. Terminal integration is crucial for Cline to execute commands and read their output, enabling it to understand errors, test results, and command responses.

​

Quick Diagnosis Flowchart

Follow this flowchart to quickly identify your issue:

​

Common Issues & Quick Solutions

​

1. Shell Integration Unavailable

Symptoms:

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

Quick Solutions:

​

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

Symptoms:

• 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

Solutions:

• 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

Symptoms:

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

Solution: This is a known bug in output processing. Workarounds:

• 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

Symptoms:

• 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

Access these in Cline by clicking the settings icon, and navigating to the “Terminal Settings” section:

​

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

Oh-My-Zsh often interferes with shell integration. Solutions:

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

Recent macOS versions have stricter terminal permissions:

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

​

Windows Issues

​

PowerShell Execution Policy

If commands fail silently:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​

WSL Integration

For WSL issues:

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

Windows path problems:

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

For remote development:

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

​

Docker Containers

When developing in 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

Enable terminal debugging to see what’s happening:

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

Test if shell integration works at all:

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

​

FAQ

​

Why does Cline create so many terminals?

When shell integration fails, Cline can’t reuse terminals safely (they might be running long processes). Enable shell integration or adjust the terminal reuse setting.

​

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

Cline officially supports bash, zsh, fish, and PowerShell. Custom shells may work but aren’t guaranteed. Use bash as a fallback.

​

Why do some commands work but others don’t?

Commands that use interactive features (pagers, progress bars, curses) often fail. Set PAGER=cat and use non-interactive flags.

​

How do I know if shell integration is working?

Working integration shows command output in Cline’s chat. Failed integration shows “Shell Integration Unavailable” or “[Command is running but producing no output]”.

​

Still Having Issues?

If you’ve tried everything:

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