Git Worktrees

O Hermes Agent costuma ser usado em repositórios grandes e de vida longa. Quando você quer:

• rodar vários agentes em paralelo no mesmo projeto, ou
• manter refatorações experimentais isoladas da sua branch principal,

as worktrees do Git são o jeito mais seguro de dar a cada agente um clone próprio, sem duplicar o repositório inteiro.

Esta página mostra como combinar worktrees com o Hermes, para cada sessão ter um diretório de trabalho limpo e isolado.

Por que usar worktrees com o Hermes

O Hermes trata o diretório de trabalho atual como a raiz do projeto:

• CLI: o diretório onde você roda hermes ou hermes chat
• Gateways de mensagem: o diretório definido em terminal.cwd, no ~/.hermes/config.yaml

Se você roda vários agentes no mesmo clone, as mudanças de um atrapalham o outro:

• Um agente pode apagar ou reescrever arquivos que o outro está usando.
• Fica difícil entender quais mudanças pertencem a qual experimento.

Com worktrees, cada agente ganha:

• a própria branch e o próprio diretório
• o próprio histórico de checkpoints, para o /rollback

Veja também: Checkpoints e Rollback.

Começando: criar uma worktree

De dentro da sessão: /worktree new

O caminho mais rápido (inspirado no /worktree new do Copilot CLI): numa sessão interativa, rode

/worktree new meu-experimento

O Hermes cria .worktrees/meu-experimento/ dentro do repositório (branch hermes/meu-experimento, baseada na ponta remota recém-buscada, a menos que worktree_sync: false) e reaponta as ferramentas de terminal e de arquivo da sessão para lá — sem reiniciar. Omita o nome para ganhar uma árvore aleatória hermes-<id>. O /worktree sozinho mostra a árvore ativa; /worktree list lista todas. Na saída, a árvore só é mantida se tiver commits não enviados, igual ao hermes -w.

Na mão, com o git

A partir do repositório principal (o que contém o .git/), crie uma worktree para uma branch:

# na raiz do repositório principal
cd /caminho/do/seu/repo

# cria uma branch nova e uma worktree em ../repo-feature
git worktree add ../repo-feature feature/hermes-experimento

Isso cria:

• um diretório novo: ../repo-feature
• uma branch nova: feature/hermes-experimento, com checkout naquele diretório

Agora dá para entrar na worktree e rodar o Hermes lá:

cd ../repo-feature

# começa o Hermes na worktree
hermes

O Hermes vai:

• enxergar ../repo-feature como a raiz do projeto
• usar aquele diretório para arquivos de contexto, edições e ferramentas
• usar um histórico de checkpoints separado, no escopo daquela worktree

Vários agentes em paralelo

Dá para criar várias worktrees, cada uma com a própria branch:

cd /caminho/do/seu/repo

git worktree add ../repo-experimento-a feature/hermes-a
git worktree add ../repo-experimento-b feature/hermes-b

Em terminais separados:

# Terminal 1
cd ../repo-experimento-a
hermes

# Terminal 2
cd ../repo-experimento-b
hermes

Cada processo do Hermes:

• trabalha na própria branch (feature/hermes-a e feature/hermes-b)
• grava checkpoints sob um repositório-sombra diferente (derivado do caminho da worktree)
• usa o /rollback de forma independente, sem afetar o outro

Isso é útil principalmente para:

• refatorações em lote
• tentar abordagens diferentes para a mesma tarefa
• parear sessões de CLI e de gateway contra o mesmo repositório remoto

Limpar worktrees com segurança

Quando você terminar um experimento:

1. Decida se vai manter ou descartar o trabalho.
2. Para manter, incorpore a branch na principal, como de costume.
3. Remova a worktree:

cd /caminho/do/seu/repo

# remove o diretório da worktree e a referência a ela
git worktree remove ../repo-feature

Observações:

• O git worktree remove se recusa a remover uma worktree com mudanças não commitadas, a não ser que você force.
• Remover a worktree não apaga a branch; use os comandos normais de git branch para apagar ou manter.
• Os dados de checkpoint em ~/.hermes/checkpoints/ não são limpos sozinhos quando você remove uma worktree, mas costumam ser bem pequenos.

Boas práticas

• Uma worktree por experimento
  • Crie uma branch e uma worktree dedicadas a cada mudança relevante.
  • Isso mantém os diffs focados e os pull requests pequenos e revisáveis.
• Nomeie as branches pelo experimento
  • Por exemplo, feature/hermes-docs-checkpoints, feature/hermes-refatorar-testes.
• Faça commit com frequência
  • Use commits do git para os marcos importantes.
  • Use checkpoints e o /rollback como rede de segurança para as edições feitas pelas ferramentas no meio do caminho.
• Evite rodar o Hermes na raiz do repositório principal quando usar worktrees
  • Prefira os diretórios das worktrees, para cada agente ter um escopo claro.

Usando o hermes -w (modo automático)

O Hermes tem a opção -w, que cria uma worktree descartável automaticamente, com branch própria. Não é preciso montar worktree na mão — entre no repositório e rode:

cd /caminho/do/seu/repo
hermes -w

O Hermes vai:

• criar uma worktree temporária em .worktrees/, dentro do repositório
• fazer checkout de uma branch isolada (hermes/hermes-<hash>, por exemplo)
• rodar a sessão inteira dentro dela

É o jeito mais fácil de conseguir isolamento. Também dá para combinar com uma pergunta única:

hermes -w -z "Corrija a issue #123"

Para agentes em paralelo, abra vários terminais e rode hermes -w em cada um — cada invocação ganha worktree e branch próprias, sozinha.

Juntando tudo

• Use worktrees do git para dar a cada sessão um clone limpo.
• Use branches para registrar o histórico de alto nível dos experimentos.
• Use checkpoints e /rollback para se recuperar de erros dentro de cada worktree.

A combinação rende:

• garantia forte de que agentes e experimentos diferentes não se atropelam
• ciclos de iteração rápidos, com recuperação fácil de edições ruins
• pull requests limpos e revisáveis

Desenvolver as interfaces em várias worktrees

As superfícies em TypeScript (ui-tui/, apps/desktop/) precisam cada uma de um node_modules, e um npm ci novo por worktree duplica isso em toda branch. Se você mexe na TUI ou no aplicativo desktop a partir de várias worktrees, veja TUI e Desktop a partir de Worktrees, com os auxiliares htui e hgui, que compartilham uma instalação só por link simbólico.