Skip to main content
Pra revisar um PR com o contexto certo, o Kodus parseia o repositório inteiro num AST graph (nós + arestas) e usa ele pra buscar contexto cross-file, validar sugestões e alimentar o agente. O parser roda dentro de um sandbox pra poder fazer git clone, instalar dependências, e executar o CLI isolado do processo da API. Esta página explica os modos de sandbox disponíveis, o que é o AST graph, e como o cache mantém reviews por PR rápidos.

​
Como o AST graph funciona

O Kodus usa o @kodus/kodus-graph, um CLI que percorre um repositório e emite um JSON graph (funções, classes, arquivos, imports, calls). O CLI já vem pré-instalado na imagem do worker (kodus-ai-worker) — no modo local, não tem setup extra. Ciclo de vida:
  1. Quando você seleciona um repositório (no setup, ou ao adicionar um repo depois na UI) — o Kodus enfileira um job AstGraphBuild que roda kodus-graph parse --all no branch default, persiste no Postgres (tabelas ast_graph_*), e marca o repo como indexado. Isso roda em background — você não precisa esperar terminar pra abrir PRs.
  2. Quando um PR é mergeado no branch default — handlers de webhook enfileiram um rebuild incremental que re-parseia apenas os arquivos alterados e mescla os deltas no graph cacheado. O cache continua fresco sem precisar de rebuild completo.
  3. Em toda review de PR — o Kodus carrega o graph cacheado, parseia apenas os arquivos tocados pelo PR, e alimenta o agente com um subgraph focado. Esse é o caminho quente; nunca re-parseia o repo todo.
O cache é o que torna review de repos grandes viável: o build completo roda uma vez no onboarding do repo, todo PR depois disso lê do Postgres.

​
Modos de sandbox

O sandbox é selecionado por SANDBOX_PROVIDER no .env:

​
Escolhendo um modo

  • Tá começando, quer que “funcione e pronto” → local. É o default do installer e não precisa de conta externa.
  • Repos enormes (milhões de LOC) ou quer isolamento forte → e2b. Cadastre em e2b.dev, seta API_E2B_KEY, troca SANDBOX_PROVIDER=e2b.
  • Você não quer que sandbox nenhum rode → none. O agente de review roda sem contexto cross-file; sugestões ainda funcionam mas ficam menos informadas.

​
Migrando uma instalação self-hosted existente

Se você atualizou de uma versão anterior ao AST graph, seus repositórios já selecionados ainda não têm graph — o build dispara automaticamente só em novas seleções. Pra indexar os antigos, rode o script de backfill que vem no installer:
Ele percorre todos os teams da instância e enfileira um job AstGraphBuild pra cada repo selecionado cujo astGraphStatus seja NULL, PENDING ou FAILED. Os builds rodam em background — você pode continuar usando o Kodus enquanto terminam. O script é idempotente: re-execuções pulam repos que já estão READY, nunca re-enfileiram jobs BUILDING, e você pode parar e retomar livremente. Flags comuns:
Acompanhe o progresso pelos logs do worker:

​
Configuração

Cadastre no E2B em e2b.dev, gere uma API key no dashboard, coloca no .env e reinicia a stack.

​
O que roda onde

​
Dimensionamento de recursos

O sandbox local roda git clone e kodus-graph parse dentro do container worker, então RAM do worker importa:
  • Repos pequenos a médios (< 100k LOC) — host com 8GB padrão dá conta.
  • Repos grandes (100k–1M LOC) — dê 4–8GB de RAM extra ao container worker; considere 16GB total no host.
  • Monorepos enormes (> 1M LOC) — troque pra e2b pra parsing fora do host.
A pegada no Postgres escala com quantidade de repos e profundidade do histórico — planeje ~10–50MB por repo indexado como ordem de grandeza.

​
Troubleshooting

Reviews não estão incluindo contexto cross-file (modo local): Veja os logs do worker pra erros de install ou parse do kodus-graph:
Se o passo de install falhar, confirme que o container worker tem acesso à internet (precisa baixar bun + o CLI no primeiro boot, caso a imagem tenha sido buildada sem eles). Jobs e2b travam ou não iniciam: Verifique se API_E2B_KEY está setada e válida:
O dashboard do E2B mostra sessões ativas e uso de quota. Você quer desligar AST completamente (testes, debug): Defina SANDBOX_PROVIDER=none e reinicie o worker. Reviews vão pular o estágio do graph e rodar com a visão crua do diff pelo LLM.