Terminal Integration Troubleshooting Guide

This guide assists you in troubleshooting terminal integration problems within Sypha. For Sypha to function properly, terminal integration must work correctly so it can run commands and capture their output, allowing it to interpret error messages, test outcomes, and command responses.

Quick Diagnosis Flowchart

Use this flowchart to rapidly pinpoint the problem you're encountering:

graph TD
    A[Terminal Issue] --> B{Can Sypha execute commands?}
    B -->|No| C[Shell Integration Unavailable]
    B -->|Yes| D{Can Sypha see the output?}
    D -->|No| E[Output Capture Failed]
    D -->|Yes| F{Is the output corrupted?}
    F -->|Yes| G[Character Filtering Issue]
    F -->|No| H{Does the command hang?}
    H -->|Yes| I[Long-Running Command Issue]
    H -->|No| J[Check Terminal Settings]

    C --> K[Try Solution 1]
    E --> L[Try Solution 2]
    G --> M[Try Solution 3]
    I --> N[Try Solution 4]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style K fill:#9f9,stroke:#333,stroke-width:2px
    style L fill:#9f9,stroke:#333,stroke-width:2px
    style M fill:#9f9,stroke:#333,stroke-width:2px
    style N fill:#9f9,stroke:#333,stroke-width:2px

Frequent Problems & Fast Solutions

1. Shell Integration Unavailable

Symptoms:

• Error message displays: "Shell Integration Unavailable"
• Commands run successfully but Sypha cannot capture the output
• Terminal functions correctly when used manually but fails with Sypha

Fast Solutions:

macOS

• Change to bash

  1. Navigate to Sypha Settings
  2. Click on the "Terminal Settings" tab
  3. Locate "Default Terminal Profile" and choose "bash" from the dropdown list

• Temporarily disable Oh-My-Zsh:

  1. When using zsh, run mv ~/.zshrc ~/.zshrc.backup in the terminal
  2. Relaunch VSCode

• Configure environment: 1.a Zsh users should utilize one of these Zsh commands to modify their shell profile:

  • nano ~/.zshrc
  • vim ~/.zshrc
  • code ~/.zshrc

  1.b Bash users should use

  • nano ~/.bash_profile
  2. Insert the following line into your shell configuration: export TERM=xterm-256color
  3. Save the configuration file

Windows

• Utilize PowerShell 7

  1. Download and install from Microsoft Store
  2. Open Sypha Settings
  3. Click the "Terminal Settings" tab
  4. Find "Default Terminal Profile" and choose "PowerShell 7" from the dropdown list

• Turn off Windows ConPTY

  1. Open your VSCode Settings
  2. Search for "Integrated: Windows Enable Conpty" in the Settings search field
  3. Disable this option

• Switch to Command Prompt

  1. Open Sypha Settings
  2. Click the "Terminal Settings" tab
  3. Find "Default Terminal Profile" and choose "Command Prompt" from the dropdown list

Linux

• Switch to bash

  1. Navigate to Sypha Settings
  2. Click the "Terminal Settings" tab
  3. Locate "Default Terminal Profile" and choose "bash" from the dropdown list

• Verify permissions

  1. Confirm that VSCode has the necessary terminal access permissions

• Turn off custom prompts

  1. Add comment markers to prompt customizations within .bashrc

2. Command Output Not Visible

Symptoms:

• Sypha displays in chat: "[Command is running but producing no output]"
• Commands finish execution but Sypha fails to retrieve results
• Commands function intermittently rather than reliably

Solutions:

• Extend Shell Integration Timeout

  1. In Sypha, click the Settings button located at the top right corner of the chat interface
  2. After opening the Settings window, click the "Terminal Settings" tab on the left side
  3. Find "Shell integration timeout (seconds)" and input "10" in the text field

• Turn Off Terminal Reuse

  1. In Sypha, click the Settings button located at the top right corner of the chat interface
  2. After opening the Settings window, click the "Terminal Settings" tab on the left side
  3. Locate "Enable aggressive terminal reuse" and deselect this checkbox

• Identify conflicting extensions

  1. Deactivate other VSCode extensions related to terminal functionality

3. Character Filtering Issues

Symptoms:

• Output is missing commas (causing JSON to appear malformed)
• Terminal output has special characters removed
• Syntax errors appear that don't exist when executing manually

Solution: This represents a known defect in output processing. Available workarounds:

• Instruct AI to redirect output to files
  1. Direct Sypha through chat or Sypha rules to employ command > output.txt prior to accessing the file/s

4. Long-Running Commands & Progress Bars

Symptoms:

• Docker builds fail to finish within Sypha
• Progress bars use up thousands of tokens
• The "Proceed while running" button in Sypha chat malfunctions

Terminal Settings Explained

Access these settings within Sypha by clicking the settings icon and proceeding to the "Terminal Settings" section:

Default Terminal Profile

• Function: Determines which shell Sypha utilizes for command execution
• Modification trigger: When encountering shell integration problems with your current default shell
• Suggested settings: - macOS: bash (when zsh causes problems) - Windows: PowerShell 7 - Linux: bash

Shell Integration Timeout

• Function: Defines the duration Sypha waits for terminal readiness
• Default value: 4 seconds
• Scenarios requiring increase:
  • Delayed shell initialization (resource-intensive .zshrc/.bashrc)
  • WSL setups
  • SSH remote connections
• Suggested value: - Begin with 10 seconds when experiencing difficulties

Enable Aggressive Terminal Reuse

• Function: Allows reusing existing terminals regardless of current directory
• Scenarios requiring disablement:
  • Commands run in incorrect directories
  • Virtual environment complications
  • Terminal state becomes corrupted
