Criação de Sessões e Colaboração no Git

Dois recursos que funcionam em conjunto: separar subtarefas em sessões filhas independentes (opcionalmente em worktrees Git isolados) e um merge gráfico que reúne as branches paralelas. Juntos, eles permitem que vários agentes trabalhem no mesmo repositório em paralelo.

1. O que significa iniciar uma sessão filha

De dentro de qualquer sessão, você pode separar uma subtarefa. O VelaTerm cria uma nova sessão filha abaixo do nó atual (a árvore passa a ter hierarquia: pai → filha → neta), opcionalmente atribui a ela um worktree Git isolado e envia a descrição da tarefa como a primeira mensagem da nova sessão. O novo agente começa a trabalhar assim que é iniciado, sem precisar de mais explicações.

O resultado é uma sessão real na árvore, com processo próprio, que você pode acompanhar, responder, reabrir e retomar a qualquer momento. Não se trata de uma tarefa oculta em segundo plano.

Para trabalhos que devem ser planejados, executados e revisados por agentes diferentes, use um fluxo de planejamento e execução; consulte Planejamento e Execução.

2. Formas de iniciar uma sessão filha

Os dois comandos estão disponíveis em todas as sessões iniciadas pelo VelaTerm. As habilidades do agente exigem as Vela Skills: escolha "Install" em Configurações ▸ Geral e depois inicie uma nova conversa do Claude Code ou do Codex para que o agente passe a reconhecê-las. Os agentes só chamam essas habilidades quando você pede.

Uma nova sessão não vê a conversa de onde veio. Quando você usa a habilidade, o agente inclui na tarefa o objetivo, os arquivos relevantes, as conclusões até o momento, as restrições e os critérios de aceitação. Quando você mesmo executa o comando, inclua essas informações no texto da tarefa.

3. Diretório, agente e modelo

• Diretório. A sessão filha começa no diretório em que o comando é executado, que também é o repositório usado para o worktree. Use --cwd <path> para trabalhar em outro projeto, por exemplo vspawn-tree --cwd /work/project "fix the parser". Isso é importante em uma coleção, que não tem pasta de projeto própria. As habilidades adicionam --cwd quando a conversa identifica claramente um repositório.
• Agente. A sessão filha usa o mesmo agente da sessão atual; a partir de um terminal comum, é iniciado o Claude Code. --claude, --codex, --copilot ou --kiro escolhem outro agente, e o cartão de confirmação oferece todos os tipos de agente.
• Modelo e esforço. --model <name> e --effort <level> definem o modelo e o esforço de raciocínio da sessão filha, por exemplo vspawn --model opus --effort high "port the parser". Os nomes de modelo são os do agente que será executado. Uma configuração que o agente não aceita é rejeitada antes de a sessão ser criada. Sem essas opções, uma sessão filha do mesmo tipo de agente herda os argumentos de inicialização e a configuração de permissão da sessão pai; uma sessão filha de outro tipo usa os padrões desse agente definidos em Configurações ▸ Agentes.
• Visão. Uma sessão filha compatível com a visão de conversa abre na mesma visão da sessão pai, quando esta também é compatível; caso contrário, abre na visão padrão do agente.

Todas as opções estão listadas em Comandos de Sessão §3.

4. Confirmação antes de iniciar

Por padrão, toda solicitação de sessão filha mostra primeiro um cartão de confirmação com o título "Iniciar sessão filha". O cartão não tira o foco da sessão em que você está trabalhando, e uma notificação do sistema ("Sessão filha aguardando confirmação") avisa que há uma solicitação esperando.

• O cartão mostra a sessão que fez a solicitação e o diretório dela ("Sessão solicitante"), as "Instruções da tarefa", que se tornam a primeira mensagem da sessão filha, as "Configurações de execução" ("Tipo de sessão", "Modelo", "Esforço de raciocínio") e a escolha do "Diretório de trabalho": "Diretório atual" ou "Worktree separado".
• As sugestões de modelo vêm do agente selecionado. Se não houver uma lista disponível, você pode digitar um identificador de modelo. Deixar um campo em "Padrão do agente" faz com que a configuração do próprio agente seja usada.
• Um terminal comum abre no diretório de trabalho; ele não executa as instruções da tarefa.
• "Iniciar sessão" (ou ⌘Enter / Ctrl+Enter) inicia a sessão filha; "Cancelar" descarta a solicitação. As demais solicitações aguardam em uma fila, e o cartão mostra quantas ainda faltam ("Mais N solicitações para revisar").

