Usando Agentes do Cursor com WSL no Windows

Guia de Agentes Remotos WSL do Cursor

O Windows Subsystem for Linux (WSL) permite executar um ambiente Linux diretamente no Windows, combinando o melhor de ambas as plataformas. Executar agentes do Cursor dentro do WSL permite usar ferramentas Linux nativas, gerenciadores de pacotes e sistemas de compilação enquanto mantém a familiaridade do desktop Windows. No entanto, a interação entre o host Windows e o ambiente WSL introduz desafios únicos, especialmente em relação ao manuseio de terminal e execução de agentes. Este guia abrange tudo, desde a configuração inicial até a solução de problemas avançada.

Pré-requisitos

Antes de configurar o Cursor com WSL, certifique-se de ter o seguinte:

Windows 11 (recomendado) ou Windows 10 com as últimas atualizações
WSL 2 instalado e configurado (execute wsl --install em um PowerShell elevado)
Uma distribuição Linux instalada (Ubuntu é o padrão e a mais testada)
Cursor instalado no host Windows (não dentro do WSL)
Recursos de sistema suficientes: pelo menos 8GB de RAM e 20GB de espaço livre em disco

dica

Use WSL 2 em vez de WSL 1. O WSL 2 fornece um kernel Linux completo com melhor desempenho e compatibilidade. Verifique sua versão com wsl -l -v no PowerShell. Se vir a versão 1, faça upgrade com wsl --set-version <DistroName> 2.

Configuração do WSL para o Cursor

Instalando e Configurando o WSL

Se você ainda não instalou o WSL, siga estas etapas:

# Execute em um PowerShell elevado (Executar como Administrador)
wsl --install

# Isso instala o WSL 2 com a distribuição padrão do Ubuntu
# Reinicie seu computador quando solicitado

# Após a reinicialização, configure seu usuário Linux e senha
# Em seguida, verifique a instalação
wsl --list --verbose

Saída esperada:

  NAME      STATE           VERSION
* Ubuntu    Running         2

Instalando Ferramentas de Desenvolvimento no WSL

Depois que o WSL estiver configurado, instale as ferramentas de desenvolvimento que seu projeto precisa dentro do ambiente Linux:

# Dentro do WSL, atualize as listas de pacotes
sudo apt update && sudo apt upgrade -y

# Instale ferramentas de desenvolvimento comuns
sudo apt install -y build-essential git curl wget unzip

# Instale 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

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

# Instale 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

# Instale Docker (opcional, para desenvolvimento em contêineres)
sudo apt install -y docker.io
sudo usermod -aG docker $USER

aviso

Não instale o Cursor dentro do WSL. O Cursor deve ser instalado no host Windows. Ele se conecta ao WSL como um ambiente remoto, semelhante a como se conecta a remotos SSH. Instalar o Cursor dentro do WSL resultará em problemas de exibição e funcionalidade GUI ausente.

Conectando o Cursor ao WSL

O Cursor tem suporte WSL integrado através da extensão Remote Development:

Abra o Cursor no Windows
Abra a Paleta de Comandos (Ctrl+Shift+P)
Digite e selecione: WSL: Connect to WSL
Escolha sua distribuição instalada (por exemplo, Ubuntu)
O Cursor será recarregado e conectado ao ambiente WSL

Alternativamente, você pode abrir um projeto WSL diretamente do terminal:

# Do Windows PowerShell ou Prompt de Comando
cd \\wsl$\Ubuntu\home\username\my-project
cursor .

Ou de dentro do WSL:

# Navegue até o diretório do seu projeto
cd ~/my-project

# Inicie o Cursor conectado a este caminho WSL
cursor .

dica

Crie um atalho ou alias do Windows que abra o Cursor no seu diretório inicial do WSL para acesso rápido:

# Adicionar ao seu perfil do PowerShell
function cursor-wsl { wsl -e bash -c "cd ~ && cursor ." }

Isso permite que você digite cursor-wsl no PowerShell para abrir o Cursor no seu diretório inicial do WSL instantaneamente.

Configuração do Terminal

Compreendendo o Comportamento do Terminal no WSL

Quando o Cursor é executado no modo WSL, o terminal integrado pode operar em dois modos:

Terminal WSL: Executa comandos dentro do ambiente Linux (padrão)
Terminal Windows: Executa comandos no host Windows

O modo do terminal afeta como os agentes interagem com o sistema. Os agentes normalmente executam comandos no terminal WSL, mas algumas operações podem precisar ser executadas no host Windows.

Configurando o Terminal Padrão

