Worktrees do Git são checkouts separados de um repositório, com pastas e áreas de trabalho próprias. No Cursor, isso evita que agentes escrevam no mesmo checkout, mas branches diferentes ainda podem alterar o mesmo código. Integrar as mudanças continua exigindo atenção.
Use worktrees para separar o trabalho; revise e teste o resultado quando as branches se encontrarem.
O que os worktrees isolam — e o que acontece na integração
Cada agente pode trabalhar em seu próprio checkout, sem sobrescrever os arquivos de trabalho de outro agente na mesma pasta. Pense em bancadas separadas para tarefas paralelas: a divisão ajuda durante o trabalho, mas não decide como combinar os resultados.
Se duas branches alterarem linhas sobrepostas do mesmo arquivo, o Git pode apontar um conflito que precisa ser resolvido. Mudanças em trechos diferentes podem ser combinadas, mas uma integração sem conflito textual ainda pode deixar erros no código. A documentação do Git sobre conflitos de merge recomenda distinguir a combinação das alterações da correção do programa resultante.
No Cursor, /best-of-n compara execuções feitas em worktrees separados, sem integrar automaticamente as mudanças. Cabe a você escolher um resultado e aplicá-lo. A documentação de worktrees do Cursor descreve esse fluxo.
Worktrees do Cursor: Agents Window, IDE e configuração
O recurso de worktrees integrado à interface do Cursor fica no Agents Window. No IDE, o Cursor documenta comandos de Worktree Skills, entre eles /worktree, /best-of-n, /apply-worktree e /delete-worktree.
Para preparar um worktree, o arquivo .cursor/worktrees.json aceita configurações específicas para Unix e Windows, além de uma configuração genérica. Elas podem conter comandos executados em sequência ou o caminho para um script. O Cursor procura o arquivo primeiro na pasta do worktree e depois na raiz do projeto.
A limpeza também pode incluir worktrees criados manualmente
No Cursor 3.5 ou posterior, a limpeza automática pode incluir worktrees criados fora do gerenciador do Cursor, inclusive com git worktree add. A documentação estabelece um limite padrão de 25 worktrees por máquina; um intervalo de seis horas aparece como exemplo de configuração, não como regra universal.
Quando a troca de worktree interrompe um agente
Em 10 de setembro de 2026, a equipe do Cursor respondeu a um relato de interrupção durante uma tarefa e atribuiu o problema à criação de um worktree e à mudança da pasta-raiz no meio da execução. Como solução para aquele caso, recomendou iniciar o agente na pasta em que o trabalho deveria ocorrer. A equipe também disse que o comando continue retoma uma tarefa interrompida. A resposta da equipe no fórum do Cursor traz essa orientação datada.