• Consideration: - Disabling spawns additional terminals but guarantees clean state

Terminal Output Line Limit

• Function: Controls the maximum number of lines Sypha captures from terminal output
• Default value: 500 lines
• Scenarios requiring adjustment:
  • Raise for detailed build outputs
  • Lower when approaching token limitations
  • Configure to 100 for commands displaying progress bars

Platform-Specific Solutions

macOS Issues

Oh-My-Zsh Conflicts

Oh-My-Zsh frequently causes interference with shell integration. Available solutions:

1. Build a lightweight .zshrc specifically for VSCode:

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

2. Set up VSCode to utilize it:

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

macOS 15+ Issues

Newer macOS releases enforce more stringent terminal permissions:

1. System Preferences → Privacy & Security → Developer Tools
2. Include Visual Studio Code in the list
3. Perform a complete VSCode restart

Windows Issues

When using Windows and continuing to face shell integration challenges after attempting the previous solutions, it's advisable to employ Git Bash (or PowerShell).

Git Bash

Git Bash serves as a terminal emulator delivering a Unix-style command line interface on Windows. To implement Git Bash, follow these steps:

1. Acquire and execute the Git for Windows installer from https://git-scm.com/downloads/win
2. Close and relaunch VSCode
3. Press Ctrl + Shift + P to access the Command Palette
4. Enter "Terminal: Select Default Profile" and select it
5. Choose "Git Bash"

PowerShell

Should you prefer to continue using PowerShell, verify you're running a current version (v7+ minimum).

• Verify your installed PowerShell version by executing: $PSVersionTable.PSVersion
• Should your version be earlier than 7, upgrade PowerShell.

You might need to modify your PowerShell execution policy as well. PowerShell's default configuration limits script execution for security purposes.

Understanding PowerShell Execution Policies

PowerShell employs execution policies to control which scripts are permitted to execute on your system. The most frequently used policies include:

• Restricted: PowerShell scripts cannot execute. This represents the default configuration.
• AllSigned: Every script, including locally created ones, requires a signature from a trusted publisher.
• RemoteSigned: Locally authored scripts may execute, while internet-sourced scripts require signatures.
• Unrestricted: No limitations exist. Scripts can execute freely, although warnings appear before running internet-downloaded scripts.

For VSCode development tasks, the RemoteSigned policy is typically advised. It permits locally authored scripts to execute without limitations while preserving security for downloaded scripts. For additional information about PowerShell execution policies and their security ramifications, consult Microsoft's documentation: About Execution Policies.

Steps to Change the Execution Policy

1. Launch PowerShell with Administrator privileges: Press Win + X and choose "Windows PowerShell (Administrator)" or "Windows Terminal (Administrator)".

2. Verify Current Execution Policy by executing this command:

   Get-ExecutionPolicy

   • When the result shows RemoteSigned, Unrestricted, or Bypass, modifying your execution policy is probably unnecessary. These policies permit shell integration to function.
   • When the result displays Restricted or AllSigned, you'll likely need to modify your policy to activate shell integration.

3. Modify the Execution Policy by executing the following command:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

   • This establishes the policy as RemoteSigned for the current user exclusively, offering better security than system-wide modifications.

4. Approve the Change by entering Y and pressing Enter at the prompt.

5. Confirm the Policy Modification by executing Get-ExecutionPolicy once more to validate the new configuration.

6. Relaunch VSCode and attempt the shell integration once more.

WSL Integration

For addressing WSL problems:

1. Employ the WSL extension for VSCode
2. Launch folder within WSL: code . from WSL terminal
3. Choose "WSL Bash" as the terminal profile in Sypha

Path Issues

Resolving Windows path complications:

1. Employ forward slashes in Sypha: C:/Users/...
2. Enclose paths containing spaces in quotes: "C:/Program Files/..."
3. Refrain from using ~ - employ complete paths instead

Linux/SSH/Container Issues

SSH Connections

For remote development scenarios:

1. Deploy Sypha on the remote system, not on your local machine
2. Utilize the SSH extension's integrated terminal
3. Extend timeout to 15+ seconds

Docker Containers

When working within containers:

1. Deploy Sypha inside the container
2. Employ the Dev Containers extension
3. Verify shell integration scripts are accessible

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

Activate terminal debugging to observe what's occurring:

1. Access VSCode Command Palette (Cmd/Ctrl+Shift+P)
2. Execute: "Developer: Set Log Level..."
3. Select "Trace"
4. Review Output panel → "Sypha" for terminal logs

Manual Shell Integration Test

Verify whether shell integration functions at all:

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

FAQ

Why does Sypha create so many terminals?

When shell integration malfunctions, Sypha cannot safely reuse terminals (they could be executing lengthy processes). Activate shell integration or modify the terminal reuse configuration.

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

Sypha provides official support for bash, zsh, fish, and PowerShell. Custom shells might function but lack guarantees. Employ bash as a backup option.

Why do some commands work but others don't?

Commands utilizing interactive capabilities (pagers, progress bars, curses) frequently malfunction. Configure PAGER=cat and employ non-interactive options.

How do I know if shell integration is working?

Functioning integration displays command output within Sypha's chat. Malfunctioning integration displays "Shell Integration Unavailable" or "[Command is running but producing no output]".

Still Having Issues?

When you've exhausted all options:

1. Gather Debug Information:

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

2. Submit the Issue:

   • Employ /reportbug in Sypha github issues
   • Attach your debug information
   • Specify which solutions you've attempted