GitNexus: como grafos de conhecimento dão consciência arquitetural aos agentes de IA

Semana passada, pedi para um agente de IA renomear uma função em um projeto com 200 arquivos. Ele renomeou. E quebrou 14 imports em 9 arquivos diferentes. O agente não tinha como saber que aquela função era usada em tantos lugares. Ele simplesmente não enxergava o projeto como um todo.

Esse é o problema central de usar IA para escrever código em projetos reais: o agente não tem consciência arquitetural. Ele vê o arquivo que você abriu, talvez os vizinhos, mas não entende como as peças se conectam.

O gap entre “escrever código” e “entender código”

LLMs são excelentes em gerar código função por função. Mas um projeto de software não é uma coleção de funções isoladas. É uma rede de dependências, chamadas, importações e efeitos colaterais.

Quando um desenvolvedor sênior modifica uma função, ele mentalmente percorre: “quem chama isso?”, “que testes cobrem isso?”, “se eu mudar a assinatura, o que quebra?”. Esse raciocínio depende de um modelo mental do projeto inteiro.

Agentes de IA não têm esse modelo. Eles compensam com buscas textuais (grep, ripgrep), que encontram strings mas não entendem relações semânticas. Encontrar todas as ocorrências de validateToken não é a mesma coisa que entender que validateToken é chamada pelo middleware de autenticação, que é usado em 47 rotas da API.

GitNexus: o projeto inteiro como um grafo

O GitNexus ataca esse problema de frente. É um motor de inteligência de código que indexa repositórios inteiros em um grafo de conhecimento navegável, onde cada nó é um símbolo (função, classe, módulo) e cada aresta é uma relação (importa, chama, estende).

O projeto é open-source, tem mais de 7.500 stars no GitHub, e funciona tanto via CLI quanto no navegador (zero instalação).

Como funciona a indexação

O pipeline de indexação tem 6 estágios:

Mapeamento de estrutura - Percorre o sistema de arquivos e mapeia a hierarquia de diretórios e arquivos
Parsing AST via Tree-sitter - Extrai todos os símbolos (funções, classes, variáveis, tipos) usando parsing sintático nativo. Suporta 12 linguagens: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP e Swift
Resolução de imports e chamadas - Conecta os símbolos: quem importa quem, quem chama quem
Clustering funcional - Agrupa símbolos relacionados em clusters funcionais (ex: “módulo de autenticação”, “camada de persistência”)
Trace de execução - Mapeia fluxos de execução completos através do codebase
Índice de busca híbrida - Constrói índices BM25 (busca textual) e semântica, combinados via Reciprocal Rank Fusion

O resultado é armazenado em KuzuDB, um banco de grafos embarcável que roda tanto nativo (CLI) quanto via WASM (navegador). Cada repositório gera um índice portável na pasta .gitnexus/.

7 ferramentas via MCP

O que torna o GitNexus particularmente útil para agentes de IA é a exposição do grafo via MCP (Model Context Protocol). São 7 ferramentas que qualquer agente compatível pode usar:

Ferramenta	O que faz
`list_repos`	Descobre repositórios indexados
`query`	Busca híbrida agrupada por processo
`context`	Relações e participações de um símbolo
`impact`	Análise de blast radius (upstream + downstream)
`detect_changes`	Análise de impacto baseada em git diff
`rename`	Rename coordenado em múltiplos arquivos
`cypher`	Queries Cypher diretas no grafo

A ferramenta impact é a mais poderosa. Você pergunta “qual o impacto de mudar validateToken?” e recebe: todas as funções que chamam ela (upstream), todas as funções que ela chama (downstream), e o blast radius — quantos arquivos e processos são afetados. Isso é exatamente a informação que o agente precisava antes de fazer aquele rename que quebrou 14 arquivos.

Busca híbrida: por que grep não basta

A maioria das ferramentas de código para IA usa busca textual pura. O GitNexus combina três abordagens:

BM25 (busca léxica): encontra correspondências exatas de termos. Bom para nomes de funções, variáveis, strings específicas.

