Aller au contenu principal

Utiliser les agents Cursor avec WSL sur Windows

Guide des agents distants WSL Cursor

Windows Subsystem for Linux (WSL) vous permet d'exécuter un environnement Linux directement sur Windows, combinant le meilleur des deux plateformes. L'exécution d'agents Cursor dans WSL permet d'utiliser les outils Linux natifs, les gestionnaires de packages et les systèmes de compilation tout en conservant le bureau Windows familier. Cependant, l'interaction entre l'hôte Windows et l'environnement WSL introduit des défis uniques, en particulier en matière de gestion du terminal et d'exécution des agents. Ce guide couvre tout, de la configuration initiale au dépannage avancé.

Prérequis​

Avant de configurer Cursor avec WSL, assurez-vous de disposer des éléments suivants :

  • Windows 11 (recommandé) ou Windows 10 avec les dernières mises à jour
  • WSL 2 installé et configuré (exécutez wsl --install dans un PowerShell élevé)
  • Une distribution Linux installée (Ubuntu est la valeur par défaut et la plus testée)
  • Cursor installé sur l'hôte Windows (pas dans WSL)
  • Ressources système suffisantes : au moins 8 Go de RAM et 20 Go d'espace disque libre
astuce

Utilisez WSL 2 plutôt que WSL 1. WSL 2 fournit un noyau Linux complet avec de meilleures performances et compatibilité. Vérifiez votre version avec wsl -l -v dans PowerShell. Si vous voyez la version 1, mettez à niveau avec wsl --set-version <DistroName> 2.

Configuration de WSL pour Cursor​

Installation et configuration de WSL​

Si vous n'avez pas encore installé WSL, suivez ces étapes :

# Exécuter dans un PowerShell élevé (Exécuter en tant qu'administrateur)
wsl --install

# Cela installe WSL 2 avec la distribution Ubuntu par défaut
# Redémarrez votre ordinateur lorsque vous y êtes invité

# Après le redémarrage, configurez votre utilisateur Linux et votre mot de passe
# Puis vérifiez l'installation
wsl --list --verbose

Résultat attendu :

  NAME      STATE           VERSION
* Ubuntu    Running         2

Installation des outils de développement dans WSL​

Une fois WSL configuré, installez les outils de développement dont votre projet a besoin dans l'environnement Linux :

# Dans WSL, mettez à jour les listes de packages
sudo apt update && sudo apt upgrade -y

# Installez les outils de développement courants
sudo apt install -y build-essential git curl wget unzip

# Installez Node.js via Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

# Installez Python
sudo apt install -y python3 python3-pip python3-venv

# Installez Go
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Installez Docker (optionnel, pour le développement conteneurisé)
sudo apt install -y docker.io
sudo usermod -aG docker $USER
attention

N'installez pas Cursor dans WSL. Cursor doit être installé sur l'hôte Windows. Il se connecte à WSL comme un environnement distant, de manière similaire à la façon dont il se connecte aux distants SSH. L'installation de Cursor dans WSL entraînera des problèmes d'affichage et des fonctionnalités GUI manquantes.

Connexion de Cursor à WSL​

Cursor intègre la prise en charge de WSL via l'extension Remote Development :

  1. Ouvrez Cursor sur Windows
  2. Ouvrez la palette de commandes (Ctrl+Shift+P)
  3. Tapez et sélectionnez : WSL: Connect to WSL
  4. Choisissez votre distribution installée (par exemple, Ubuntu)
  5. Cursor se rechargera et se connectera à l'environnement WSL

Alternativement, vous pouvez ouvrir un projet WSL directement depuis le terminal :

# Depuis Windows PowerShell ou l'invite de commandes
cd \\wsl$\Ubuntu\home\username\my-project
cursor .

Ou depuis WSL :

# Naviguez vers votre répertoire de projet
cd ~/my-project

# Lancez Cursor connecté à ce chemin WSL
cursor .
astuce

Créez un raccourci ou un alias Windows qui ouvre Cursor dans votre répertoire personnel WSL pour un accès rapide :

# Ajouter à votre profil PowerShell
function cursor-wsl { wsl -e bash -c "cd ~ && cursor ." }

Cela vous permet de taper cursor-wsl dans PowerShell pour ouvrir Cursor dans votre répertoire personnel WSL instantanément.

Configuration du terminal​

Comprendre le comportement du terminal dans WSL​

Lorsque Cursor s'exécute en mode WSL, le terminal intégré peut fonctionner dans deux modes :

  • Terminal WSL : Exécute des commandes dans l'environnement Linux (par défaut)
  • Terminal Windows : Exécute des commandes sur l'hôte Windows

