O que é CodeGraph e por que ele muda a forma como o agente lê seu código

Fala aí, beleza? Todo mundo que usa agente de código já viu essa cena: você faz uma pergunta simples sobre o projeto e o bicho sai vasculhando o repositório inteiro antes de abrir a boca

grep aqui, abre arquivo, descobre outro nome de função, grep de novo, abre mais três arquivos, e só ENTÃO ele responde

Cada volta dessa custa chamada de ferramenta, token e o seu tempo

O CodeGraph ataca exatamente isso: em vez de deixar o agente procurar, ele entrega um índice do seu código já pronto, um grafo de conhecimento pré-indexado que sincroniza sozinho quando os arquivos mudam

O projeto é open source, de autoria de Colby McHenry, e mora em github.com/colbymchenry/codegraph

Antes que role confusão: existem OUTROS projetos chamados CodeGraph, de autores diferentes, que não são este. O post inteiro fala do repositório do Colby, combinado?

Bora ver o que ele é, como funciona por dentro, o que dizem os números do benchmark oficial, o contraponto de um teste independente e como instalar 🙂

O problema que o CodeGraph tenta resolver: o loop de grep

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Hoje o agente encontra código do jeito mais simples que existe: busca textual

Ele procura um nome, lê o arquivo que apareceu, descobre que a função real está em outro lugar, procura de novo, lê mais um arquivo…

É um ciclo de tentativa e erro, e ele funciona. O problema é o preço: cada volta é uma chamada de ferramenta, e cada arquivo aberto entra inteiro na janela de contexto, inclusive as partes que não interessam pra pergunta

Quanto maior a base, pior fica. O agente gasta a maior parte do esforço só pra DESCOBRIR onde o código mora, e sobra menos fôlego pra pensar no que você realmente pediu

O CodeGraph troca esse ciclo por uma consulta: o índice já foi construído antes, então o agente pergunta e recebe

E o sintoma mais claro disso aparece no benchmark oficial do projeto: nos sete repositórios testados, o número de leituras de arquivo foi ZERO. Não é que o agente leu menos, é que ele não precisou abrir arquivo nenhum pra responder

Como o CodeGraph monta o grafo do seu código

Calma, que grafo é esse?

É um mapa do seu código em duas peças: os nós (funções, classes, métodos) e as arestas (chamadas, imports, extends, implements). Ou seja, as coisas que existem e as ligações entre elas

Se você já mexeu com árvore de dependência de pacote, a ideia é bem parecida, só que aplicada aos símbolos do seu projeto em vez das libs

O pipeline é assim:

1. O tree-sitter transforma o código-fonte em AST, aquela árvore que representa a estrutura real do arquivo, não o texto dele
2. Queries específicas de cada linguagem varrem essa árvore e extraem os nós e as arestas
3. Tudo isso é gravado em um banco SQLite local, com busca full-text via FTS5

Repara que não tem embedding no meio do caminho, nem banco vetorial, nem chave de API. É estrutura de código mesmo, extraída por parser, guardada em SQLite. Roda 100% local e nada sai da sua máquina, sob licença MIT

A versão 1.5.0, publicada em 21 de julho de 2026, reconstruiu o motor de parsing como um kernel nativo em Rust, com sincronização quase instantânea. Nessa release, 20 linguagens passaram a ser parseadas nesse motor compilado

A relação divulgada não sai completa, mas cita TypeScript, JavaScript (com TSX e JSX), Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua e Luau entre elas

E o grafo pronto pode ser consumido de três formas: servidor MCP (o Model Context Protocol, que é como o agente pluga ferramenta externa), CLI e biblioteca TypeScript

O encaixe por MCP é o mesmo tipo de porta que outros projetos open source como o OpenDesign usam pra dar capacidade nova ao agente, só que aqui a capacidade é enxergar o próprio código

codegraph_explore: o trecho exato em uma única chamada

Essa é a ferramenta que muda o jogo

A codegraph_explore substitui o loop de grep por UMA chamada, e ela devolve três coisas de uma vez:

• os símbolos relevantes, com o código-fonte verbatim (o trecho real, não um resumo do modelo)
• os caminhos de chamada entre esses símbolos, ou seja, quem chama quem
• um resumo de raio de impacto, o tal blast radius, mostrando o que uma mudança ali afetaria

Sacou a diferença? Não é o agente adivinhando onde procurar, é o índice entregando o que ele pediu com o contexto de vizinhança junto

E tem a segunda metade da história, que é o auto-sync

Ele vem ligado por padrão. O CodeGraph observa o projeto com file watchers nativos do sistema operacional e atualiza o grafo de forma incremental a cada mudança de arquivo, inclusive enquanto o PRÓPRIO agente está editando código

Na prática isso significa duas coisas: menos idas e voltas pra achar qualquer coisa, e um contexto que não envelhece no meio da sessão. O agente edita, o grafo acompanha, a próxima consulta já reflete o estado novo

É o mesmo espírito de outras extensões que mudam o comportamento do agente, tipo o Superpowers do Claude Code: não é um modelo melhor, é uma engrenagem nova em volta dele