Busca semântica: encontra código conceitualmente similar mesmo com nomes diferentes. Se você busca “validar credenciais”, encontra checkUserAuth mesmo que as palavras não batam.

Reciprocal Rank Fusion (RRF): combina os rankings de BM25 e semântica sem precisar normalizar scores. Cada fonte vota nos resultados e o RRF gera um ranking final ponderado. É o mesmo algoritmo que usamos no MCP Context Hub para combinar busca vetorial e textual — funciona bem justamente porque não precisa que fontes diferentes usem a mesma escala.

Os resultados vêm agrupados por processo. Em vez de uma lista plana de funções, você recebe: “no processo de autenticação, essas funções são relevantes; no processo de logging, essas outras”. Isso dá ao agente uma visão funcional, não apenas estrutural.

Zero-server: tudo roda no cliente

Uma decisão arquitetural que merece destaque: o GitNexus não tem servidor. Todo o processamento acontece localmente — no terminal via CLI ou no navegador via WebAssembly.

Isso resolve dois problemas práticos:

Privacidade: seu código nunca sai da sua máquina. Em projetos corporativos, isso é um requisito, não um diferencial.
Latência: sem round-trip para servidor, as queries no grafo são sub-millisecond. Um impact em um repositório de 2.000 arquivos retorna em menos de 100ms.

O trade-off é que a indexação inicial demora mais (depende do tamanho do projeto e do hardware local), mas é feita uma única vez e atualizada incrementalmente.

Web UI: visualização interativa

Além do CLI e MCP, o GitNexus oferece uma interface web onde você pode ver o grafo do seu projeto. Cada nó é um símbolo, cada aresta é uma relação, e você pode:

Navegar pelos clusters funcionais
Clicar em um nó para ver seu código e relações
Filtrar por tipo (função, classe, módulo)
Buscar símbolos por nome ou conceito

Isso é útil não só para IA, mas para onboarding de desenvolvedores. Em vez de ler documentação (que quase nunca está atualizada), um novo membro do time pode abrir o grafo e entender a arquitetura em minutos.

O Web UI funciona 100% no navegador — você pode arrastar uma pasta ou ZIP do seu projeto e ele indexa localmente via WASM. Não precisa instalar nada.

Como integrar com seu agente

Claude Code

npx gitnexus analyze
npx gitnexus setup

O setup detecta automaticamente o editor/agente e configura o MCP server. Para Claude Code, ele registra o servidor e instala skills que ensinam o agente a usar as ferramentas de forma inteligente (ex: sempre rodar impact antes de um refactor).

Cursor e Windsurf

O setup também configura esses editores. A integração é via MCP — as mesmas 7 ferramentas ficam disponíveis no contexto do agente.

Multi-repo

Se você trabalha com microsserviços ou monorepos, o GitNexus mantém um registro global em ~/.gitnexus/registry.json. Você pode indexar múltiplos repositórios e o agente consegue buscar relações entre eles.

Onde isso se encaixa no ecossistema

O GitNexus resolve o problema de entender código. Ele não gera código, não comprime contexto, não faz cache. Ele mapeia relações.

Isso o torna complementar a ferramentas como o MCP Context Hub (que otimiza e persiste contexto) e o Context7 (que busca documentação de bibliotecas). Na prática, uma stack de inteligência para agentes de IA pode ter:

GitNexus: entende a estrutura e relações do seu código
Context Hub: persiste decisões, comprime contexto, faz cache semântico
Context7: traz documentação atualizada de dependências externas

Cada um resolve uma dimensão diferente do problema de contexto. Juntos, transformam um agente que “escreve código” em um que “entende o projeto”.

Detalhes técnicos da implementação do grafo

Para quem quer entender o que acontece por baixo dos panos, vale explorar como o GitNexus constrói e consulta o grafo internamente.

Estrutura dos nós e arestas

Cada nó no grafo tem um tipo e um conjunto de propriedades. Os tipos principais são:

File: representa um arquivo no repositório. Propriedades: caminho, linguagem, tamanho, hash do conteúdo.
Function: representa uma função ou método. Propriedades: nome, assinatura, linha inicial, linha final, complexidade ciclomática.
Class: representa uma classe ou interface. Propriedades: nome, métodos, propriedades, herança.
Module: representa um módulo ou pacote. Propriedades: exports, imports, dependências.

As arestas conectam nós com relações tipadas:

IMPORTS: um arquivo importa outro
CALLS: uma função chama outra
EXTENDS: uma classe estende outra
CONTAINS: um arquivo contém uma função ou classe
DEPENDS_ON: dependência funcional inferida pelo clustering

Essa estrutura permite queries como: “mostre todas as funções que chamam validateToken e estão em arquivos que importam o módulo auth”. Em busca textual pura, isso exigiria múltiplos greps e correlação manual. Com o grafo, é uma query Cypher de 3 linhas:

MATCH (caller:Function)-[:CALLS]->(target:Function {name: 'validateToken'})
MATCH (file:File)-[:CONTAINS]->(caller)
WHERE file.path CONTAINS 'auth'
RETURN caller.name, file.path

Tree-sitter e parsing multi-linguagem

O Tree-sitter é a base do parsing do GitNexus, e a escolha não é acidental. Diferente de parsers baseados em regex ou heurísticas, o Tree-sitter gera ASTs (Abstract Syntax Trees) completas e corretas, mesmo para código parcialmente inválido.

Isso é crucial em contextos reais: código em branches de desenvolvimento frequentemente tem erros de sintaxe temporários. Um parser frágil falharia. O Tree-sitter degrada graciosamente, extraindo o máximo de informação possível mesmo de código incompleto.

O suporte a 12 linguagens significa que monorepos com serviços em TypeScript, Python e Go podem ser indexados como um grafo unificado. As relações entre serviços (via APIs REST ou gRPC) não são capturadas automaticamente pelo parsing, mas podem ser anotadas manualmente ou inferidas via clustering.

KuzuDB: por que um banco de grafos embarcável

A escolha do KuzuDB (em vez de Neo4j, por exemplo) é estratégica. O KuzuDB roda como uma biblioteca embarcada, sem processo servidor separado. Isso permite:

Execução local pura: nada de instalar e configurar um banco de dados separado. O npx gitnexus analyze faz tudo.
Portabilidade: o índice é uma pasta (.gitnexus/) que pode ser commitada, compartilhada ou movida entre máquinas.
WASM: o KuzuDB compila para WebAssembly, o que habilita a Web UI sem backend.

Em termos de performance, o KuzuDB usa armazenamento colunar otimizado para queries de grafos. Traversals de 3 a 4 hops em grafos com 50.000 nós retornam em menos de 10ms. Para a maioria dos repositórios (até 10.000 arquivos), a experiência é essencialmente instantânea.

Performance: benchmarks e comparações

Como qualquer ferramenta, o GitNexus precisa ser avaliado em termos de performance real, não apenas funcionalidade.

Tempo de indexação

Baseado em testes com repositórios reais:

Repositório	Arquivos	Linguagem	Tempo de indexação	Tamanho do índice
Projeto pequeno (API REST)	85	TypeScript	4s	12MB
Projeto médio (SaaS)	620	TypeScript + Python	28s	89MB
Projeto grande (monorepo)	3.200	Multi-linguagem	2min 15s	340MB
Projeto muito grande	12.000+	Multi-linguagem	8min+	1.2GB+

A indexação incremental (após a primeira) é significativamente mais rápida, processando apenas arquivos modificados. Em um projeto de 620 arquivos onde 15 foram modificados, a reindexação leva menos de 3 segundos.

Tempo de query

As queries no grafo são rápidas por natureza:

impact em um símbolo com 30 dependências: ~15ms
query com busca híbrida em 3.000 arquivos: ~80ms
context de um símbolo com 50 relações: ~8ms
rename coordenado em 20 arquivos: ~45ms (análise) + tempo de escrita