Le mode terminal affecte la façon dont les agents interagissent avec le système. Les agents exécutent généralement des commandes dans le terminal WSL, mais certaines opérations peuvent nécessiter d'être exécutées sur l'hôte Windows.

Configuration du terminal par défaut​

// Dans settings.json (accessible via Ctrl+, > Open Settings JSON)
{
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "bash",
      "args": ["-l"],
      "icon": "terminal-bash"
    },
    "zsh": {
      "path": "zsh",
      "args": ["-l"],
      "icon": "terminal-zsh"
    }
  },
  // S'assurer que Cursor utilise le shell WSL pour les commandes d'agent
  "cursor.agent.shell": "wsl",
  "cursor.agent.shellPath": "/bin/bash"
}

Restauration d'un terminal cassé​

Un problème courant dans les configurations WSL est un terminal cassé ou non réactif. Le terminal peut afficher des messages d'erreur, ne pas démarrer ou afficher une sortie brouillée. Voici comment le réparer :

# Étape 1 : Vérifier si le processus du terminal est en cours d'exécution
# Palette de commandes : Terminal: Select Default Profile

# Étape 2 : Vérifier que le chemin du shell est correct
# Le chemin doit pointer vers un shell valide dans WSL
// Correctif courant : définir explicitement le chemin du shell
{
  "terminal.integrated.shell.linux": "/bin/bash",
  "terminal.integrated.env.linux": {
    "TERM": "xterm-256color",
    "COLORTERM": "truecolor",
    "LANG": "en_US.UTF-8"
  }
}

Si le terminal est complètement non réactif :

  1. Fermez toutes les instances de terminal dans Cursor
  2. Ouvrez la palette de commandes et exécutez : Terminal: Restart Terminal Server
  3. Si cela ne fonctionne pas, rechargez la fenêtre : Developer: Reload Window
  4. En dernier recours, redémarrez complètement Cursor
attention

Si le terminal affiche "The terminal process failed to launch" ou "exec bash: no such file or directory", l'intégration WSL est cassée. Cela se produit généralement après une mise à jour Windows ou un changement de distribution WSL. Exécutez wsl --shutdown dans PowerShell, puis reconnectez Cursor à WSL.

Résolution des blocages d'agent dans gatherTerminalSelections​

Comprendre le problème​

L'un des problèmes les plus signalés avec WSL et les agents Cursor est le blocage gatherTerminalSelections. Lorsqu'un agent tente d'interagir avec le terminal, il appelle une fonction interne appelée gatherTerminalSelections pour déterminer quel terminal utiliser. Dans les environnements WSL, cette fonction peut se bloquer indéfiniment, provoquant le gel de l'agent.

Symptômes​

  • L'agent commence à exécuter une tâche mais se bloque à l'étape d'interaction avec le terminal
  • La barre d'état affiche "Agent is working..." indéfiniment
  • Aucune sortie de terminal n'apparaît
  • L'agent finit par expirer ou nécessite une annulation manuelle
  • La console développeur de Cursor peut afficher une promise gatherTerminalSelections en attente

Causes principales​

Le blocage se produit généralement en raison de l'une des raisons suivantes :

  1. Plusieurs profils de terminal : Cursor ne peut pas décider quel profil de terminal utiliser
  2. Scripts d'intégration shell : Le script d'intégration shell ne se charge pas dans WSL
  3. Problèmes d'allocation PTY : L'allocation de pseudo-terminal de WSL diffère de Linux natif
  4. Conflits de variables d'environnement : Les variables d'environnement Windows fuient dans WSL et causent des conflits

Solution 1 : Simplifier les profils de terminal​

Réduisez le nombre de profils de terminal pour éviter l'ambiguïté de sélection :

// Dans settings.json
{
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "/bin/bash",
      "args": ["-l"]
    }
  },
  "terminal.integrated.defaultProfile.linux": "bash",
  // Désactiver les autres profils qui peuvent confondre l'agent
  "terminal.integrated.profiles.windows": {},
  "terminal.integrated.detectableProfiles": false
}
astuce

Après avoir modifié les paramètres de profil de terminal, rechargez la fenêtre Cursor. Le cache de sélection de terminal de l'agent est effacé lors du rechargement, ce qui résout souvent le blocage lors de la prochaine exécution de l'agent.

Solution 2 : Réparer l'intégration shell​

