Terminal integration in SourceCraft Code Assistant

Integration with the terminal is the key feature allowing Code Assistant to run commands in your terminal and process their output. This two-way connection between the AI and your development environment unlocks powerful automation capabilities.

Terminal integration is on by default in Code Assistant and connects directly to your terminal's command execution lifecycle without requiring any setup. This built-in feature enables Code Assistant to:

• Run commands under your username via the execute_command tool.
• Read command outputs in real time without copying and pasting.
• Automatically detect and fix errors in active applications.
• Track command termination codes to identify success or failure.
• Keep track of the working directory changes as you navigate through your project.
• Respond to the terminal's output without any user intervention.
• Terminate active commands directly from the chat interface using the terminate button (appears next to the command execution message).

When you ask Code Assistant to perform tasks like installing dependencies, starting a development server, or analyzing build errors, the terminal integration runs hidden from view to make these interactions seamless and efficient.

Setting up terminal integration

Code Assistant allows detailed setup of terminal integration. To access these settings:

1. In the chat's top panel, click Settings.
2. In the left-hand panel, navigate to Terminal.

Basic settings

Terminal output limit

This setting controls the amount of output Code Assistant will capture from your commands:

• Consider reducing the setting if you worry about using up too many tokens or if Code Assistant appears slow when processing very long outputs.
• Consider increasing the setting if you often need more long command content, but remember that you may need to spend more tokens. Default: 500 lines.

Compress progress bar output

Leave this option on (default) for cleaner output and to save tokens. This allows Code Assistant to process dynamic output, such as progress bars or spinners, by showing only the end state. Disable it only when debugging intermediate unprocessed output of a progress bar or similar dynamic content.

Advanced settings

Inherit environment variables

This setting controls whether or not Code Assistant terminal sessions will use the same environment variables (e.g., PATH, API keys) as your main VS Code environment.

It directly reflects the VS Code terminal.integrated.inheritEnv global setting.

Leave it on (default for VS Code) if you want your Code Assistant commands to operate in the same context and with the same tools as your regular VS Code terminal. Consider disabling it only if you need a completely clean, isolated environment for the Code Assistant terminal tasks, or if you are resolving complex conflicts of environment variables.

Runtime environment

In macOS (and likely other operating systems as well), the environment provided to VS Code and, consequently, Code Assistant may vary based on how VS Code was started.

If you run VS Code from the terminal using the vscode command, VS Code and Code Assistant will inherit the environment from the shell that had started them, and everything will usually work fine.

If you run VS Code from Finder, Dock, or Spotlight, the environment variables exported from .zshrc or .zprofile will most likely be missing. If you have environment variables installed in one of these files and you find them missing when you run VS Code, move them to .zshenv, log out of the system, and then log in again for the window manager to apply the new environment settings.

Disable terminal shell integration

This setting controls the way Code Assistant runs the terminal commands.

• Enabled: Code Assistant will run commands using the built-in terminal, the output displayed directly in the chat interface. This is a mostly reliable method that yields coherent output, making it the preferred option for the majority of users to interact with the terminal commands via Code Assistant. It guarantees that commands are executed in a coordinated environment managed by Code Assistant.

• Disabled: Code Assistant will try to run commands directly in the VS Code terminal's active panel. This alternative method may be of use in specific cases where commands need to be run in a fully configured VS Code shell environment, or where you have to engage specific VS Code terminal features to run a command. However, this method may prove less reliable depending on you shell settings and VS Code version.

The following settings are optional and apply only with Disable terminal shell integration off:

Terminal shell integration timeout

If shell integration is on but you still see the Shell integration not available message, especially when using advanced shell settings, e.g., Zsh with multiple plugins or in a slow corporate environment, your shell may take too long to initialize. Increase this value to give your shell more time to get Code Assistant ready. Try increasing by 5-10 seconds. The default value is five seconds.

Terminal command delay