Para iniciar as solicitações sem o cartão, desative "Confirm before spawn" em Configurações ▸ Comportamento ou adicione --yes a um comando específico.

5. Worktrees: trabalho em paralelo sem conflitos

Com um worktree, a sessão filha trabalha em uma nova branch, em um diretório próprio, isolada do espaço de trabalho principal e das outras sessões filhas. Essa é a configuração recomendada quando vários agentes alteram o mesmo repositório ao mesmo tempo. Os novos worktrees partem do commit atual e não incluem alterações não commitadas. Se não for possível criar um worktree para uma sessão filha, a sessão usa o diretório original.

Uma sessão que trabalha em um worktree mostra um pequeno selo no ícone dela na barra lateral; passe o cursor sobre ele para ver o nome e o caminho do worktree.

Outras formas de trabalhar com worktrees:

• "Nova sessão de worktree…", no menu de projeto, grupo ou sessão, abre a caixa de diálogo de criação com a opção "Worktree" definida como "Novo". Informe um "Nome do worktree", que é usado para o diretório e para a branch. A caixa de diálogo também pode vincular a sessão a um worktree "Existente" ou usar "Nenhum".
• "Mover para um worktree…", no menu de um grupo, vincula o grupo a um worktree novo ou existente. As sessões criadas no grupo a partir desse momento usam esse worktree; as que já estavam nele mantêm o próprio diretório. Um grupo com worktree também oferece "Informações do grupo".

O submenu Git de uma sessão ou de um grupo cujo diretório é um repositório Git contém:

Depois que um worktree vinculado é excluído, o menu da sessão ou do grupo oferece "Convert to normal session" ou "Convert to normal group", que removem o vínculo para que a sessão volte a começar no diretório do projeto.

Quando você exclui uma sessão que tem worktrees na subárvore, a confirmação oferece a opção de remover esses worktrees também.

6. Merge: merge gráfico no Git

Quando o trabalho estiver pronto, faça o merge. Para qualquer sessão ou grupo cujo diretório seja um repositório Git, com ou sem worktree, escolha "Git ▸ Merge…" para abrir a caixa de diálogo "Merge branches":

• Escolha as duas branches. Selecione uma "Source branch" (origem) e uma "Target branch" (destino); "Swap direction" inverte as duas. A mesma caixa de diálogo faz o merge da branch de uma sessão filha de volta na branch principal ou traz a branch principal para uma sessão filha a fim de atualizá-la.
• Antes da confirmação, a caixa de diálogo lista as alterações que o merge traz para a branch de destino.
• O merge é executado na árvore de trabalho em que a branch de destino está em checkout. Se a branch de destino não estiver em checkout em nenhum lugar, o merge não pode ser executado; faça o checkout dela primeiro.
• Se a árvore de trabalho da branch de origem tiver alterações não commitadas, elas são primeiro incluídas em um commit com a mensagem que você informar ("Commit & merge").
• Se o merge tiver conflitos, o VelaTerm os deixa no lugar e informa onde resolvê-los. Resolva-os no terminal desse worktree (ou peça a um agente que faça isso) e depois faça o commit.

O merge não exclui o worktree. Quando não precisar mais dele, remova-o com "Git ▸ Delete worktree…".

7. Um fluxo de trabalho típico

1. Na sessão principal, discuta a tarefa com o Claude Code e depois execute /vspawn-tree refactor the checkout module (requer as Vela Skills).
2. Revise a tarefa no cartão de confirmação e escolha "Iniciar sessão". A sessão filha começa no próprio worktree e aparece na barra lateral abaixo da sessão pai, com um ponto de status verde enquanto trabalha.
3. Continue na sessão principal. Quando a sessão filha fizer uma pergunta ou terminar, o ponto dela muda e uma notificação aparece.
4. Revise o trabalho da sessão filha e depois escolha "Git ▸ Merge…" para fazer o merge da branch dela na branch principal.
5. Remova o worktree com "Git ▸ Delete worktree…" e depois arquive a sessão filha para manter um registro.