Terminal Shell Integration

Terminal Shell Integration is a core feature of VJSP, enabling the tool to execute commands in the terminal and intelligently process output results. Leveraging bidirectional communication between AI and the development environment, it unlocks a variety of efficient automation scenarios.

What is Shell Integration?

Shell Integration is enabled by default in VJSP, requiring no manual configuration to directly hook into the terminal's command execution lifecycle. This built-in feature allows VJSP to:

Execute commands on your behalf via the execute_command tool
Read command output in real-time, eliminating manual copy-pasting
Automatically detect and fix errors in running applications
Monitor command exit codes to determine success or failure
Track working directory changes during project navigation
Respond intelligently to terminal output without user intervention

When VJSP needs to install dependencies, start development servers, analyze build errors, or perform other operations, Shell Integration runs automatically in the background, ensuring smooth and efficient interactions.

Quick Start with Shell Integration

Shell Integration is built into VJSP and works out of the box for most scenarios. If you see "Shell Integration Unavailable" or experience command execution issues, try these solutions:

Update VSCode/IntelliJ IDEA to the latest version (minimum requirement: VSCode 1.93)
Select a compatible Shell environment: Open the command palette (Ctrl+Shift+P or Cmd+Shift+P) → Run "Terminal: Select Default Profile" → Choose bash, zsh, PowerShell, or fish
Windows PowerShell users: Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, then restart VSCode
WSL users: Add . "$(code --locate-shell-integration-path bash)" to your ~/.bashrc file

Terminal Integration Settings

VJSP provides detailed configuration options to adjust Shell Integration behavior, accessible via the VJSP sidebar under "Settings → Terminal".

Basic Settings

Terminal Output Limit

Controls the maximum number of lines captured from terminal output. When exceeded, the first 20% and last 80% of content are preserved, with a truncation indicator in between. This balances token usage while retaining critical context. Default: 500 lines.

Terminal Shell Integration Timeout

Defines the maximum time to wait for Shell Integration initialization before executing commands. Increase this value if you frequently encounter "Shell Integration Unavailable" errors. Default: 15 seconds.

Terminal Command Delay

Adds a brief pause after command execution to ensure VJSP captures all output. Due to variations in VSCode's terminal integration across operating systems and Shell configurations, this setting significantly impacts stability:

Default: 0 ms
Recommended values:
- 0 ms: Best for newer VSCode versions
- 50 ms: Legacy default, works for most users
- 150 ms: Recommended for PowerShell users
Note: Effectiveness depends on:
- VSCode version
- Shell customizations (e.g., oh-my-zsh, powerlevel10k)
- OS and environment

Advanced Settings

💡 Important

Changes to these settings require a terminal restart to take effect

Advanced terminal settings only apply after restarting the terminal:

Close the current terminal window using the trash can icon
Open a new terminal via "Terminal → New Terminal" or the shortcut Ctrl+`

Always restart all open terminals after modifying advanced settings.

PowerShell Counter Compatibility Fix

Resolves issues with running the same command consecutively in PowerShell. Enable if VJSP fails to execute identical commands repeatedly.

Clear ZSH Line End Markers

Prevents ZSH from appending special characters at line ends, avoiding interference with VJSP's output parsing.

Oh My Zsh Integration

Improves compatibility with the popular Shell customization framework Oh My Zsh. Enable if you experience terminal issues with Oh My Zsh.

Powerlevel10k Integration

Enhances compatibility with the ZSH theme Powerlevel10k. Enable if custom prompts cause VJSP malfunctions.

ZDOTDIR Configuration Support

Allows VJSP to adapt to custom ZSH configurations without interfering with your personal Shell settings.

Shell Integration Troubleshooting

PowerShell Execution Policy (Windows)

PowerShell restricts script execution by default. Configure the policy as follows:

Open PowerShell as Administrator
Check current policy: Get-ExecutionPolicy
Set appropriate policy: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Policy descriptions:

Restricted: No scripts allowed (default)
RemoteSigned: Local scripts run; downloaded scripts require signing
Unrestricted: All scripts run with warnings
AllSigned: All scripts require signing

Manual Shell Integration Installation

If automatic integration fails, add the corresponding line to your Shell config:

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 Conflicts

For tools like Powerlevel10k, add compatibility settings:

bash

# Add to ~/.zshrc before loading powerlevel10k
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

Alternative: Enable "Powerlevel10k Integration" in VJSP settings.

Verify Shell Integration Activation

Check activation 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 successful activation:

Shell integration status indicator in terminal title bar
Command detection highlighting
Automatic title updates with working directory changes
Execution time and exit code display after commands

WSL Terminal Integration

VSCode interacts with WSL in two ways, affecting Shell Integration behavior:

Method 1: Windows VSCode with WSL Terminal

VSCode runs natively on Windows
Uses VSCode's built-in WSL terminal integration
Commands execute via WSL bridge
Potential delays due to cross-system communication
Manual config required: source "$(code --locate-shell-integration-path <shell>)" in WSL

Method 2: VSCode Running Inside WSL

Launch via code . in WSL
VSCode server runs natively on Linux
Direct access to Linux filesystem and tools
Better performance and stability
Automatic Shell Integration loading
Recommended for WSL development

Optimal WSL setup steps:

Open your WSL distribution
Navigate to project directory
Run code . to launch VSCode
Use the built-in terminal

Known Issues & Workarounds

Windows: Fish + Cygwin Configuration

For Windows users running Fish under Cygwin:

(Optional) Locate Integration Script In VSCode's Fish terminal, run:
bash
```
code --locate-shell-integration-path fish
```
1

Update Fish Config Add to ~/.config/fish/config.fish (inside if status is-interactive):

fish

string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)
# Or manual path if needed:
# source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"

Configure VSCode Profile Add to settings.json:

json

{
  "terminal.integrated.profiles.windows": {
    "fish": {
      "path": "C:\\cygwin64\\bin\\bash.exe",
      "args": ["--login", "-i", "-c", "exec fish"],
      "icon": "terminal-bash"
    },
    "fish-direct": {
      "path": "C:\\cygwin64\\bin\\fish.exe",
      "options": ["-l", "-c"],
      "icon": "terminal-fish"
    }
  },
  "terminal.integrated.defaultProfile.windows": "fish"
}

Restart VSCode
Verify Test with echo "Hello from integrated Fish!"

VSCode 1.98+ Shell Integration Failure

Symptom: "VSCE output start escape sequence (]633;C or ]133;C) not received"

Solutions:

Adjust Command Delay: Set to 50ms (or 0ms for some users) and restart terminals
Downgrade VSCode: Install 1.98 from the VSCode Updates page
WSL Fix: Launch VSCode via code . inside WSL
ZSH Fix: Enable ZSH compatibility options in VJSP settings

Ctrl+C Behavior

Symptom: VJSP triggers Ctrl+C to clear input, potentially interrupting running processes

Solution: Ensure the terminal prompt is empty before requesting command execution

Multi-line Command Parsing

Symptom: Mixed output from historical commands

Solution: Use && for chaining (e.g., echo a && echo b) instead of multi-line input

PowerShell-specific Issues

Early completion: PowerShell reports done before full output
Duplicate command failure: Can't run the same command twice

Solution: Enable "PowerShell Counter Compatibility Fix" and set delay to 150ms

Incomplete Terminal Output

Symptom: Missing output in VSCode

Solution: Close and reopen the terminal tab to refresh the connection

Troubleshooting Resources

View Debug Logs

Open "Help → Toggle Developer Tools → Console"
Set log level to "Show All Levels"
Filter for [Terminal Process] messages
Check preOutput field:
- Empty ('') indicates VSCode isn't sending data
- May point to upstream VSCode issues

VSCode Terminal Integration Test Extension

Reset Stuck Commands: Click "Reset Stats" if "command already running"
Test Configurations: Systematically test delay and setting combinations
Report Issues: Include environment details (OS, VSCode version, Shell type) when submitting issues

Terminal Shell Integration ​

What is Shell Integration? ​

Quick Start with Shell Integration ​

Terminal Integration Settings ​

Basic Settings ​

Terminal Output Limit ​

Terminal Shell Integration Timeout ​

Terminal Command Delay ​

Advanced Settings ​

PowerShell Counter Compatibility Fix ​

Clear ZSH Line End Markers ​

Oh My Zsh Integration ​

Powerlevel10k Integration ​

ZDOTDIR Configuration Support ​

Shell Integration Troubleshooting ​

PowerShell Execution Policy (Windows) ​

Manual Shell Integration Installation ​

Bash (~/.bashrc) ​

Zsh (~/.zshrc) ​

PowerShell ($Profile) ​

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

Terminal Customization Conflicts ​

Verify Shell Integration Activation ​

Bash ​

Zsh ​

PowerShell ​

Fish ​

WSL Terminal Integration ​

Method 1: Windows VSCode with WSL Terminal ​

Method 2: VSCode Running Inside WSL ​

Known Issues & Workarounds ​

Windows: Fish + Cygwin Configuration ​

VSCode 1.98+ Shell Integration Failure ​

Ctrl+C Behavior ​

Multi-line Command Parsing ​

PowerShell-specific Issues ​

Incomplete Terminal Output ​

Troubleshooting Resources ​

View Debug Logs ​

VSCode Terminal Integration Test Extension ​

Terminal Shell Integration

What is Shell Integration?

Quick Start with Shell Integration

Terminal Integration Settings

Basic Settings

Terminal Output Limit

Terminal Shell Integration Timeout

Terminal Command Delay

Advanced Settings

PowerShell Counter Compatibility Fix

Clear ZSH Line End Markers

Oh My Zsh Integration

Powerlevel10k Integration

ZDOTDIR Configuration Support

Shell Integration Troubleshooting

PowerShell Execution Policy (Windows)

Manual Shell Integration Installation

Bash (`~/.bashrc`)

Zsh (`~/.zshrc`)

PowerShell (`$Profile`)

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

Terminal Customization Conflicts

Verify Shell Integration Activation

Bash

Zsh

PowerShell

Fish

WSL Terminal Integration

Method 1: Windows VSCode with WSL Terminal

Method 2: VSCode Running Inside WSL

Known Issues & Workarounds

Windows: Fish + Cygwin Configuration

VSCode 1.98+ Shell Integration Failure

Ctrl+C Behavior

Multi-line Command Parsing

PowerShell-specific Issues

Incomplete Terminal Output

Troubleshooting Resources

View Debug Logs

VSCode Terminal Integration Test Extension