// Em settings.json (acessível 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"
    }
  },
  // Garantir que o Cursor use o shell WSL para comandos de agente
  "cursor.agent.shell": "wsl",
  "cursor.agent.shellPath": "/bin/bash"
}

Restaurando um Terminal Quebrado

Um problema comum em configurações WSL é um terminal quebrado ou não responsivo. O terminal pode exibir mensagens de erro, falhar ao iniciar ou mostrar saída corrompida. Veja como corrigi-lo:

# Passo 1: Verificar se o processo do terminal está em execução
# Paleta de Comandos: Terminal: Select Default Profile

# Passo 2: Verificar se o caminho do shell está correto
# O caminho deve apontar para um shell válido dentro do WSL

// Correção comum: definir explicitamente o caminho do shell
{
  "terminal.integrated.shell.linux": "/bin/bash",
  "terminal.integrated.env.linux": {
    "TERM": "xterm-256color",
    "COLORTERM": "truecolor",
    "LANG": "en_US.UTF-8"
  }
}

Se o terminal estiver completamente sem resposta:

Feche todas as instâncias de terminal no Cursor
Abra a Paleta de Comandos e execute: Terminal: Restart Terminal Server
Se isso não funcionar, recarregue a janela: Developer: Reload Window
Como último recurso, reinicie o Cursor completamente

aviso

Se o terminal mostrar "The terminal process failed to launch" ou "exec bash: no such file or directory", a integração WSL está quebrada. Isso geralmente acontece após uma atualização do Windows ou uma mudança de distribuição WSL. Execute wsl --shutdown no PowerShell e reconecte o Cursor ao WSL.

Resolvendo Travamentos de Agentes em gatherTerminalSelections

Compreendendo o Problema

Um dos problemas mais relatados com WSL e agentes do Cursor é o travamento gatherTerminalSelections. Quando um agente tenta interagir com o terminal, ele chama uma função interna chamada gatherTerminalSelections para determinar qual terminal usar. Em ambientes WSL, essa função pode travar indefinidamente, fazendo com que o agente congele.

Sintomas

O agente começa a executar uma tarefa, mas trava na etapa de interação com o terminal
A barra de status mostra "Agent is working..." indefinidamente
Nenhuma saída de terminal aparece
O agente eventualmente atinge o tempo limite ou requer cancelamento manual
O console de desenvolvedor do Cursor pode mostrar uma promise gatherTerminalSelections pendente

Causas Raiz

O travamento normalmente ocorre devido a uma das seguintes razões:

Múltiplos perfis de terminal: O Cursor não consegue decidir qual perfil de terminal usar
Scripts de integração de shell: O script de integração de shell falha ao carregar no WSL
Problemas de alocação PTY: A alocação de pseudo-terminal do WSL difere do Linux nativo
Conflitos de variáveis de ambiente: Variáveis de ambiente do Windows vazam para o WSL e causam conflitos

Solução 1: Simplificar Perfis de Terminal

Reduza o número de perfis de terminal para evitar ambiguidade de seleção:

// Em settings.json
{
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "/bin/bash",
      "args": ["-l"]
    }
  },
  "terminal.integrated.defaultProfile.linux": "bash",
  // Desativar outros perfis que possam confundir o agente
  "terminal.integrated.profiles.windows": {},
  "terminal.integrated.detectableProfiles": false
}

dica

Após alterar as configurações de perfil de terminal, recarregue a janela do Cursor. O cache de seleção de terminal do agente é limpo no recarregamento, o que frequentemente resolve o travamento na próxima execução do agente.

Solução 2: Corrigir Integração de Shell

A integração de shell permite que o agente rastreie a saída de comandos. No WSL, o script de integração pode não carregar corretamente. Verifique e corrija:

# Dentro do WSL, verificar se a integração de shell está carregada
echo $TERM_PROGRAM

# Deve mostrar: cursor ou vsoc (se estiver usando o terminal Cursor/VS Code)
# Se vazio, a integração de shell não está carregada

