Como o Sharkly executa agentes em paralelo sem conflitos de merge

Execute dois agentes de código no mesmo checkout e você vai encontrar o modo de falha em menos de uma hora. Um agente troca de branch enquanto o outro está no meio de uma edição. Alterações em stage desaparecem dentro de um commit ao qual não pertencem. Os testes passam contra um arquivo que o outro agente reescreveu pela metade. Nada disso é culpa do modelo. Uma árvore de trabalho do git é estado mutável compartilhado, e dois processos que alteram estado compartilhado sem coordenação vão, cedo ou tarde, corrompê-lo.

O remédio padrão é bem conhecido: dar a cada agente sua própria árvore de trabalho. As git worktrees permitem que um único repositório sirva vários diretórios com checkout ao mesmo tempo, de modo que branches paralelos nunca toquem os mesmos arquivos no disco. Muitas equipes automatizam isso à mão; nosso guia sobre como usar git worktrees com agentes de código de IA percorre essa configuração faça você mesmo.

Este post trata do outro caminho: o que acontece quando isolamento, preparação de diretório, limites de concorrência e limpeza são tratados pela plataforma em vez de pelos seus scripts de shell.

TL;DR

A Sharkly executa agentes de IA em paralelo sem conflitos de merge, dando a cada execução de Task seu próprio diretório isolado em um Computer conectado. Um serviço local nesse Computer recebe cada execução enfileirada, prepara o diretório da task (no caso de trabalho baseado em repositório, uma git worktree separada por execução), inicia o Runtime selecionado e transmite o progresso, os eventos de trace e o resultado de volta para a Task. Os limites de concorrência no Agent e no Computer definem quantas execuções acontecem ao mesmo tempo, e nada é mesclado por conta própria: o resultado volta para a Task, onde uma pessoa revisa a alteração e decide a etapa de merge e release. Os agentes nunca compartilham uma árvore de trabalho, então Tasks paralelas não conseguem sobrescrever as alterações umas das outras.

O modo de falha que a Sharkly foi feita para evitar

Vale a pena ser preciso sobre o que dá errado quando agentes compartilham um checkout, porque cada sintoma corresponde a uma parte da solução.

O estado de branch é global por árvore de trabalho, então quando o agente A faz checkout do próprio branch, os arquivos do agente B mudam embaixo dele no meio da execução. O index também é global, então git add e git commit intercalam trabalho de tasks diferentes. O estado não rastreado entra em conflito: artefatos de build e instalações de dependências de uma execução contaminam os resultados de teste de outra. E a dívida de limpeza se acumula, porque cada cópia ad-hoc de repositório feita para driblar os três primeiros problemas fica no disco até que alguém lembre que ela existe.

Um único diretório compartilhado só consegue executar um agente com segurança. Se você faz malabarismo com painéis do tmux e disciplina, nosso post sobre executar vários agentes do Claude Code em paralelo explica por que esse teto chega tão rápido.

A pilha de execução: Agent, Computer, Runtime, Task

A Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução. Ela adiciona a camada de task compartilhada, Computer, contexto, controle e revisão em torno das ferramentas que sua equipe já usa. Essa posição de camada define como a execução paralela funciona, porque o trabalho da Sharkly é coordenar execuções, não escrever código.

Quatro papéis dividem o trabalho, e cada um tem exatamente uma função:

• O Agent define como o trabalho deve ser conduzido: suas instruções, Skills, repositórios e configurações de execução. O Agent não é o host de execução.
• O Computer fornece o host e os recursos locais: uma máquina local, um servidor remoto, um contêiner ou um host de nuvem compatível. O post irmão sobre Computers na Sharkly aborda como conectá-los.
• O Runtime realiza a sessão do agente propriamente dita. É a ferramenta concreta instalada nesse Computer, como o Claude Code, o Codex ou o Gemini CLI.
• A Task continua sendo o registro compartilhado da equipe: objetivo, status, discussão, trace de execução e resultado.

Quem costura tudo isso é um pequeno serviço local no Computer. Ele registra o Computer, detecta os Runtimes instalados, recebe execuções enfileiradas, prepara o diretório da task para cada execução, inicia o Runtime e reporta os resultados de volta. É ele que inicia a conexão com o servidor, então uma configuração típica não precisa de porta de entrada (inbound).

É essa separação que torna o paralelismo viável. Como o diretório de trabalho é preparado por execução pelo serviço local, e não escolhido pelo Agent, dois Agents atribuídos a duas Tasks podem apontar para o mesmo repositório no mesmo Computer sem nunca ver os arquivos um do outro. Para saber como os Agents são configurados, veja Agents na Sharkly.

O que acontece quando uma execução começa