Os números do benchmark oficial do CodeGraph

O benchmark do projeto foi remedido em 5 de agosto de 2026. Na média dos sete repositórios testados, deu isso:

Agora o que interessa de verdade, que é o método, porque número sem método não vale nada

Foram sete bases de código open source REAIS, cobrindo sete linguagens diferentes: VS Code, Excalidraw, Django, Tokio, OkHttp, Gin e Alamofire

O modelo usado foi o Claude Opus 4.8 em modo headless, respondendo uma pergunta de arquitetura sobre a base, com e sem CodeGraph

E cada braço rodou 4 vezes, tomando a mediana. Não é uma execução de sorte, é a mediana de quatro

Esse é o benchmark do próprio projeto, então guarde a informação com o carimbo certo: é medição do autor, não de terceiro independente

O ganho é real, mas depende do tamanho da base

E aqui entra a parte honesta da conversa 😅

A HarrisonSec rodou um teste independente no repositório Hono, um projeto TypeScript que está FORA da suíte oficial dos sete repos

O resultado reproduziu a economia de passos, mas não a economia de dinheiro: a contagem de chamadas de ferramenta caiu 55%, e o custo em dólares ficou praticamente igual, com variação de +7%

Ou seja, empate no bolso

A explicação registrada é boa e faz sentido: o Hono está ACIMA do ponto de virada em número de passos, então o índice já economiza chamadas, mas está ABAIXO do ponto de virada em dólares, porque o custo de carregar o payload do grafo empata com o custo dos ciclos de grep que ele substituiu

Em repositórios bem maiores a conta muda de lado, porque o caminho do grep percorre muito mais arquivos, e aí o índice passa a compensar também no custo

Então o veredito fica assim: espere economia de passos e de tempo em qualquer tamanho de projeto, e espere economia de dinheiro sobretudo em base grande

Vale dizer com todas as letras: este post não inclui teste próprio. O que está aqui é o benchmark oficial e o teste independente da HarrisonSec, cada um com o seu recorte

Como instalar o CodeGraph

São três passos, só com o fluxo confirmado na documentação do projeto. E olho no passo 3, porque é ele que faz o CodeGraph enxergar o seu repositório

1. Instale o pacote globalmente pelo npm

npm i -g @colbymchenry/codegraph

Se você prefere não instalar nada global de cara, dá pra usar o atalho que baixa e roda o instalador de uma vez:

npx @colbymchenry/codegraph

2. Rode o instalador, UMA vez por máquina

codegraph install

Ele detecta os agentes que você já tem instalados e pergunta quais configurar, ligando o servidor MCP do CodeGraph em cada um. A lista de agentes suportados pelo instalador: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE e Kiro

3. Dentro do projeto, construa o grafo

codegraph init

Esse comando roda uma vez POR PROJETO. Ele cria o diretório local .codegraph/ e constrói o grafo completo no mesmo passo

Sem esse terceiro passo não tem índice, então não pule ele achando que o install já resolveu

O erro comum aqui é confundir os dois comandos, e ele acontece nas duas direções: tem gente que roda só o codegraph install e acha que o grafo do projeto já existe (não existe, o índice nasce no codegraph init), e tem gente que repete o install a cada repositório novo, sem necessidade. Grava assim: install é uma vez por máquina, init é uma vez por projeto

Para quem o CodeGraph faz sentido

Base de código grande, daquelas em que o agente se perde no loop de busca e queima metade do contexto só pra descobrir onde a função mora. É o cenário mais óbvio

Time com restrição de dados, porque o CodeGraph roda 100% local: sem embeddings, sem banco vetorial, sem chave de API e sem mandar nada pra fora da máquina. O código não sai de casa pra ser indexado

Quem alterna entre agentes diferentes e não quer manter índice separado pra cada um. O mesmo grafo serve Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE e Kiro

Quem quer avaliar impacto ANTES de editar, usando o blast radius pra ver o que uma mudança encosta. Isso é ouro em refatoração de código legado

E onde ele tende a render menos: projeto pequeno. O ganho aparece em passos e em tempo, não necessariamente na fatura, como o teste do Hono mostrou

Conclusão

A sacada do CodeGraph é simples e por isso funciona: ele não deixa o agente mais inteligente, ele deixa a leitura do seu código mais barata e mais direta

Troca busca por consulta. Em vez de o modelo caçar o arquivo certo no grep, ele pergunta a um índice que já existe e recebe o trecho exato, com os caminhos de chamada e o raio de impacto junto

Próximo passo se você curtiu a ideia: roda codegraph init num projeto real de tamanho médio pra cima e compara quantas chamadas de ferramenta o agente gasta antes e depois

Decide pelo SEU repositório, não pela média do benchmark, porque o ponto de virada muda com o tamanho da base

E como o projeto é MIT e está aberto no GitHub, dá pra abrir o código e conferir cada peça antes de confiar nele, que é sempre o melhor jeito de avaliar ferramenta open source 😀

até o próximo post!