If the command output seems incomplete or Code Assistant skips the command output ending even with shell integration on, a short delay may help. Enter a short delay, e.g., 50 or 100 ms. This will give the terminal more time to output all data before Code Assistant considers the command completed. This is a workaround for possible sync issues in the VS Code terminal or some shells (see the #237208 VS Code error). The default value is 0 ms.

Enable PowerShell counter workaround

This setting is PowerShell-specific. Enable the option if you see that Code Assistant has a problem executing the same PowerShell command several times over, or if the PowerShell command output capture is unreliable. This setting adds a unique counter to commands to help PowerShell tell them apart.

Clear ZSH EOL mark

This setting is Zsh-specific. Sometimes Zsh adds a special symbol (often %) at the end of the line if it does not end with a new line. Enable the option if Code Assistant misinterprets or mixes up Zsh command outputs, especially if the last output line contains an unexpected symbol. Code Assistant will try to delete this marker (PROMPT_EOL_MARK='').

Enable Oh My Zsh integration

This setting is specific to the popular Oh My Zsh framework for Zsh. Enable the option if you are using Oh My Zsh and have general issues with the terminal or output display commands that cannot be fixed using any other settings. It helps aligning Code Assistant with Oh My Zsh integration mechanisms by setting ITERM_SHELL_INTEGRATION_INSTALLED=Yes. You may need to restart VS Code.

Enable Powerlevel10k integration

This setting is specific to the Powerlevel10k theme for Zsh. Enable the option if your complex Powerlevel10k prompt prevents Code Assistant from correctly defining command boundaries, analyzing outputs, or monitoring the current working directory. The option sets the POWERLEVEL9K_TERM_SHELL_INTEGRATION=true parameter.

Enable ZDOTDIR handling

Additional setting for Zsh users with custom locations of Zsh start files. Enable the option if you use ZDOTDIR to point out the custom directory for Zsh configuration files, e.g., .zshrc. This setting helps Code Assistant work with such configurations correctly by creating an isolated temporary ZDOTDIR for its own integration scripts and preventing conflicts with your personal Zsh environment.

How shell integration works

Shell integration involves Code Assistant in the terminal command execution process in real time:

• When you open the terminal, VS Code establishes a special connection with your shell.
• VS Code monitors your activity in the terminal by registering:
  • New invites.
  • Command input.
  • Start of command execution.
  • End of command execution (both success and failure).
  • Current directory.
• Each shell type (Bash, Zsh, PowerShell, Fish) implements this slightly differently but they all provide the same functionality to Code Assistant.
• Code Assistant can see what commands are running and where, how much time they take, whether or not they are successful, and their full output – all without you having to copy and paste anything.

Troubleshooting terminal integration

Terminal integration is Code Assistant's native feature that works automatically in most cases. If you get the Shell Integration Unavailable message or have issues with commands, try the following:

• Update VS Code to the latest version. You will need VS Code version 1.93 or higher.
• Make sure you have selected a compatible terminal by going Command palette (Ctrl + Shift + P or Cmd + Shift + P) → Terminal: Select Default Profile → select bash, zsh, PowerShell, or fish.
• For Windows PowerShell, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser and then restart VS Code.
• For WSL, add . "$(code --locate-shell-integration-path bash)" to your ~/.bashrc.

Fallback execution mechanism

Code Assistant features a fallback command execution mechanism. This will prove the most relevant if you had selected Disable terminal shell integration.

If Code Assistant is set up to use the VS Code terminal integration but fails to connect or has issues, it may automatically try to execute the command directly using the background process. This is a fallback to try and execute the command.

If this fallback mechanism is used, you will get a chat message stating that the command is run without the built-in Code Assistant terminal or the VS Code terminal integration being fully functional. If this is the case, real-time stream output or termination code accuracy may be limited.

PowerShell execution policy

By default, PowerShell restricts running scripts. To configure:

1. Open PowerShell as an administrator.
2. Check the current policy: Get-ExecutionPolicy.
3. Install the policy you need: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser.

The main policies are:

• Restricted: Scripts not allowed (default).
• RemoteSigned: Local scripts can be run; downloaded scripts must be signed.
• Unrestricted: All scripts can be run with warnings.
• AllSigned: All scripts must be signed.

Setting up shell integration manually

If automatic integration fails, add the relevant line to your shell configuration:

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

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

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

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

Issues setting up the terminal with the Powerlevel10k theme

Add the following line to ~/.zshrc before adding Powerlevel10k:

typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

You can also enable the Powerlevel10k Integration option in the Code Assistant settings.

Checking shell integration status

Make sure shell integration is active with the help of these commands:

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

functions | grep -i vsc
typeset -p precmd_functions preexec_functions

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

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

Visual indicators of the active shell integration:

1. Shell integration indicator in the terminal header.
2. Command detection highlights.
3. Updates of the working directory in the terminal header.
4. Command execution duration and termination code reports.

WSL terminal integration methods

In Windows Subsystem for Linux (WSL), there are several ways of using VS Code with WSL, each with some shell integration particularities of its own:

VS Code for Windows with the WSL terminal

• VS Code is native to Windows.
• You use the WSL terminal integration function in VS Code.
• Shell commands are executed through a WSL bridge.
• Windows-to-WSL interaction may cause an additional delay.
• Shell integration markers may be affected by the WSL-Windows transition: make sure source "$(code --locate-shell-integration-path <shell>)" loads for your shell in the WSL environment as it may not be happening automatically.

VS Code operating inside WSL

• You start VS Code directly from WSL with the help of the code . command.
• The VS Code server is native to Linux.
• There is direct access to the file system and Linux tools.
• Best performance and reliable shell integration.
• Shell integration loads automatically as VS Code is native to Linux.
• Recommended approach for development using WSL.

For optimal shell integration in WSL, we recommend the following:

1. Open your WSL distribution.
2. Go to your project directory.
3. Start VS Code using code ..
4. Use the built-in terminal in VS Code.

Integration with Cygwin (bash, zsh)

Cygwin is a Unix-like environment for Windows. To configure Gygwin as your terminal in VS Code:

1. Install Cygwin from https://www.cygwin.com/.

2. Open the VS Code settings:

   1. Select File → Preferences → Settings.
   2. In the top-right corner, click Open Settings (JSON).

3. Add the following configuration to settings.json inside the upper level of curly brackets ({}):

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

   Where:

   • path: Points to the Bash executable file in your Cygwin installation.
   • args: The --login flag guarantees that the shell can read the profile files.
   • env: The CHERE_INVOKING environment variable tells Cygwin to use the current directory as the working one.
   • terminal.integrated.defaultProfile.windows: Installs Cygwin as the default terminal profile.

   Note

   If you run the 32-bit version of Cygwin, use "C:\\cygwin\\bin\\bash.exe" for path.

4. Open a new Cygwin terminal by pressing Ctrl + Shift + ****. You can also press **F1**, enter Terminal: Create New Terminal (with Profile)` and select Cygwin.

If you have any issues integrating your shell with Cygwin, make sure you have added proper shell integration hooks to your Cygwin bash profile.

Troubleshooting resources

If you have shell integration issues, check your debugging logs:

1. Open Help → Toggle Developer Tools → Console.
2. To see all log entries, select Show All Levels.
3. Search for entries containing the [Terminal Process] text.