Dois agentes no mesmo working directory é receita para caos: um formata o arquivo que o outro ainda estava editando, o git status vira sopa, e o humano perde a noção de quem quebrou o build. Git worktrees resolvem o isolamento sem clonar o remoto de novo: um .git compartilhado, vários checkouts, cada um numa branch.
Em 2026 isso virou peça central de ADEs como o Orca — e também funciona no terminal “puro” com git worktree.
O problema do working tree único
Agentes escrevem arquivos o tempo todo. Em paralelo, no mesmo tree:
- Conflitos de edição sem merge formal.
- Testes de A falhando por causa do diff sujo de B.
git stashacidental engolindo o trabalho do outro.- Hooks e watchers disparando duas vezes no mesmo path.
Isolar por processo (dois terminais) não isola por filesystem. Worktree isola o filesystem do checkout.
Worktree em 60 segundos
# a partir do repo principal, na branch atual
git fetch origin
# novo checkout em pasta irmã, branch nova a partir de origin/main
git worktree add ../portfolio-fix-login -b fix/login-race origin/main
cd ../portfolio-fix-login
# agente trabalha só aqui
Listar / limpar:
git worktree list
git worktree remove ../portfolio-fix-login
# se a pasta já foi apagada à mão:
git worktree prune
Cada worktree tem sua branch (ou um detach). O objeto store é compartilhado — clones baratos em disco comparado a git clone completo.
Padrão: um agente, um worktree
Regra operacional simples:
| Papel | Worktree |
|---|---|
| Humano no dia a dia | main checkout |
| Agente A (feature) | ../repo-feat-x |
| Agente B (bugfix) | ../repo-fix-y |
| Reviewer read-only | pode ser o mesmo tree do autor se não escrever; senão, tree próprio no commit do autor |
ADE como Orca automatiza: criar worktree, escolher agente (Claude Code, Cursor CLI, OpenCode…), mostrar diff, apagar perdedores. O conceito é o mesmo do comando acima — ver comparação das tools.
Race: três abordagens, um bug
Fluxo que mais paga o isolamento:
- Crie três worktrees a partir do mesmo ref (
origin/main). - Lance três agentes com o mesmo prompt.
- Espere idle / testes.
- Compare diffs.
- Shippe o vencedor; delete os outros worktrees/branches.
Isso é orquestração leve — detalhada em orquestração de agentes de código. O valor não é “três vezes mais tokens”: é diversidade de falha barata de inspecionar.
Cuidados que pegam gente experiente
Dependências por worktree
node_modules não é compartilhado de forma mágica. Em JS/TS, cada worktree costuma precisar do próprio install (yarn / pnpm). Em monorepos grandes, orçamento de disco importa — use cache do package manager.
Portas e processos
Dois next dev → conflito de porta. Padronize PORT=3010, 3011, … por worktree ou mate o servidor ao terminar a task.
Arquivos ignorados e secrets
.env local: copie com cuidado ou use secret manager. Não assuma que o agente “vê” o env do tree principal.
Hooks
husky / pre-commit rodam por tree. Um agente que commit afoito ainda respeita hook — desde que o hook esteja instalado naquele tree.
Branch naming
Prefixos claros (agent/, orca/, wt/) evitam misturar branches humanas com experimentos descartáveis.
Mini playbook sem ADE
REPO=~/Coding/personal/portfolio
PARENT="$(dirname "$REPO")"
BASE=origin/main
NAME=fix-flake-checkout
WT="$PARENT/$NAME"
git -C "$REPO" fetch origin
git -C "$REPO" worktree add "$WT" -b "agent/$NAME" "$BASE"
cd "$WT"
# ex.: claude / cursor agent / opencode — prompt colado aqui
# yarn && yarn test
# se aprovado:
# git push -u origin HEAD
# gh pr create ...
# se descartar:
cd "$REPO"
git worktree remove "$WT"
git branch -D "agent/$NAME"
Ajuste paths ao seu OS; o ponto é ritualizar add → work → pr ou remove.
Ligação com skills e MCP
- Skill de “spawn worktree” deve fixar base ref (
origin/mainvs branch atual). - MCP com estado em
/tmpdeve ser safe sob paralelo. - Rules: “nunca rode dois writers no tree do humano”.
Ver Skills e Rules e MCP.
Checklist
- Cada writer tem seu worktree?
- Base ref explícita no create?
- Ports / installs isolados?
- Plano de limpeza (
remove+ apagar branch)? - Integração (PR) feita por um único dono?
Conclusão
Worktrees são o isolamento barato que agentes exigem. Sem eles, “paralelismo” é só dois processos brigando pelo mesmo disco. Com eles — no git puro ou num ADE — você compara abordagens, pipelineia tasks e mantém o tree humano limpo.
Para o restante do site e projetos: portfolio.