L'intégration shell permet à l'agent de suivre la sortie des commandes. Dans WSL, le script d'intégration peut ne pas se charger correctement. Vérifiez et réparez-le :

# Dans WSL, vérifier si l'intégration shell est chargée
echo $TERM_PROGRAM

# Devrait afficher : cursor ou vsoc (si vous utilisez le terminal Cursor/VS Code)
# Si vide, l'intégration shell n'est pas chargée

# Sourcer manuellement le script d'intégration
# Trouver le bon chemin :
ls /mnt/c/Users/*/AppData/Local/Programs/cursor/resources/app/out/vs/shell/integration/

# Ou ajouter ceci à votre ~/.bashrc
if [ -n "$CURSOR_IPC_HANDLE" ]; then
  export CURSOR_INTEGRATION_ENABLED=1
fi

Solution 3 : Pré-allouer un terminal​

Créer un terminal dédié pour l'agent avant de le lancer peut empêcher le blocage de sélection :

// Dans settings.json
{
  "cursor.agent.terminal": {
    "autoCreate": true,
    "profile": "bash",
    "waitForIntegration": true,
    "integrationTimeout": 5000
  }
}

Cela indique à Cursor de créer un terminal utilisant le profil spécifié avant le démarrage de l'agent, contournant entièrement le processus de sélection.

Solution 4 : Désactiver l'invite de sélection de shell​

Si le blocage est causé par une invite de sélection qui ne se résout jamais, désactivez l'invite :

{
  "cursor.agent.terminal.selectionMode": "auto",
  "cursor.agent.terminal.skipSelection": true
}
attention

Désactiver l'invite de sélection de terminal signifie que l'agent utilisera toujours le profil de terminal par défaut. Si vous devez exécuter des agents dans différents environnements de terminal, vous devrez modifier manuellement le profil par défaut avant chaque exécution.

Unifier les compétences d'agent entre l'hôte Windows et WSL​

Le défi​

Lorsque vous travaillez avec Windows et WSL, vous pouvez avoir différents outils, configurations et définitions de compétences de chaque côté. Cela crée une expérience fragmentée où un agent pourrait savoir comment faire quelque chose sur l'hôte Windows mais pas dans WSL, ou vice versa.

Partager les fichiers de configuration​

L'approche la plus efficace consiste à partager les fichiers de configuration d'agent entre les deux environnements. Puisque WSL peut accéder au système de fichiers Windows via /mnt/c/, vous pouvez stocker la configuration partagée dans un emplacement accessible depuis Windows.

// Dans Cursor settings.json (côté Windows)
{
  "cursor.agent.skillsDirectory": "\\\\wsl$\\Ubuntu\\home\\username\\.cursor\\skills",
  "cursor.agent.sharedConfig": true
}
// Dans Cursor settings.json (côté WSL)
{
  "cursor.agent.skillsDirectory": "~/.cursor/skills",
  "cursor.agent.sharedConfig": true
}

Création d'un répertoire de compétences unifié​

Configurez un répertoire de compétences auquel les deux environnements peuvent accéder :

# Dans WSL
mkdir -p ~/.cursor/skills

# Créer un lien symbolique vers un emplacement accessible depuis Windows
# Cela vous permet de modifier les compétences depuis l'un ou l'autre environnement
ln -s ~/.cursor/skills /mnt/c/Users/username/.cursor/skills-wsl

# Exemple : Un fichier de compétence qui fonctionne dans les deux environnements
cat > ~/.cursor/skills/shared-git-workflow.md << 'EOF'
# Shared Git Workflow Skill

## Applies to: Windows Host and WSL

When performing git operations:

1. Always check the current branch first
2. Use conventional commit messages
3. Run tests before committing
4. Push only to feature branches, never to main

## Environment-specific notes:
- On Windows: use Git for Windows (git.exe)
- On WSL: use native Linux git
- Both should reference the same repository
EOF
astuce

Stockez vos compétences dans un dépôt Git et clonez-le dans les deux environnements. Cela garantit que les compétences sont versionnées et synchronisées. Utilisez un sous-module .cursor/skills dans votre dépôt de projet principal pour un partage à l'échelle de l'équipe.

Gestion des différences de chemin​

L'un des plus grands défis dans une configuration à double environnement est la gestion des chemins. Windows utilise des lettres de lecteur (C:\) tandis que WSL utilise des chemins de montage (/mnt/c/). Vous devez en tenir compte dans les configurations d'agent :

// Dans settings.json
{
  "cursor.agent.pathMappings": {
    "windows": {
      "C:\\Users\\username\\projects": "/home/username/projects"
    },
    "wsl": {
      "/home/username/projects": "C:\\Users\\username\\projects"
    }
  }
}
# Exemple de compétence avec instructions de gestion de chemin

## Lors du travail avec des chemins de fichiers :

- Si l'agent s'exécute dans WSL, convertissez les chemins Windows en chemins WSL
  - `C:\Users\username\project` devient `/mnt/c/Users/username/project`
- Si l'agent s'exécute sur l'hôte Windows, convertissez les chemins WSL en chemins Windows
  - `/home/username/project` reste tel quel (répertoire personnel WSL)
  - `/mnt/c/Users/username/project` devient `C:\Users\username\project`

## Détection de l'environnement courant :
- Vérifier si `/proc/version` existe (WSL/Linux)
- Vérifier si `$OS` est `Windows_NT` (Windows)
attention

Ne codez jamais de chemins absolus en dur dans les compétences d'agent. Utilisez toujours des chemins relatifs ou des variables de configuration. Les chemins codés en dur se brisent lors du passage entre l'hôte Windows et l'environnement WSL.

Modèles de développement à distance​

Modèle 1 : Développement WSL principal​

Dans ce modèle, tout le développement se fait dans WSL, et Cursor sur Windows agit comme un client léger :

// settings.json
{
  "remote.WSL.defaultDistro": "Ubuntu",
  "cursor.agent.executionEnvironment": "wsl",
  "cursor.agent.preferWslTerminal": true,
  "files.eol": "\n"
}

C'est la configuration la plus simple et fonctionne bien pour les projets entièrement basés sur Linux, tels que les applications Node.js, Python, Go ou Rust.

Modèle 2 : Développement hybride​

Dans ce modèle, certains outils s'exécutent sur Windows et d'autres dans WSL :

// settings.json
{
  "cursor.agent.executionEnvironment": "auto",
  "cursor.agent.shellRouting": {
    "bash": "wsl",
    "powershell": "windows",
    "cmd": "windows",
    "node": "wsl",
    "python": "wsl",
    "dotnet": "windows"
  }
}
astuce

L'approche hybride est utile lorsque vous avez besoin d'outils spécifiques à Windows (comme le SDK .NET, SQL Server ou des frameworks de test exclusifs à Windows) aux côtés d'outils Linux. Configurez le routage des shells pour choisir automatiquement le bon environnement en fonction de la commande.

Modèle 3 : Développement Docker-first​

Utilisez WSL avec Docker pour une expérience de développement entièrement conteneurisée :

// settings.json
{
  "cursor.agent.executionEnvironment": "wsl",
  "docker.host": "wsl",
  "cursor.agent.preferredContainer": "dev-container",
  "remote.containers.defaultProfile": "WSL: Ubuntu"
}
# Exemple de Dockerfile pour un développement compatible avec les agents
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# Installer des outils supplémentaires
RUN apt-get update && apt-get install -y \
    git \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# Installer les packages npm globaux
RUN npm install -g typescript ts-node nodemon

# Configurer l'espace de travail
WORKDIR /workspace

Modèle 4 : Développement multi-distributions​

Si vous travaillez avec plusieurs distributions Linux, vous pouvez configurer Cursor pour utiliser différentes distributions selon les projets :

// settings.json
{
  "remote.WSL.distros": {
    "Ubuntu": {
      "defaultProfile": "bash",
      "startupCommand": "source ~/.nvm/nvm.sh"
    },
    "Debian": {
      "defaultProfile": "bash",
      "startupCommand": "source /etc/profile.d/rvm.sh"
    }
  }
}
# Lister les distributions installées
wsl --list --verbose

# Changer la distribution par défaut
wsl --set-default Ubuntu

Dépannage des problèmes WSL courants​

L'agent ne trouve pas les fichiers​

Si l'agent signale que des fichiers sont introuvables, vérifiez le format du chemin :

# Format de chemin WSL correct
ls /home/username/project/src/

# Incorrect : utiliser le format de chemin Windows dans WSL
# Cela échouera ou accédera au mauvais emplacement
ls C:\Users\username\project\src\
attention

L'accès cross-filesystem (accéder aux fichiers WSL depuis Windows ou vice versa) est significativement plus lent que l'accès natif. Pour les opérations critiques pour les performances comme l'indexation et la compilation, gardez tous les fichiers dans le système de fichiers WSL (/home/...) plutôt que dans le système de fichiers Windows (/mnt/c/...).

Problèmes de connectivité réseau​

Si l'agent ne peut pas accéder à Internet depuis WSL :

# Tester la connectivité depuis WSL
ping 8.8.8.8
curl -s https://api.github.com | head -5

# Si la résolution DNS échoue, vérifier /etc/resolv.conf
cat /etc/resolv.conf

# S'il est vide ou mal configuré, le réparer :
sudo tee /etc/resolv.conf << 'EOF'
nameserver 8.8.8.8
nameserver 1.1.1.1
EOF

# Si WSL ne peut pas accéder aux services localhost sur Windows
# Vérifier l'IP de l'hôte Windows depuis WSL
ip route show | grep -i default | awk '{print $3}'
# Utiliser cette IP pour accéder aux services Windows depuis WSL

Limites de mémoire et de ressources​

WSL 2 utilise une machine virtuelle avec des limites de ressources configurables. Si les agents sont lents ou à court de mémoire :

# Créer ou éditer le fichier .wslconfig
# Emplacement : C:\Users\username\.wslconfig
# .wslconfig
[wsl2]
memory=12GB
processors=6
swap=4GB
localhostForwarding=true

Après avoir créé ou édité ce fichier :

# Dans PowerShell
wsl --shutdown
# Puis redémarrer Cursor et se reconnecter à WSL
astuce

Surveillez l'utilisation des ressources WSL depuis l'hôte Windows à l'aide du Gestionnaire des tâches. Cherchez le processus "vmmem", qui représente la machine virtuelle WSL 2. S'il utilise constamment 90 % ou plus de la mémoire allouée, augmentez la limite de mémoire dans .wslconfig.

Performance du système de fichiers​

La performance du système de fichiers diffère significativement selon l'endroit où les fichiers sont stockés :

EmplacementVitesse de lectureVitesse d'écritureRecommandation
Accueil WSL (/home/)RapideRapideStocker les fichiers de projet ici
Windows via WSL (/mnt/c/)LentTrès lentÉviter pour les fichiers de projet
Windows natifRapideRapideUniquement pour les outils Windows
# Tester les performances du système de fichiers
# Dans WSL, sur le système de fichiers WSL
dd if=/dev/zero of=/home/$USER/testfile bs=1M count=100 oflag=direct
rm /home/$USER/testfile

# Dans WSL, accédant au système de fichiers Windows
dd if=/dev/zero of=/mnt/c/Users/$USER/testfile bs=1M count=100 oflag=direct
rm /mnt/c/Users/$USER/testfile

Si vous constatez une différence de 5 à 10 fois (courant), déplacez vos fichiers de projet vers le système de fichiers WSL.

Résumé des meilleures pratiques​

  • Utilisez toujours WSL 2, pas WSL 1, pour le travail avec les agents Cursor
  • Installez Cursor sur Windows, pas dans WSL
  • Stockez les fichiers de projet dans le système de fichiers WSL (/home/...) pour de meilleures performances
  • Simplifiez les profils de terminal pour éviter les blocages gatherTerminalSelections
  • Définissez cursor.agent.terminal.autoCreate pour contourner les problèmes de sélection de terminal
  • Partagez les compétences d'agent via un répertoire synchronisé ou un dépôt Git
  • Ne codez jamais de chemins absolus en dur dans les compétences d'agent
  • Configurez .wslconfig avec une allocation de mémoire et de CPU adéquate
  • Utilisez wsl --shutdown pour réinitialiser l'environnement WSL en cas de problème
  • Maintenez votre distribution WSL à jour avec sudo apt update && sudo apt upgrade
attention

Certaines extensions Cursor installées sur l'hôte Windows peuvent ne pas fonctionner correctement en mode WSL. Les extensions doivent être installées séparément pour le distant WSL. Vérifiez le panneau Extensions pour un bouton "Install in WSL" à côté de chaque extension.

Conclusion​

L'exécution d'agents Cursor dans WSL combine la puissance des outils de développement Linux avec le confort du bureau Windows. Bien que la configuration à double environnement introduise des défis en matière de gestion du terminal, de gestion des chemins et d'allocation des ressources, les stratégies de ce guide vous aident à les surmonter.

La clé d'une expérience WSL fluide est la cohérence de la configuration : gardez les profils de terminal simples, assurez-vous que l'intégration shell se charge correctement et maintenez un répertoire de compétences unifié. Lorsque les choses tournent mal, wsl --shutdown suivi d'une reconnexion fraîche de Cursor résout la plupart des problèmes. Avec une configuration appropriée, WSL devient un environnement de développement de première classe pour les agents Cursor, vous donnant accès à l'écosystème Linux complet sans quitter Windows.