Para comparação, uma busca equivalente com ripgrep (que é extremamente rápida) encontra ocorrências textuais em ~20ms, mas não identifica relações semânticas. O GitNexus leva um pouco mais, mas retorna informação estruturada que ripgrep não consegue fornecer.

Comparação com alternativas

Outras ferramentas atacam problemas similares:

Sourcegraph: oferece code intelligence e navegação, mas é um serviço pesado que exige infraestrutura (servidor, banco de dados, indexadores). O GitNexus roda 100% local.
Serena: foca em análise semântica de código via MCP. Complementar ao GitNexus, com mais foco em entender o significado do código e menos em mapear relações estruturais.
ast-grep: excelente para buscas baseadas em padrões AST, mas não constrói um grafo persistente. Cada busca é independente.

O diferencial do GitNexus é a combinação de: grafo persistente + busca híbrida + MCP nativo + execução local. Nenhuma das alternativas oferece esse pacote completo.

Possibilidades futuras

O GitNexus já resolve problemas reais hoje, mas o potencial de grafos de código vai além do que está implementado atualmente.

Detecção de code smells via grafo

Com o grafo completo de dependências, é possível detectar automaticamente padrões problemáticos: funções com fan-in muito alto (acoplamento), ciclos de dependência entre módulos, classes com responsabilidades demais (medida pelo número de relações distintas). Esses padrões são difíceis de detectar com análise textual, mas triviais com queries de grafo.

Sugestão de testes baseada em impacto

Quando um PR modifica 5 arquivos, o grafo pode identificar exatamente quais testes precisam rodar, não todos. Isso é relevante para pipelines de CI/CD em projetos grandes, onde rodar a suite inteira de testes leva 30 minutos ou mais. Executar apenas os testes afetados pelo blast radius pode reduzir o tempo para 3 a 5 minutos.

Evolução arquitetural ao longo do tempo

Indexando o grafo em diferentes pontos do histórico git, seria possível visualizar como a arquitetura evolui ao longo do tempo: quais módulos crescem mais, onde o acoplamento aumenta, quando dependências circulares surgem. Isso transformaria o GitNexus de uma ferramenta de análise estática em uma ferramenta de observabilidade arquitetural.

Grafos cross-repositório inteligentes

Para organizações com microsserviços, a capacidade de conectar grafos de diferentes repositórios via contratos de API (OpenAPI specs, protobufs) criaria uma visão unificada do sistema distribuído. O agente poderia responder: “se eu mudar esse endpoint no serviço A, quais clientes no serviço B e C são afetados?”

Limitações honestas

Nenhuma ferramenta é perfeita, e é importante ser transparente:

Linguagens dinâmicas: a resolução de chamadas em Python e JavaScript depende de parsing estático, que não captura chamadas dinâmicas (ex: getattr, eval). A cobertura é boa, mas não é 100%.
Licença não-comercial: o GitNexus usa licença PolyForm Noncommercial. Você pode usar livremente em projetos pessoais e open-source, mas uso comercial requer licença separada.
Indexação inicial: em projetos muito grandes (100k+ arquivos), a primeira indexação pode demorar alguns minutos. Depois disso, atualizações são incrementais.
Relações entre serviços: chamadas HTTP entre microsserviços não são detectadas automaticamente pelo parsing de código. O grafo mapeia relações dentro de um repositório com alta fidelidade, mas relações cross-repositório dependem de anotações manuais ou inferência.

Por que isso importa agora

Estamos em um ponto de inflexão. Agentes de IA estão evoluindo de “assistentes de autocomplete” para “desenvolvedores autônomos” que navegam, entendem e modificam codebases inteiros.

Mas autonomia sem consciência arquitetural é perigoso. Um agente que modifica código sem entender o blast radius vai criar mais bugs do que resolve. O GitNexus é parte da infraestrutura que faz agentes autônomos serem confiáveis, não apenas rápidos.

O futuro do desenvolvimento com IA não é sobre modelos maiores. É sobre dar aos modelos existentes o contexto certo. E para código, o contexto certo é um grafo.

Links: