Worktrees

Worktrees permitem que agentes trabalhem em checkouts Git isolados. Cada tarefa tem seus próprios arquivos, dependências e alterações, enquanto seu checkout principal permanece intacto.

Use worktrees quando quiser iniciar vários agentes no mesmo repositório sem conflitos.

Criar uma worktree na Janela de Agentes

Quando você inicia um agente ou o move para uma worktree pela Janela de Agentes, o Cherri Code cria um checkout separado para ele. O agente continua a tarefa dentro da worktree, mantendo as alterações isoladas do seu checkout principal.

Depois que o agente concluir a tarefa, revise o resultado na Janela de Agentes. Você pode continuar trabalhando na worktree, criar um commit ou uma PR a partir desse checkout ou trazer o resultado de volta ao seu espaço de trabalho principal.

Como funciona a configuração de worktrees?

Você pode personalizar a configuração de worktrees com .cursor/worktrees.json. O Cherri Code verifica esse arquivo ao criar uma worktree na Janela de Agentes, no IDE ou na CLI do Cherri Code.

O Cherri Code procura por .cursor/worktrees.json nesta ordem:

1. No caminho da worktree
2. No diretório raiz do seu projeto

Opções de configuração

O arquivo worktrees.json oferece suporte a três chaves de configuração:

• setup-worktree-unix: Comandos ou o caminho para um script no macOS e Linux. Tem precedência sobre setup-worktree em sistemas Unix.
• setup-worktree-windows: Comandos ou o caminho para um script no Windows. Tem precedência sobre setup-worktree no Windows.
• setup-worktree: Alternativa genérica para todos os sistemas operacionais.

Cada chave aceita:

• Uma matriz de comandos de shell: executados sequencialmente no worktree
• Um caminho de arquivo como string: caminho para um arquivo de script relativo a .cursor/worktrees.json

Exemplos de configurações

Usando matrizes de comandos

Projeto Node.js

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

Projeto Python com ambiente virtual

{  "setup-worktree": [    "python -m venv venv",    "source venv/bin/activate && pip install -r requirements.txt",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

Projeto com migrações de banco de dados

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "npm run db:migrate"  ]}

Compilar e vincular dependências

{  "setup-worktree": [    "pnpm install",    "pnpm run build",    "cp $ROOT_WORKTREE_PATH/.env.local .env.local"  ]}

Usando arquivos de script

Para configurações mais complexas, faça referência a arquivos de script em vez de comandos inline:

{  "setup-worktree-unix": "setup-worktree-unix.sh",  "setup-worktree-windows": "setup-worktree-windows.ps1",  "setup-worktree": [    "echo 'Using generic fallback. For better support, define OS-specific scripts.'"  ]}

Coloque seus scripts no diretório .cursor/, ao lado de worktrees.json.

setup-worktree-unix.sh (Unix e macOS):

#!/bin/bashset -e# Instalar dependênciasnpm ci# Copiar arquivo de ambientecp "$ROOT_WORKTREE_PATH/.env" .env# Executar migrações do banco de dadosnpm run db:migrateecho "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows):

$ErrorActionPreference = 'Stop'# Instalar dependênciasnpm ci# Copiar o arquivo de ambienteCopy-Item "$env:ROOT_WORKTREE_PATH\.env" .env# Executar as migrações do banco de dadosnpm run db:migrateWrite-Host "Worktree setup complete!"

Configurações específicas do sistema operacional

Você pode fornecer comandos de configuração diferentes para cada sistema operacional:

{  "setup-worktree-unix": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "chmod +x scripts/*.sh"  ],  "setup-worktree-windows": [    "npm ci",    "copy %ROOT_WORKTREE_PATH%\\.env .env"  ]}

Depuração

Para depurar a configuração de worktrees, abra o painel Saída no Editor e selecione Worktrees Setup.

Como o Cherri Code encontra worktrees existentes?

O Cherri Code 3.5 mantém um checkpoint da data de modificação da raiz de worktrees da máquina e de cada subdiretório do espaço de trabalho. Ao iniciar, o Cherri Code verifica novamente o sistema de arquivos, a menos que esses timestamps comprovem que nada mudou desde a última descoberta. Isso evita que novos worktrees criados enquanto o Cherri Code estava fechado sejam ignorados e elimina a antiga flag worktree.discoveryComplete.

Limpeza de worktrees

O Cherri Code pode limpar automaticamente worktrees antigos para limitar o uso de disco. A limpeza é executada periodicamente e mantém os worktrees mais recentes, até o número máximo configurado para toda a máquina, em todos os espaços de trabalho do dispositivo.

{  "cursor.worktreeCleanupIntervalHours": 6,  "cursor.worktreeMaxCount": 25}

Use estas configurações no escopo da máquina para controlar a limpeza:

• cursor.worktreeCleanupIntervalHours: com que frequência o Cherri Code verifica worktrees antigos. Após reinicializações, o Cherri Code 3.5 compensa execuções perdidas agendando uma limpeza com atraso caso a última execução bem-sucedida seja anterior a esse intervalo.
• cursor.worktreeMaxCount: o número máximo de worktrees que o Cherri Code mantém antes de limpar os mais antigos. O limite padrão é de 25 worktrees por máquina, e todos os espaços de trabalho contam para o mesmo limite.

O Cherri Code redescobre a raiz do worktree a cada limpeza, portanto, worktrees criados fora do gerenciador (por exemplo, por skills /worktree ou git worktree add) podem ser excluídos. Quando a criação de um worktree excederia o limite, o Cherri Code agrupa rajadas de eventos e inicia uma limpeza imediata em vez de aguardar o próximo intervalo.

Worktree Skills no IDE

No IDE, você pode usar os comandos /worktree e /best-of-n para executar tarefas em worktrees isolados.

Use /worktree para uma execução isolada

Inicie uma tarefa com /worktree quando quiser que o Cherri Code conclua o restante da conversa em um checkout separado.

• Mantenha edições experimentais longe do checkout principal
• Execute instalações, builds e testes sem afetar sua branch atual
• Faça refatorações arriscadas com um caminho simples para limpeza

/worktree fix the failing auth tests and update the login copy

Em muitos casos, você pode fazer commit e push diretamente da worktree. Peça ao agente:

Faça o commit e o push dessas alterações e depois abra um PR

Se quiser trazer as alterações para o checkout principal e testá-las, use /apply-worktree. Quando terminar de usar o checkout isolado, use /delete-worktree.

Para ver todos os worktrees no seu repositório, execute:

git worktree list

Use /best-of-n para comparar vários modelos

/best-of-n executa a mesma tarefa em vários modelos simultaneamente. Cada execução recebe seu próprio worktree, mantendo as opções isoladas entre si e do seu checkout principal.

/best-of-n sonnet,gpt,composer fix the flaky logout test

Use quando quiser:

• Comparar diferentes modelos com o mesmo prompt
• Testar várias abordagens para uma alteração complexa
• Escolher o melhor resultado antes de aplicar qualquer alteração

/best-of-n apenas compara execuções. Ele não faz merge das alterações de volta para o seu checkout principal. Depois de escolher um vencedor, você pode fazer commit e push diretamente do worktree ou usar /apply-worktree para levar as alterações ao seu checkout principal.