Repositórios de um agente

Camada funcional

Até 24/08/2026, um agente trabalhava com um repositório. Quem precisava mexer em duas partes de um sistema ao mesmo tempo — o site e a interface de programação, digamos — não tinha caminho: sobrava pedir ao agente que buscasse o segundo por conta própria dentro da máquina dele, um trabalho que morria junto com a máquina, sem aparecer no painel de arquivos e sem o agente saber que existia.

Agora o repositório virou uma lista: até dez por agente, cada um na própria pasta, prontos quando o computador do agente liga. Um deles é o principal — é o que o painel de arquivos abre por padrão e o que vale quando alguém fala em "o repositório do agente" sem qualificar.

O que muda, na prática

• Ligar o acesso ao GitHub exige pelo menos um repositório, em vez de um repositório e uma branch como campo único.
• Cada linha da lista tem um repositório e a branch dele; uma das linhas é a principal.
• Chegando a dez, o botão de adicionar desliga e diz por quê — antes de você tentar e levar um erro.
• Remover o último repositório com o acesso ligado é recusado: desligue o acesso primeiro.
• O aviso de "acesso somente leitura" numa linha continua à vista mesmo depois de a causa ter sido corrigida, para você não perder o motivo de vista.
• O painel de arquivos ganhou escopo: dá para escolher qual dos repositórios olhar.

O que acontece quando um repositório não está disponível

A conferência de acesso descrita na página do GitHub passa a valer por repositório, e o que acontece depois depende do papel de cada um:

Um repositório extra sem acesso nem chega a ser buscado — não faz sentido gastar tempo para falhar. E o agente sabe da ausência: ele recebe o que de fato está lá, não o que deveria estar. A diferença importa, porque um agente que acha ter um repositório à mão vai tentar usá-lo.

O clone tenta de novo quando vale a pena (31/08/2026)

Antes desta correção, trazer o código era tentativa única: um tropeço de meio segundo na rede derrubava a conversa inteira antes de ela começar, exatamente como derrubava um repositório que não existe — sem diferença nenhuma entre "vale tentar de novo" e "não vale". E o caso mais comum não era peso nem lentidão: era uma falha instantânea, que passaria sozinha, e que ninguém repetia.

Agora a falha é classificada antes de decidir o que fazer. Repetem a tentativa as causas que passam sozinhas — a rede, o limite de uso do GitHub, uma espera que estourou sem consumir todo o tempo disponível. Não repetem as que não passariam por insistência: um repositório que não existe, uma branch que não existe, espaço em disco esgotado, uma autorização que precisa ser renovada. Insistir contra essas só gastaria o tempo que faz a conversa parecer travada. A autorização vencida é o meio-termo: ela é renovada uma vez — uma só, mesmo quando vários repositórios falham juntos — antes de a tentativa ser abandonada.

E a causa passa a ficar registrada e à vista, no lugar da mesma frase genérica para qualquer problema de preparo. Sem isso não havia como saber, nem depois, se um agente estava falhando por rede, por permissão ou por uma branch renomeada.

Como o agente se orienta entre vários

Com um repositório só, nada muda no jeito dele trabalhar. Com vários, ele recebe a relação do que tem em mãos e uma ordem de decisão: procurar antes de perguntar. Uma busca custa menos que uma pergunta, e a pergunta fica reservada ao que a busca não resolve — o meio-termo entre adivinhar e mexer no repositório errado, e perguntar a cada pedido até virar inútil.

As diretrizes de cada projeto entram separadas por repositório, para o agente não misturar as regras de um com as do outro. E há um teto de tamanho para esse conjunto, repartido entre os repositórios em vez de valer por ordem de chegada: um projeto com documentação extensa não pode engolir o espaço dos outros.

As diretrizes também valem por pasta (07/09/2026)

Até aqui, só os arquivos de regra na raiz de cada repositório chegavam ao agente. Regra escrita para uma pasta específica — as convenções do Cursor, as instruções do GitHub Copilot, ou um segundo arquivo de diretrizes dentro de uma subpasta — ficava de fora, mesmo existindo no repositório.

Agora o agente também recebe essas regras, cada uma marcada com a pasta ou o padrão de arquivo a que se aplica — para ele saber que uma regra vale só para uma parte do projeto, não para o repositório inteiro. Quando a lista de regras descobertas não cabe no espaço reservado, o que sobra não desaparece: fica listado por caminho, para quem for mexer naquela pasta saber que existe uma regra ali e que precisa abrir o arquivo para lê-la.

O mesmo mecanismo de descoberta é reaproveitado pelo revisor de Pull Request: para ele, as regras do repositório revisado contam como critério de avaliação, e uma mudança que viole uma delas é um achado — ver Revisor de Pull Request.

Um App continua com um repositório só

Isso é decisão, não limitação por resolver. Um App é publicado a partir de um repositório que o próprio VolundOS cria para ele, e a relação é de um para um. Tentar configurar vários num App é recusado com uma mensagem, em vez de aceito e ignorado — aceitar em silêncio deixaria você achando que configurou algo.

Repositório declarado pelo próprio disparo (29/08/2026)

Até aqui, o repositório era sempre configuração persistente do agente — resolve bem quem mexe sempre no mesmo lugar, mas não serve um agente que atende muitos pedidos diferentes: um revisor de PR ou o executor de uma esteira recebe o repositório junto do pedido, e reconfigurar o agente a cada disparo faria duas execuções concorrentes do MESMO agente disputarem a mesma configuração — a segunda trabalhando no repositório errado.

Agora existe um segundo caminho, por escolha de quem configura: em vez de declarar repositórios fixos, o agente pode passar a receber o repositório junto do pedido. Quem chama a execução — seja uma chamada direta ao agente, seja o disparo de uma esteira — manda a lista de repositórios no próprio pedido, com a branch opcional e a indicação de qual deles é o principal, e é essa lista que o computador daquela execução prepara. Branch em branco passou a significar "a branch padrão do repositório", porque quem manda o repositório junto do pedido nem sempre sabe qual é.

Duas regras de configuração protegem o caminho antigo:

• Os dois não se combinam. Um agente com repositório fixo configurado e recebendo repositório do pedido é recusado — a primeira execução sobrescreveria a configuração, e não é isso que a opção promete.
• Ligar GitHub exige uma fonte de repositório, das duas. Sem repositório fixo e sem receber do pedido, o agente fica sem onde clonar — a mesma trava que já existia, agora com um segundo jeito de satisfazê-la.

Quando o pedido não declara nada, a mensagem distingue as duas causas possíveis: "sem repositório configurado", que se resolve no painel, ou "esta execução não declarou nenhum", que é problema do pedido e não da configuração — evita mandar quem investiga para o lugar errado.

Numa esteira, a mesma capacidade aparece no disparo, e está descrita em Execução de uma esteira.

O que dá para fazer, e onde

Quem depende disso

• Agentes com repositório de trabalho: o código já está lá quando a execução começa, com a credencial aplicada — o agente nunca vê a credencial.
• Painel de arquivos: escopo por repositório, em vez de sempre mostrar um só.
• Skills: importar skill de um repositório continua funcionando como antes.