Guia prático de Codex Worktree: desenvolva várias tarefas de IA em paralelo sem poluir o repositório

No mesmo repositório, três tarefas estão rodando ao mesmo tempo: fix/auth-expired-session, test/payment-webhook e docs/setup-node20. O git status do main checkout vira uma mistura de mudanças sem relação: correção de bug de login, arquivos de test fixture e uma nota no README sobre Node 20. Os três tipos de alteração estão em um único checkout, e você já não sabe qual parte pode ser commitada sozinha nem qual pode afetar as outras.

Isso não é um problema abstrato de paralelismo. É a consequência real de um Git checkout poluído. O modo Worktree do Codex app separa tarefas diferentes em diretórios e branches diferentes, para que cada linha de trabalho tenha um diff que possa ser revisado, mergeado ou revertido.

Local / Worktree / Cloud: como escolher o modo certo

O Codex app oferece três modos de execução. Local e Worktree rodam no seu computador. A documentação oficial diz diretamente: “Both Local and Worktree threads will run on your computer”. Já Cloud roda em um ambiente remoto.

O modo Worktree combina com tarefas paralelas independentes ou experimentos. Cada thread tem seu próprio diretório e branch, então o main checkout não é afetado. Local é simples, mas quando várias tarefas se misturam, separar commits fica difícil. Cloud sai completamente da sua máquina e combina com CI/CD e builds remotos.

A regra de escolha: use Local para uma tarefa, Worktree para trabalho local paralelo ou experimental, e Cloud para trabalho remoto.

O modo Worktree do Codex app em detalhes

Criação de Worktree e Handoff

O fluxo para criar um Worktree thread no Codex app é:

1. Criar um novo thread
2. Escolher o modo Worktree (o nome exato na UI pode mudar depois de 18/06/2026)
3. Escolher um branch inicial ou trabalhar por padrão em detached HEAD
4. Enviar o primeiro prompt
5. O Codex começa a trabalhar em um diretório isolado

Por padrão, o Codex trabalha em detached HEAD. Isso permite continuar dentro do worktree e criar um branch quando você quiser preservar o resultado. Handoff serve para mover thread e código entre Local e Worktree.

Cenários de Handoff:

De Worktree para Local: depois que a tarefa terminar, crie primeiro um branch dentro do worktree se ele ainda estiver em detached HEAD. Depois use Handoff para voltar para Local e, por fim, faça merge ou crie uma PR.

De Local para Worktree: quando você quer mover trabalho inacabado para um ambiente isolado e evitar poluir o main checkout.

Handoff não é só trocar de diretório. Ele leva junto o contexto do thread, o histórico de prompts e as alterações inacabadas.

Características dos Codex-managed worktrees

Codex-managed worktrees têm alguns comportamentos específicos:

Local padrão: $CODEX_HOME/worktrees

Quantidade mantida por padrão: 15 worktrees (segundo a documentação de 18/06/2026); os mais antigos podem ser limpos automaticamente

Permanent worktree: worktrees criados manualmente não são apagados automaticamente

Limitação de branch: o Git não permite que o mesmo branch fique checked out em vários worktrees ao mesmo tempo; tentar fazer isso gera erro

Herança de regras: AGENTS.override.md é copiado automaticamente para o worktree, mantendo as regras do projeto consistentes

Na prática: a quantidade de worktrees tem limite, os antigos podem ser limpos, o mesmo branch não pode ser usado em paralelo e as regras do projeto são herdadas.

.worktreeinclude resolve o problema de arquivos ignorados

Por padrão, worktrees herdam apenas Git tracked files. Arquivos em .gitignore não são movidos automaticamente durante Handoff. Itens que costumam faltar: .env, .env.local, caches de dependências e arquivos de configuração local.

A solução é criar um arquivo .worktreeinclude na raiz do projeto e listar os arquivos ignorados que devem ser copiados. Exemplo:

.env
.env.local
node_modules/.cache

Com isso, os arquivos ignorados listados ali também podem ser copiados para o worktree durante Handoff.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Setup scripts: fazer o projeto rodar dentro de um worktree

