Como o CodeGraph reduz tool calls e tokens do agente no seu projeto

Fala aí, beleza? Se você já ficou olhando o agente listar a pasta, abrir um arquivo, abrir DE NOVO o mesmo arquivo e ainda pedir mais contexto antes de escrever a primeira linha útil, você conhece esse problema de perto

Em base grande, a maior parte do gasto acontece antes da primeira linha útil

O agente não está pensando ali, ele está tateando

É exatamente esse pedaço que o CodeGraph tenta cortar. É um projeto open source de Colby McHenry, publicado sob licença MIT no repositório colbymchenry/codegraph, e a proposta dele é simples de enunciar: trocar a sequência de listar, abrir e reler por uma consulta a um índice que já estava pronto antes da sua pergunta

Por que o agente queima contexto antes de responder qualquer coisa

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

O sintoma: ele se perde e a resposta chega cara e lenta

Você pergunta algo de arquitetura, tipo "quem chama essa função e o que quebra se eu mudar ela"

O agente sai catando arquivo, volta com meia resposta, abre mais um arquivo, relê um que já tinha aberto

Quando a resposta chega, ela veio depois de um monte de idas e voltas que não produziram nada além de contexto

A causa: ferramenta estreita cobra pedágio a cada passo

Pensa em cada ferramenta do agente como uma pergunta separada: listar, buscar, abrir, reler

Cada uma dessas é uma ida e volta inteira, e todo arquivo aberto fica no contexto e volta a ser processado a cada turno seguinte

Aí tem o agravante: quando o menu tem várias ferramentas parecidas, o agente erra a escolha, e cada escolha errada é mais um turno queimado à toa. Essa é justamente a justificativa oficial do CodeGraph pra reduzir o menu, uma ferramenta forte guia melhor o agente do que um punhado de ferramentas estreitas

A solução: o trabalho de descoberta feito antes da pergunta

Se o código já foi lido, quebrado em símbolos e ligado por arestas ANTES, a pergunta inteira cabe em uma consulta só

O agente não precisa navegar até a resposta, ele consulta a resposta

Como prevenir: índice velho é pior que índice nenhum

Aqui mora o medo de todo mundo: "e quando eu mexer no código, o índice não vira mentira?"

Rodando como servidor MCP, o CodeGraph monitora o projeto com eventos nativos do sistema operacional (FSEvents, inotify, ReadDirectoryChangesW) e captura cada criação, alteração ou remoção de arquivo fonte

E tem um debounce que agrupa rajadas de edição em uma sincronização só, então salvar dez arquivos seguidos não dispara dez reindexações

Vídeo: para onde vão os tokens do seu agente

Pra começar do zero com esse raciocínio de desperdício de contexto, o vídeo abaixo ajuda a entender pra onde o orçamento do agente escorre antes dele produzir qualquer coisa

O que é o CodeGraph e como ele responde em uma chamada só

O CodeGraph faz o parse do seu código com tree-sitter e guarda todo símbolo, aresta e arquivo em um banco SQLite local, exposto como um grafo de conhecimento consultável

Que banco local? Um arquivo em .codegraph/codegraph.db, com busca full-text via FTS5, usando node:sqlite em modo WAL

Se você conhece aquele índice de busca que um editor monta em background pra te dar "ir para a definição" instantâneo, a ideia é parecida, só que quem consome o índice é o agente, não você

O suporte a linguagens é automático pela extensão do arquivo, com parsing incremental em mais de 20 linguagens. E roda 100% local: indexação e consulta acontecem na sua máquina, sem mandar o código pra serviço externo

Uma ferramenta só no menu (e as outras sete ainda estão lá)

Como servidor MCP, o CodeGraph expõe por padrão UMA ferramenta: a codegraph_explore

Ela responde em uma chamada só, devolvendo o código verbatim dos símbolos relevantes agrupado por arquivo, os caminhos de chamada entre eles e um resumo de raio de impacto

Isso conversa com uma ideia que já apareceu por aqui quando falamos de rodar scripts dentro de Skills: dar ao agente uma porta de entrada única e bem definida em vez de espalhar opções parecidas

As outras sete continuam funcionais, só não aparecem listadas por padrão: codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files e codegraph_status

Pra trazer elas de volta, existe a variável de ambiente CODEGRAPH_MCP_TOOLS, uma allowlist de nomes curtos separados por vírgula que substitui o padrão

Com e sem CodeGraph: o que o benchmark oficial mediu

O benchmark oficial coloca um agente Claude Code rodando headless (com --strict-mcp-config) pra responder uma pergunta de arquitetura, em 7 repositórios open source reais cobrindo 7 linguagens, com mediana de 4 execuções por braço

O braço COM tem o servidor MCP do CodeGraph ligado, o braço SEM tem config MCP vazia. Read, Grep e Bash estão disponíveis nos dois lados, então não é agente cego contra agente com ferramentas

O desenho dessa resposta direta é quase sempre o mesmo: um codegraph_explore devolvendo o código relevante, e para

Atenção nisso: os percentuais são MÉDIA dos sete repositórios, não promessa por projeto

O seu repo pode ficar acima ou abaixo, e daqui a pouco a gente vê um caso real em que o número de custo não se repetiu

Como instalar o CodeGraph e indexar o seu projeto

São três passos, e a ordem importa

1. Rode o instalador. Ele detecta e configura os agentes que já estão instalados na máquina

npx @colbymchenry/codegraph

Se você já tem Node e prefere deixar o binário disponível de forma global, dá pra instalar assim:

npm i -g @colbymchenry/codegraph

O pacote é distribuído no npm como @colbymchenry/codegraph, e a versão mais recente publicada é a 1.5.0, de 21/07/2026

2. Responda o que o instalador pergunta: quais agentes configurar e se a configuração vale pra todos os projetos ou só pro atual

Ele escreve a config do servidor MCP de cada agente mais uma seção CodeGraph no arquivo de instruções do agente (CLAUDE.md, AGENTS.md ou GEMINI.md), e ativa permissões de auto-allow quando o Claude Code está entre os alvos

Aliás, o instalador oficial cobre vários agentes de código, não só o Claude Code: Claude Code, Codex CLI, Gemini CLI, Cursor, OpenCode, Antigravity, Kiro e Hermes Agent

3. Entre no projeto e construa o grafo

codegraph init

Esse comando cria o diretório local .codegraph/ e constrói o grafo completo no mesmo passo, sem etapa separada de indexação

O erro comum deste passo: achar que o instalador já indexou o código. Não indexou! Ele só conecta os agentes

Sem codegraph init dentro do projeto, o agente tem a ferramenta na mão e nenhum grafo pra consultar, e você vai jurar que a ferramenta é furada quando na verdade faltou um comando 😅

Quando a economia aparece de verdade (e quando ela some)

A própria documentação é honesta nesse ponto, e isso é MUITO bom de ver: a economia de tokens e de dinheiro é dependente de escala

Ela aparece em bases grandes e emaranhadas, rodando em volume

Onde compensa mais:

• Repositório grande, com muita dependência cruzada, onde encontrar o ponto certo já é meio dia de trabalho
• Uso em volume, várias sessões por dia, várias perguntas por sessão
• Pergunta de arquitetura e de raio de impacto ANTES de mexer no código, tipo "quem depende disso aqui"
• Time com agentes diferentes na mesma máquina, já que o instalador configura vários e o índice é do projeto, não do agente

E onde ela some: repositório modesto

A documentação avisa que ali o ganho de token e custo é pequeno e ruidoso. Sobra o ganho universal, que segue valendo: menos tool calls e resposta mais rápida

Vale a pena? O que o teste independente mostrou

Agora a parte que ninguém gosta de colocar no post, mas que é a mais útil

Um teste independente publicado pelo HarrisonSec rodou o CodeGraph no repositório Hono (cerca de 280 arquivos TypeScript)

A queda de tool calls se reproduziu bonito: 55% menos

A economia de custo não: deu 7% a mais, ou seja, custo empatado na prática

A explicação dele é direta: cada chamada do CodeGraph devolve um bloco grande de contexto de grafo, que é relido a cada turno, e o custo de carregar esse payload em cache equivale ao custo das idas e voltas de grep que ele substituiu

A conclusão do teste é uma frase que vale guardar: o Hono fica ACIMA do ponto de virada em número de passos, e ABAIXO do ponto de virada em dólares

Então a recomendação honesta é essa: adote pelo comportamento do agente, menos passos e menos desvio

E trate a economia em dinheiro como consequência de escala, não como garantia. Se prometerem redução de custo pro seu projeto sem saber o tamanho dele, é achismo

Conclusão

O gargalo do seu agente em base grande raramente é o modelo

É a sequência de descoberta: listar, abrir, reler, pedir mais contexto, e só depois pensar

O CodeGraph ataca essa sequência trocando ela por uma consulta a um grafo que já estava montado, local, atualizado por eventos de arquivo

Próximo passo concreto, se você quiser tirar a prova: roda npx @colbymchenry/codegraph, dá um codegraph init no MAIOR projeto que você tiver por aí e faz a mesma pergunta de arquitetura com e sem o índice

Compara os passos que o agente deu nos dois casos, e aí sim decide se fica

até o próximo post! 😀