WSL Support All Tiers

Using PairCoder with Windows Subsystem for Linux.

Overview

PairCoder fully supports Windows Subsystem for Linux (WSL1 and WSL2). It automatically detects when running in WSL and provides appropriate path hints and editor interoperability.

Auto-Detection

PairCoder automatically detects WSL environment and adapts its behavior:

bash 
# Check if WSL is detected
bpsai-pair system info

# Output includes:
# Platform: Linux (WSL2)
# WSL Distro: Ubuntu-22.04

Installation in WSL

Install PairCoder inside your WSL distribution:

bash 
# Inside WSL (Ubuntu/Debian)
sudo apt update
sudo apt install python3.12 python3-pip

# Install PairCoder
pip install bpsai-pair

# Verify
bpsai-pair --version

Path Handling

PairCoder provides helpful path conversion hints when working between Windows and WSL file systems.

Accessing Windows Files

bash 
# Windows drives are mounted at /mnt/
cd /mnt/c/Users/YourName/projects/my-project

# Initialize PairCoder
bpsai-pair init
Performance Note

For best performance, keep your project files in the Linux filesystem (e.g., ~/projects/) rather than on the Windows mount (/mnt/c/). File operations are significantly faster on the native Linux filesystem.

Path Conversion

bash 
# Convert Windows path to Linux path
wslpath -u "C:\Users\name\project"
# Output: /mnt/c/Users/name/project

# Convert Linux path to Windows path
wslpath -w "/home/user/project"
# Output: \\wsl$\Ubuntu\home\user\project

Editor Integration

VS Code (Recommended)

VS Code with the WSL extension provides the best experience:

  1. Install VS Code on Windows
  2. Install the "WSL" extension
  3. From WSL, run code . to open in WSL mode
bash 
# Set VS Code as your editor
export PAIRCODER_EDITOR="code"

# Add to ~/.bashrc for persistence
echo 'export PAIRCODER_EDITOR="code"' >> ~/.bashrc

Cursor IDE

bash 
# Cursor also supports WSL
export PAIRCODER_EDITOR="cursor"

# Or with full path if not in PATH
export PAIRCODER_EDITOR="/mnt/c/Users/name/AppData/Local/Programs/cursor/Cursor.exe"

Native Linux Editors

bash 
# Use vim/neovim in terminal
export PAIRCODER_EDITOR="nvim"

# Or nano for simplicity
export PAIRCODER_EDITOR="nano"

Terminal Support

PairCoder works with all common WSL terminals:

  • Windows Terminal - Recommended for best experience
  • VS Code integrated terminal - Works seamlessly
  • ConEmu / Cmder - Full support
  • Native WSL terminal - Basic support

Terminal Configuration

bash 
# Ensure UTF-8 encoding for proper display
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Enable color support
export TERM=xterm-256color

Claude Code in WSL

When using Claude Code inside WSL, ensure your API key is set in the WSL environment:

bash 
# Set API key in WSL
export ANTHROPIC_API_KEY="sk-ant-..."

# Add to ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc

# Verify it's set
echo $ANTHROPIC_API_KEY

MCP Server in WSL

To use PairCoder's MCP server with Claude Desktop on Windows, you'll need to configure the Windows-side Claude Desktop to call into WSL:

json 
// In Claude Desktop's config (Windows)
{
  "mcpServers": {
"paircoder": {
  "command": "wsl",
  "args": ["-e", "bpsai-pair", "mcp", "serve"]
}
  }
}

Common Issues

Slow file operations

If commands are slow, you might be working on the Windows filesystem. Move your project to the Linux filesystem:

bash 
# Copy project to Linux filesystem
cp -r /mnt/c/Users/name/project ~/projects/

# Work from there
cd ~/projects/project
bpsai-pair init

Permission denied errors

bash 
# Fix permissions on Linux filesystem
chmod -R 755 ~/projects/my-project

# For Windows filesystem, permissions are managed by Windows

Git credential issues

Use Windows Git Credential Manager from WSL:

bash 
# Configure Git to use Windows credential manager
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Recommended Setup

For the best PairCoder experience on WSL:

  1. Use WSL2 (better performance than WSL1)
  2. Keep projects in Linux filesystem (~/projects/)
  3. Use VS Code with WSL extension
  4. Use Windows Terminal for CLI work
  5. Set environment variables in ~/.bashrc or ~/.zshrc