Git worktrees como workspaces do Herdr
Um Git worktree é uma segunda pasta de trabalho ligada ao mesmo repositório, com outra branch em checkout. O Herdr TUI abre cada worktree como um workspace próprio, agrupado abaixo do workspace do repositório, com abas e painéis independentes. Dois agentes ficam em branches diferentes sem disputar os mesmos arquivos.
Uma pasta por branch
O Git guarda o histórico de um repositório numa única pasta .git, mas cada pasta de trabalho só tem uma branch em checkout por vez. Quando dois agentes trabalham no mesmo diretório, os dois editam os mesmos arquivos e enxergam as alterações um do outro antes de qualquer commit. O comando git worktree resolve isso criando outra pasta de trabalho ligada ao mesmo repositório, com a própria branch e o próprio estado dos arquivos.
O Herdr TUI usa esse recurso do Git e acrescenta a camada de interface. Cada worktree aberto vira um workspace normal do Herdr, com abas, painéis, agentes e estado próprios na barra lateral, agrupado abaixo do workspace original do repositório. Você deixa o Claude Code implementando uma funcionalidade num worktree, o Codex corrigindo um teste em outro e acompanha os dois na mesma barra lateral.
Repositório
~/projetos/siteO workspace original, com a branch principal em checkout.
Worktree da funcionalidade
<raiz>/site/nova-paginaWorkspace agrupado, com um agente na branch nova-pagina.
Worktree da correção
<raiz>/site/corrige-testeOutro workspace agrupado, com outro agente em outra branch.
Onde as pastas ficam
Os worktrees criados pelo Herdr ficam, por padrão, em ~/.herdr/worktrees/<repositório>/<branch>, com o nome da branch convertido para um nome de pasta seguro. A chave directory, na seção [worktrees] do arquivo de configuração, troca essa raiz. Para manter os worktrees perto dos projetos, você aponta a chave para uma pasta como ~/Projects/herdr-worktrees. Valores relativos viram caminhos absolutos quando o Herdr aplica a configuração.
Pela interface, as ações de worktree aparecem nas linhas de workspace que estão num repositório Git. A ação de novo worktree recebe o nome da branch: quando a branch local já existe, o Herdr faz o checkout dela. Quando não existe, o Herdr cria a branch nova. A ação de abrir worktree lista as pastas de worktree que o repositório já tem, foca a que estiver aberta e abre no mesmo grupo a que estiver fechada.
Os comandos de worktree
A linha de comando do Herdr tem quatro comandos para worktrees, que conversam com o servidor pela Socket API. Eles servem tanto para uso manual quanto para scripts que preparam o ambiente de uma tarefa:
herdr worktree create --branch nova-paginaCria o worktree, abre como workspace e agrupa abaixo do repositório.Cria a pasta de trabalho e, quando necessário, a branch a partir de --base ou do HEAD.herdr worktree open --branch nova-paginaAbre um worktree que já existe como workspace do grupo.Nenhum, a pasta já existia.herdr worktree listLista os workspaces de worktree do repositório.Nenhum, só consulta.herdr worktree remove --workspace w2Remove a pasta de trabalho do worktree pelo git worktree remove.Apaga a pasta. A branch continua no repositório.O create aceita --path para escolher a pasta, --label para o nome do workspace e --no-focus para criar sem tirar o foco do painel atual, opção útil quando um agente prepara o worktree de outro. Os comandos devolvem JSON com os identificadores do workspace criado, que o script usa nos passos seguintes.
Fechar e remover são ações diferentes
Fechar um workspace de worktree, com herdr workspace close ou pela interface, encerra só o estado do Herdr: a pasta e a branch continuam no disco. Fechar a linha do repositório original fecha o grupo inteiro de workspaces, também sem apagar pastas nem branches. Pela linha de comando, fechar o workspace principal com worktrees ligados exige a opção --group. Sem ela, o comando devolve o erro workspace_group_close_required e deixa o grupo aberto.
Repositórios de outro usuário
O Git recusa, por padrão, repositórios cujo dono é outro usuário do sistema, situação comum em servidores com pastas compartilhadas. Os comandos de worktree do Herdr aceitam --trust-repository para confiar no caminho resolvido daquele repositório só durante aquele comando, depois que você conferiu de onde vem o repositório. O Herdr não altera a configuração global do Git ao aceitar essa opção.
O procedimento de criar um worktree pela interface, abrir um agente nele e conferir a branch está no tutorial Abra uma branch em outro workspace. A coordenação de vários agentes por script, cada um no próprio worktree, aparece na página Automação e plugins.