Um worktree fica em outro diretório, então pode faltar dependências ou arquivos que nunca entraram no repositório. Setup scripts rodam quando um novo worktree ou thread é criado, deixando o ambiente utilizável.

Etapas de configuração:

1. Configurar setup steps em Local environments no Codex app
2. Criar um diretório .codex para arquivos de configuração
3. Escrever scripts específicos por plataforma

Exemplo de projeto Node.js:

# .codex/setup.sh
npm install
npm run build

Exemplo de projeto Python:

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Setup scripts rodam em cada novo worktree e reduzem instalação manual de dependências. A UI de configuração e o formato de arquivos podem mudar depois de 18/06/2026, então confira a documentação atual antes de depender de nomes exatos.

Sem Codex app, Plain Git worktree também isola

Se você prefere CLI ou terminal, pode criar diretórios isolados diretamente com Git worktree e iniciar o Codex dentro de cada diretório. Você não precisa da gestão do Codex app, mas toda a administração fica por sua conta.

Comandos comuns de Git worktree:

# Criar um novo worktree e branch, no estilo do caso de uso oficial
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# Criar um novo worktree a partir de um branch existente
git worktree add ../task-b existing-branch

# Listar todos os worktrees
git worktree list

# Remover um worktree
git worktree remove ../task-a

# Limpar metadados antigos de worktree
git worktree prune

Comparação entre Codex-managed e Plain Git:

Plain Git worktree combina com desenvolvedores que gostam de CLI, mas você precisa cuidar de instalação de dependências, configuração de ambiente e limpeza. Codex-managed worktrees automatizam mais dessa parte.

Automations em segundo plano devem usar worktree?

Em um repositório Git, uma automation pode rodar no local project ou em um dedicated background worktree. A escolha depende do tipo de tarefa e do controle de risco.

Lógica de decisão:

Local serve para tarefas únicas e testes temporários. Ele edita diretamente o main checkout, então pode poluir trabalho inacabado. Se você está editando um arquivo, uma background automation pode modificar o mesmo arquivo.

Worktree serve para tarefas repetidas ou agendadas. Ele separa automation changes de unfinished local work. A automation roda em um diretório independente e não afeta o main checkout.

Notas de risco:

Automations usa default sandbox settings, que podem mudar depois de 18/06/2026

Com full access, background automations são mais arriscadas, então devem usar worktree

Não rode tarefas repetidas em segundo plano diretamente em Local

Princípio: uma tarefa temporária única pode usar Local; tarefas repetidas e trabalho em segundo plano com full access devem usar Worktree.

Quais tarefas podem rodar em paralelo e quais precisam ser sequenciais

Casos de uso oficiais recomendam separar explorações diferentes em worktrees diferentes. Na prática, ainda é preciso julgar conflitos de arquivos e dependências entre tarefas.

Tabela de decisão para tarefas paralelas:

Regras de paralelismo:

Comece com duas tarefas pequenas e independentes, não com cinco ou seis.

Mantenha o número de tarefas em 3-4 para reduzir o custo de revisão.

Cada tarefa precisa de um alvo claro de verificação.

Não exagere no paralelismo. Quanto mais tarefas paralelas, maior o custo de revisão e o risco de merge conflict.

Modelo de cartão de tarefa: escreva o que cada worktree deve fazer

Antes de iniciar um worktree, descreva claramente a tarefa para facilitar revisão e acompanhamento.

Exemplo de cartão de tarefa:

Goal: "Corrigir o bug session expired no módulo auth"
Context:
  - "A sessão expira depois de 30 minutos, mas o frontend não mostra aviso"
  - "Arquivos relacionados: src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "Não alterar o schema do banco de dados"
  - "Não adicionar nova dependência"
Done when:
  - "O frontend mostra aviso quando a sessão expira"
  - "npm test passa"
  - "O fluxo de login foi testado manualmente"

Branch/Worktree: "fix/auth-expired-session"
Comando de verificação: "npm test && npm run lint"

Pontos a preencher:

Goal: descreva o objetivo em uma frase

Context: forneça contexto de arquivos, módulo e histórico

🔥 Não perca meses em produtos sem demanda! Valide as propostas do seu SaaS com a Adsterra e pouco orçamento →