# Carregar manualmente o script de integração
# Encontrar o caminho correto:
ls /mnt/c/Users/*/AppData/Local/Programs/cursor/resources/app/out/vs/shell/integration/

# Ou adicionar isto ao seu ~/.bashrc
if [ -n "$CURSOR_IPC_HANDLE" ]; then
  export CURSOR_INTEGRATION_ENABLED=1
fi

Solução 3: Pré-Alocar um Terminal

Criar um terminal dedicado para o agente antes de iniciá-lo pode evitar o travamento de seleção:

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

Isso diz ao Cursor para criar um terminal usando o perfil especificado antes que o agente inicie, ignorando inteiramente o processo de seleção.

Solução 4: Desativar Prompt de Seleção de Shell

Se o travamento for causado por um prompt de seleção que nunca se resolve, desative o prompt:

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

aviso

Desativar o prompt de seleção de terminal significa que o agente sempre usará o perfil de terminal padrão. Se você precisar executar agentes em diferentes ambientes de terminal, precisará alterar o perfil padrão manualmente antes de cada execução.

Unificando Habilidades de Agente Entre Host Windows e WSL

O Desafio

Ao trabalhar com Windows e WSL, você pode ter diferentes ferramentas, configurações e definições de habilidades em cada lado. Isso cria uma experiência fragmentada onde um agente pode saber como fazer algo no host Windows, mas não no WSL, ou vice-versa.

Compartilhando Arquivos de Configuração

A abordagem mais eficaz é compartilhar arquivos de configuração de agente entre os dois ambientes. Como o WSL pode acessar o sistema de arquivos do Windows via /mnt/c/, você pode armazenar a configuração compartilhada em um local acessível pelo Windows.

// Em Cursor settings.json (lado Windows)
{
  "cursor.agent.skillsDirectory": "\\\\wsl$\\Ubuntu\\home\\username\\.cursor\\skills",
  "cursor.agent.sharedConfig": true
}

// Em Cursor settings.json (lado WSL)
{
  "cursor.agent.skillsDirectory": "~/.cursor/skills",
  "cursor.agent.sharedConfig": true
}

Criando um Diretório de Habilidades Unificado

Configure um diretório de habilidades que ambos os ambientes possam acessar:

# Dentro do WSL
mkdir -p ~/.cursor/skills

# Criar um link simbólico para um local acessível pelo Windows
# Isso permite editar habilidades de qualquer ambiente
ln -s ~/.cursor/skills /mnt/c/Users/username/.cursor/skills-wsl

# Exemplo: Um arquivo de habilidade que funciona em ambos os ambientes
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

dica

Armazene suas habilidades em um repositório Git e clone-o para ambos os ambientes. Isso garante que as habilidades sejam versionadas e sincronizadas. Use um submódulo .cursor/skills no seu repositório de projeto principal para compartilhamento em toda a equipe.

Lidando com Diferenças de Caminho

Um dos maiores desafios em uma configuração de ambiente duplo é o manuseio de caminhos. O Windows usa letras de unidade (C:\) enquanto o WSL usa caminhos de montagem (/mnt/c/). Você precisa considerar isso nas configurações do agente:

// Em settings.json
{
  "cursor.agent.pathMappings": {
    "windows": {
      "C:\\Users\\username\\projects": "/home/username/projects"
    },
    "wsl": {
      "/home/username/projects": "C:\\Users\\username\\projects"
    }
  }
}

# Exemplo de habilidade com instruções de manuseio de caminho

## Ao trabalhar com caminhos de arquivo:

- Se o agente estiver executando no WSL, converta caminhos do Windows para caminhos WSL
  - `C:\Users\username\project` torna-se `/mnt/c/Users/username/project`
- Se o agente estiver executando no host Windows, converta caminhos WSL para caminhos do Windows
  - `/home/username/project` permanece como está (diretório inicial do WSL)
  - `/mnt/c/Users/username/project` torna-se `C:\Users\username\project`

## Detectando o ambiente atual:
- Verificar se `/proc/version` existe (WSL/Linux)
- Verificar se `$OS` é `Windows_NT` (Windows)

aviso

Nunca coloque caminhos absolutos fixos nas habilidades do agente. Sempre use caminhos relativos ou variáveis de configuração. Caminhos fixos quebram ao alternar entre o host Windows e o ambiente WSL.

Padrões de Desenvolvimento Remoto

Padrão 1: Desenvolvimento WSL Primário

Neste padrão, todo o desenvolvimento acontece no WSL, e o Cursor no Windows atua como um cliente thin:

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

Esta é a configuração mais simples e funciona bem para projetos totalmente baseados em Linux, como aplicações Node.js, Python, Go ou Rust.

Padrão 2: Desenvolvimento Híbrido

Neste padrão, algumas ferramentas são executadas no Windows e outras no WSL:

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

dica

A abordagem híbrida é útil quando você precisa de ferramentas específicas do Windows (como .NET SDK, SQL Server ou frameworks de teste exclusivos do Windows) junto com ferramentas Linux. Configure o roteamento de shell para escolher automaticamente o ambiente certo com base no comando.

Padrão 3: Desenvolvimento Docker-First

Use WSL com Docker para uma experiência de desenvolvimento totalmente conteinerizada:

// settings.json
{
  "cursor.agent.executionEnvironment": "wsl",
  "docker.host": "wsl",
  "cursor.agent.preferredContainer": "dev-container",
  "remote.containers.defaultProfile": "WSL: Ubuntu"
}

# Exemplo de Dockerfile para desenvolvimento compatível com agente
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# Instalar ferramentas adicionais
RUN apt-get update && apt-get install -y \
    git \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# Instalar pacotes npm globais
RUN npm install -g typescript ts-node nodemon

# Configurar workspace
WORKDIR /workspace

Padrão 4: Desenvolvimento Multi-Distribuição

Se você trabalha com múltiplas distribuições Linux, pode configurar o Cursor para usar distribuições diferentes para projetos diferentes:

// settings.json
{
  "remote.WSL.distros": {
    "Ubuntu": {
      "defaultProfile": "bash",
      "startupCommand": "source ~/.nvm/nvm.sh"
    },
    "Debian": {
      "defaultProfile": "bash",
      "startupCommand": "source /etc/profile.d/rvm.sh"
    }
  }
}

# Listar distribuições instaladas
wsl --list --verbose

# Mudar distribuição padrão
wsl --set-default Ubuntu

Solução de Problemas Comuns do WSL

Agente Não Encontra Arquivos

Se o agente relatar que arquivos não podem ser encontrados, verifique o formato do caminho:

# Formato de caminho WSL correto
ls /home/username/project/src/

# Incorreto: usar formato de caminho Windows no WSL
# Isso falhará ou acessará o local errado
ls C:\Users\username\project\src\

aviso

O acesso entre sistemas de arquivos (acessar arquivos WSL a partir do Windows ou vice-versa) é significativamente mais lento do que o acesso nativo. Para operações críticas de desempenho como indexação e compilação, mantenha todos os arquivos dentro do sistema de arquivos WSL (/home/...) em vez do sistema de arquivos Windows (/mnt/c/...).

Problemas de Conectividade de Rede

Se o agente não conseguir acessar a internet a partir do WSL:

# Testar conectividade a partir do WSL
ping 8.8.8.8
curl -s https://api.github.com | head -5

# Se a resolução DNS falhar, verificar /etc/resolv.conf
cat /etc/resolv.conf

# Se estiver vazio ou mal configurado, corrigir:
sudo tee /etc/resolv.conf << 'EOF'
nameserver 8.8.8.8
nameserver 1.1.1.1
EOF

# Se o WSL não conseguir acessar serviços localhost no Windows
# Verificar o IP do host Windows a partir do WSL
ip route show | grep -i default | awk '{print $3}'
# Usar este IP para acessar serviços Windows a partir do WSL

Limites de Memória e Recursos

O WSL 2 usa uma máquina virtual com limites de recursos configuráveis. Se os agentes estiverem lentos ou ficando sem memória:

# Criar ou editar o arquivo .wslconfig
# Localização: C:\Users\username\.wslconfig

# .wslconfig
[wsl2]
memory=12GB
processors=6
swap=4GB
localhostForwarding=true

Após criar ou editar este arquivo:

# No PowerShell
wsl --shutdown
# Depois reinicie o Cursor e reconecte ao WSL

dica

Monitore o uso de recursos do WSL a partir do host Windows usando o Gerenciador de Tarefas. Procure pelo processo "vmmem", que representa a máquina virtual WSL 2. Se ele usar consistentemente 90%+ da memória alocada, aumente o limite de memória no .wslconfig.

Desempenho do Sistema de Arquivos

O desempenho do sistema de arquivos difere significativamente dependendo de onde os arquivos são armazenados:

Localização	Velocidade de Leitura	Velocidade de Escrita	Recomendação
Home do WSL (`/home/`)	Rápido	Rápido	Armazenar arquivos de projeto aqui
Windows via WSL (`/mnt/c/`)	Lento	Muito Lento	Evitar para arquivos de projeto
Windows nativo	Rápido	Rápido	Apenas para ferramentas do Windows

# Avaliar desempenho do sistema de arquivos
# Dentro do WSL, no sistema de arquivos WSL
dd if=/dev/zero of=/home/$USER/testfile bs=1M count=100 oflag=direct
rm /home/$USER/testfile

# Dentro do WSL, acessando sistema de arquivos Windows
dd if=/dev/zero of=/mnt/c/Users/$USER/testfile bs=1M count=100 oflag=direct
rm /mnt/c/Users/$USER/testfile

Se você vir uma diferença de 5-10x (comum), mova seus arquivos de projeto para o sistema de arquivos WSL.

Resumo das Melhores Práticas

Sempre use WSL 2, não WSL 1, para trabalho com agentes do Cursor
Instale o Cursor no Windows, não dentro do WSL
Armazene arquivos de projeto no sistema de arquivos WSL (/home/...) para melhor desempenho
Simplifique perfis de terminal para evitar travamentos gatherTerminalSelections
Defina cursor.agent.terminal.autoCreate para contornar problemas de seleção de terminal
Compartilhe habilidades de agente via um diretório sincronizado ou repositório Git
Nunca coloque caminhos absolutos fixos nas habilidades do agente
Configure .wslconfig com alocação adequada de memória e CPU
Use wsl --shutdown para redefinir o ambiente WSL quando as coisas derem errado
Mantenha sua distribuição WSL atualizada com sudo apt update && sudo apt upgrade

aviso

Algumas extensões do Cursor instaladas no host Windows podem não funcionar corretamente no modo WSL. Extensões precisam ser instaladas separadamente para o remoto WSL. Verifique o painel de Extensões por um botão "Install in WSL" ao lado de cada extensão.

Conclusão

Executar agentes do Cursor no WSL combina o poder das ferramentas de desenvolvimento Linux com a conveniência do desktop Windows. Embora a configuração de ambiente duplo introduza desafios em torno do manuseio de terminal, gerenciamento de caminhos e alocação de recursos, as estratégias deste guia ajudam você a superá-los.

A chave para uma experiência WSL suave é a consistência de configuração: mantenha perfis de terminal simples, garanta que a integração de shell carregue corretamente e mantenha um diretório de habilidades unificado. Quando as coisas dão errado, wsl --shutdown seguido de uma reconexão nova do Cursor resolve a maioria dos problemas. Com a configuração adequada, o WSL torna-se um ambiente de desenvolvimento de primeira classe para agentes do Cursor, dando acesso ao ecossistema Linux completo sem sair do Windows.

Pré-requisitos​

Configuração do WSL para o Cursor​

Instalando e Configurando o WSL​

Instalando Ferramentas de Desenvolvimento no WSL​

Conectando o Cursor ao WSL​

Configuração do Terminal​

Compreendendo o Comportamento do Terminal no WSL​

Configurando o Terminal Padrão​

Restaurando um Terminal Quebrado​

Resolvendo Travamentos de Agentes em gatherTerminalSelections​

Compreendendo o Problema​

Sintomas​

Causas Raiz​

Solução 1: Simplificar Perfis de Terminal​

Solução 2: Corrigir Integração de Shell​

Solução 3: Pré-Alocar um Terminal​

Solução 4: Desativar Prompt de Seleção de Shell​

Unificando Habilidades de Agente Entre Host Windows e WSL​

O Desafio​

Compartilhando Arquivos de Configuração​

Criando um Diretório de Habilidades Unificado​

Lidando com Diferenças de Caminho​

Padrões de Desenvolvimento Remoto​

Padrão 1: Desenvolvimento WSL Primário​

Padrão 2: Desenvolvimento Híbrido​

Padrão 3: Desenvolvimento Docker-First​

Padrão 4: Desenvolvimento Multi-Distribuição​

Solução de Problemas Comuns do WSL​

Agente Não Encontra Arquivos​

Problemas de Conectividade de Rede​

Limites de Memória e Recursos​

Desempenho do Sistema de Arquivos​

Resumo das Melhores Práticas​

Conclusão​

Pré-requisitos

Configuração do WSL para o Cursor

Instalando e Configurando o WSL

Instalando Ferramentas de Desenvolvimento no WSL

Conectando o Cursor ao WSL

Configuração do Terminal

Compreendendo o Comportamento do Terminal no WSL

Configurando o Terminal Padrão

Restaurando um Terminal Quebrado

Resolvendo Travamentos de Agentes em gatherTerminalSelections

Compreendendo o Problema

Sintomas

Causas Raiz

Solução 1: Simplificar Perfis de Terminal

Solução 2: Corrigir Integração de Shell

Solução 3: Pré-Alocar um Terminal

Solução 4: Desativar Prompt de Seleção de Shell

Unificando Habilidades de Agente Entre Host Windows e WSL

O Desafio

Compartilhando Arquivos de Configuração

Criando um Diretório de Habilidades Unificado

Lidando com Diferenças de Caminho

Padrões de Desenvolvimento Remoto

Padrão 1: Desenvolvimento WSL Primário

Padrão 2: Desenvolvimento Híbrido

Padrão 3: Desenvolvimento Docker-First

Padrão 4: Desenvolvimento Multi-Distribuição

Solução de Problemas Comuns do WSL

Agente Não Encontra Arquivos

Problemas de Conectividade de Rede

Limites de Memória e Recursos

Desempenho do Sistema de Arquivos

Resumo das Melhores Práticas

Conclusão