Atribua uma Task a um Agent e tire-a do Backlog: a Sharkly verifica a prontidão de execução, enfileira uma execução elegível e a despacha para o Computer selecionado. A partir daí, o serviço local assume. Antes de o Runtime começar, ele pode precisar esperar por capacidade de concorrência, preparar um diretório temporário isolado ou aguardar um diretório especificado livre, buscar os repositórios configurados, projetar as variáveis de ambiente permitidas e montar a invocação do Runtime.

Só então o Runtime é iniciado. A execução passa por estados explícitos: Queued, Dispatched, Waiting for local directory, Running e, por fim, Completed, Failed ou Canceled. Esses estados aparecem no log de execução da Task, então “por que nada aconteceu ainda” tem uma resposta verificável em vez de um chute. Uma execução parada em Queued por um limite de concorrência cheio é diferente de uma parada em Waiting for local directory, e a diferença indica qual botão ajustar.

Note o que está ausente: em momento algum o Agent decide onde executar. O Agent traz as instruções; a infraestrutura traz o isolamento.

Worktrees isoladas: como o modo Temporary funciona

Os Agents suportam dois modos de diretório de trabalho, e o modo feito para trabalho paralelo é o modo Temporary. Cada Task recebe um diretório isolado e, no caso de trabalho baseado em repositório, o serviço local pode preparar uma git worktree separada para cada execução a partir dos dados de repositório em cache.

Essa única frase carrega toda a história de prevenção de conflitos. Uma worktree dá a cada execução seu próprio diretório com checkout e seu próprio estado de branch, ao mesmo tempo em que compartilha os objetos do repositório subjacente. Os quatro modos de falha acima desaparecem por construção: nenhum ponteiro de branch compartilhado, nenhum index compartilhado, nenhum artefato de build compartilhado e diretórios que a plataforma pode limpar depois. Como as worktrees vêm de dados em cache em vez de um clone novo, o custo de inicialização continua razoável, embora uma execução ainda possa precisar de acesso à rede para atualizar o repositório.

A documentação é direta sobre quando usar isso: o modo Temporary é recomendado para alterações de código em paralelo e para qualquer situação em que várias Tasks possam modificar a mesma base de código ao mesmo tempo.

Uma fronteira que vale deixar clara: o isolamento evita colisões na árvore de trabalho, não conflitos semânticos. Se duas Tasks reescreverem a mesma função, as duas execuções terminam sem problemas em suas próprias worktrees, e ainda cabe a uma pessoa conciliar a sobreposição na revisão. A solução para isso é delimitar o escopo das Tasks para que não mirem o mesmo código na mesma tarde: uma decisão de planejamento, não de infraestrutura.

Quando o isolamento é a escolha errada: o modo Specified

O segundo modo existe porque um diretório novo por execução não sai de graça. No modo Specified, o Agent é executado dentro de um diretório local absoluto configurado do seu pool, reutilizando o repositório, as dependências e os caches que já estão lá. Ele está disponível apenas em Computers locais.

A troca tem uma consequência dura: um diretório especificado atende uma execução por vez e, quando todos os diretórios configurados estão ocupados, a próxima execução espera. Um Agent que precisa executar várias Tasks simultaneamente no modo Specified precisa de vários diretórios no seu pool.

O isolamento compra segurança ao custo de preparação; a reutilização compra velocidade ao custo de serialização. A Sharkly faz você escolher explicitamente por Agent, o que é bem melhor do que descobrir essa troca em uma árvore de trabalho corrompida.

Limites de concorrência: paralelo, mas com limites

Paralelismo sem limites é um modo de falha por si só. Cada execução simultânea consome CPU, memória, disco, capacidade do provedor de modelos e banda de repositório; oito agentes sobrecarregando um único notebook produzem resultados piores do que três rodando com folga.

A Sharkly limita a concorrência em dois níveis. O Computer tem um limite de concorrência de tasks como host, e cada Agent tem um número máximo de Tasks em execução simultânea, além de um timeout por Task. Os padrões são conservadores: no modo Temporary, um Agent recebe 50% do limite do Computer; no modo Specified, ele corresponde ao número de diretórios configurados. Se você definir um valor acima da quantidade de diretórios, o produto avisa que as escritas podem colidir entre tasks. Esse aviso é a tese deste post comprimida em uma única caixa de diálogo.

A orientação da documentação sobre aumentar limites é do tipo sóbrio: aumente a concorrência só depois que o Computer e o Runtime atuais derem conta da carga existente de forma confiável.

Streaming de progresso e revisão antes do merge

O isolamento seria um problema se também significasse invisibilidade. Cinco agentes em cinco diretórios ocultos é exatamente como o trabalho desaparece em terminais privados. Por isso, tudo o que a execução produz volta para o registro compartilhado.