Testar agora →Anúncio

Constraints: defina limites, inclusive o que não deve mudar

Done when: liste critérios de conclusão verificáveis

Branch/Worktree: use um nome claro, como task-type/module-description

Comando de verificação: dê um comando concreto e executável

Assim cada worktree tem limites claros. Na revisão, compare o resultado com Done when.

Fila de merge: revisar, testar e fazer merge um de cada vez

Quando tarefas paralelas terminarem, não jogue tudo em main de uma vez. Ordene por risco, depois revise, teste e faça merge uma por uma.

Etapas da fila de merge:

1. Ordenar worktrees por risco, começando pelo menor
2. Para o primeiro worktree:
   • Rodar o comando de verificação: testes, lint
   • Verificar o diff e confirmar o escopo da mudança
   • Criar um branch se ainda estiver em detached HEAD
   • Revisar o diff seguindo suas regras de PR review
3. Fazer merge em Local ou criar uma PR:
   • Merge local: Handoff de volta para Local e depois merge
   • Merge por PR: criar uma PR e aguardar CI e review
4. Repetir o processo para o próximo worktree
5. Depois que tudo terminar, fazer merge no branch main

Checklist de verificação:

Comandos de verificação passam: testes e lint

Checagem de diff: o escopo das mudanças bate com a tarefa

Review guidelines: sem arquivos sensíveis e sem secrets hard-coded

CI passa, se existir

Fluxo de teste manual concluído

Notas de risco:

Não prometa merge automático dos resultados de vários worktrees

Se várias tarefas editarem o mesmo arquivo, resolva conflitos manualmente

Mantenha revisão humana e testes no fluxo

O objetivo de uma fila de merge é deixar o diff de cada linha de trabalho revisável e reversível, não enviar todas as mudanças de uma vez.

Checklist de troubleshooting

Erro "branch already used by worktree"

Causa: o branch já está ocupado por outro worktree

Solução:

Use git worktree list para ver quais branches estão ocupados

Escolha outro branch ou remova o worktree que está usando esse branch

O código não roda dentro do worktree

Causa: faltam dependências ou arquivos de configuração

Passos de diagnóstico:

Verifique se .env e .env.local existem; talvez não tenham sido copiados

Verifique se as dependências estão instaladas, como node_modules ou venv

Verifique se os arquivos de configuração estão completos

Solução:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Configure .worktreeinclude para copiar ignored files

Configure Setup scripts para instalar dependências automaticamente

O uso de disco dos worktrees cresce demais

Causa: automations frequentes criam muitos worktrees

Solução:

Archive automation runs que você não precisa mais

Rode manualmente git worktree prune para limpar worktrees obsoletos

Verifique a configuração de retenção de worktrees no Codex app, que pode mudar depois de 18/06/2026

Worktree criado pelo agent não sincroniza com UI/thread context

Causa: quando o agent cria um worktree automaticamente, ele pode contornar a App UI

Solução:

Use git worktree list para inspecionar todos os worktrees

Verifique manualmente no app a associação entre thread e worktree

Evite pedir ao agent para criar worktrees automaticamente; crie pela App UI

O hábito básico de troubleshooting é primeiro inspecionar o estado dos worktrees com git worktree list e depois agir conforme o tipo de erro.

Custo: tarefas paralelas consomem quota mais rápido

Tarefas paralelas tendem a consumir mais turns ou quota. Cada worktree é uma session independente, e o Codex contabiliza cada session separadamente.

Regras de custo:

Mantenha tarefas paralelas em torno de 3-4.

Comece com duas tarefas pequenas e independentes para reduzir o custo de revisão.

Dê a cada tarefa um alvo claro de verificação para evitar iteração infinita.

Para preços, quota e detalhes de plan, use um futuro artigo de Cost & Quota. Esta página não repete números não verificados.

Próximos passos e leituras relacionadas

Artigos anteriores:

Escolha de entrada no Codex: breve introdução aos modos Local / Worktree / Cloud

Regras de projeto AGENTS.md: como cada worktree herda o mesmo conjunto de regras do projeto