Enquanto uma execução está ativa, a Task mostra seu estado de execução. A Activity reúne comentários e mudanças de task em uma linha do tempo; o log de execução registra quando a execução começou e terminou, as chamadas de ferramentas e os eventos do Runtime, a origem do acionamento e quaisquer detalhes de falha; o relatório do Agent é persistido como um comentário vinculado ao seu trace de execução. Contexto, progresso, bloqueios e resultados permanecem visíveis da solicitação até a entrega, mesmo que as edições de arquivos tenham acontecido em um diretório que nenhuma pessoa abriu.

Então vem o portão. Nada aqui é mesclado por conta própria. Os agentes pesquisam, executam, testam e reportam. As pessoas definem a direção, concedem autoridade e aceitam o resultado. Quando uma execução termina, o Agent pode deixar a Task aguardando revisão humana, o que aparece na Inbox da pessoa responsável. Worktrees isoladas tornam a execução paralela segura; o portão de revisão a torna confiável.

Mais uma peça fecha o ciclo: a limpeza. As execuções dos agentes deixam diretórios de trabalho e artefatos no Computer, e uma limpeza configurável recupera execuções concluídas após uma janela de retenção, com um limite mínimo de espaço livre como rede de segurança. Trabalhos em execução ou na fila, execuções fixadas (pinned) e execuções com falha que ainda precisam de investigação nunca são tocados. É essa a tarefa que as configurações faça você mesmo invariavelmente esquecem até o disco encher.

O que a Sharkly automatiza em comparação com a configuração faça você mesmo

Se você leu nosso guia de worktrees faça você mesmo, o mapeamento é direto. O git worktree add que você scripta por agente vira o serviço local preparando um diretório isolado por execução. A decisão de “quantos agentes são demais” vira limites de concorrência explícitos, com avisos quando uma configuração é insegura. O git worktree prune que você esquece vira limpeza baseada em retenção. E a parte que nenhum script oferece — um registro compartilhado de qual execução fez o quê e se uma pessoa aceitou o resultado — é a própria Task.

O par honesto de decisões também se aplica aqui. Um desenvolvedor solo rodando dois agentes em uma máquina pode não precisar de uma plataforma; um script de worktree e disciplina dão conta disso por bastante tempo. Recorra à Sharkly quando a coordenação custar mais do que a digitação: várias pessoas atribuindo trabalho, vários Computers, execuções que precisam de fila e revisão. De qualquer forma, você mantém os Runtimes que já tem; o uso dos modelos continua pelas assinaturas ou chaves de API configuradas nessas ferramentas.

Começar é deliberadamente simples. Conecte um Computer, crie um Agent no modo Temporary e atribua a ele uma Task de baixo risco. O guia de primeiros passos percorre o primeiro ciclo em cerca de dez minutos, a documentação da Sharkly aprofunda cada conceito e o texto sobre o que é a Sharkly mostra a plataforma em torno da execução.

Perguntas frequentes

Como a Sharkly evita conflitos de merge entre agentes em paralelo?

Cada execução de Task recebe seu próprio diretório isolado no Computer, e execuções baseadas em repositório podem ter cada uma sua própria git worktree preparada pelo serviço local. Os agentes nunca compartilham um checkout, um index ou arquivos não rastreados, então execuções simultâneas não conseguem sobrescrever o trabalho em andamento umas das outras. Sobreposições em que duas Tasks alteram o mesmo código de propósito ainda são conciliadas por uma pessoa no momento da revisão.

Preciso configurar git worktrees por conta própria para usar a Sharkly?

Não. No modo Temporary, o serviço local prepara o diretório da task para cada execução, incluindo worktrees para trabalho baseado em repositório. Você configura o modo no Agent uma única vez; não há comandos de worktree por execução para scriptar. Para entender o mecanismo por trás disso, consulte a documentação do git worktree.

Quantos agentes podem rodar em paralelo em um Computer?

O Computer tem seu próprio limite de concorrência de tasks, e cada Agent tem um número máximo de Tasks rodando em paralelo. Por padrão, um Agent no modo Temporary recebe 50% do limite do Computer, e um no modo Specified recebe um slot por diretório configurado. Execuções acima do limite esperam na fila.

A Sharkly faz merge das alterações do agente automaticamente?

Não. O resultado, as evidências e o trace da execução voltam para a Task, e uma pessoa revisa o resumo das alterações antes de qualquer coisa ser entregue. Quem revisa aceita, pede alterações ou decide a etapa de merge e release. A automação para onde o julgamento da equipe é necessário.

Quando devo usar o modo Specified em vez de worktrees isoladas?

Use-o quando preparar um diretório novo por execução for realmente caro: um repositório muito grande, estado gerado ou caches custosos, ou ferramentas vinculadas a um único caminho local. Aceite que cada diretório especificado atende uma execução por vez. Para todo o resto, o modo Temporary é o padrão recomendado.