CodeGraph — Pré-Indexe Seu Código para Agentes de IA, Economize 35% em Custos e 70% em Chamadas de Ferramentas

Introdução

"~35% mais barato · ~70% menos chamadas de ferramentas · 100% local"

Este é o artigo nº 71 da série "Um Projeto de Código Aberto por Dia". Hoje estamos explorando CodeGraph.

Comece com um cenário: você pergunta ao Claude Code "Como o AuthService está sendo chamado?" Sem qualquer assistência, a abordagem do Claude é: escanear diretórios, executar múltiplos greps, ler vários arquivos — e então finalmente responder. Todo o processo pode acionar de 10 a 15 chamadas de ferramentas e consumir centenas de milhares de tokens.

A percepção do CodeGraph é carregar esse trabalho antecipadamente: antes de você começar, ele já analisou seu código com tree-sitter em um grafo semântico armazenado em um banco de dados SQLite local, e então expõe 8 ferramentas de consulta para agentes de IA via MCP. Quando o agente precisa entender o código, uma única chamada codegraph_context retorna pontos de entrada, símbolos relacionados e trechos de código — sem necessidade de leitura de arquivos.

9.6k Estrelas, 588 Forks. Benchmarks em 7 projetos de código aberto reais: média de 35% de economia de custos, 70% menos chamadas de ferramentas, 49% de melhoria de velocidade. No grande repositório TypeScript do VS Code, uma pergunta e resposta de arquitetura caiu de 1.4M tokens para 393k — custo de $0.64 para $0.42.

O Que Você Vai Aprender

• O pipeline de quatro etapas do CodeGraph: Extrair → Armazenar → Resolver → Auto-Sincronizar
• As 8 ferramentas MCP e quando usar cada uma
• Uma análise detalhada dos resultados de benchmark em 7 projetos: por que bases de código maiores se beneficiam mais?
• Como funciona o suporte a 19 linguagens e o reconhecimento de rotas de 13 frameworks
• Um walkthrough completo de configuração, da instalação à integração com Claude Code
• codegraph affected: usando rastreamento de dependências para seleção inteligente de testes CI

Pré-requisitos

• Familiaridade com Claude Code, Cursor ou ferramentas de codificação de IA similares
• Compreensão básica do MCP (Modelo de Protocolo de Contexto)
• Experiência com Node.js

Histórico do Projeto

Introdução ao Projeto

CodeGraph é uma ferramenta de grafo de conhecimento semântico de código local projetada especificamente para melhorar a eficiência de agentes de codificação de IA. Sua percepção central:

Agentes de IA gastam uma quantidade massiva de tokens e tempo na "fase de descoberta" — escaneando diretórios, procurando símbolos, lendo arquivos — ao invés de se concentrar no raciocínio e geração reais.

A solução do CodeGraph é externalizar a fase de descoberta para um índice pré-construído: antes de você começar a trabalhar, o índice já está pronto, permitindo que os agentes de IA puxem conhecimento de código estruturado diretamente em vez de explorar o sistema de arquivos do zero.

As escolhas tecnológicas são pragmáticas: tree-sitter para análise de AST (maduro, multi-linguagem, alto desempenho), SQLite FTS5 para busca de texto completo (sem dependências externas, totalmente local), e eventos de arquivo nativos do SO para sincronização ao vivo (FSEvents/inotify/ReadDirectoryChangesW).

Autor/Equipe

• Autor: Colby McHenry (GitHub: colbymchenry)
• Repositório: colbymchenry/codegraph
• Distribuição: pacote npm @colbymchenry/codegraph

Estatísticas do Projeto

• ⭐ Estrelas no GitHub: 9.600+
• 🍴 Forks: 588
• 📦 pacote npm: @colbymchenry/codegraph
• 🔧 Tempo de execução: Node.js 20–24
• 💻 Plataformas: Windows, macOS, Linux
• 📄 Licença: MIT
• 🌐 Repositório: colbymchenry/codegraph

Principais Recursos

Utilidade Principal

CodeGraph insere uma camada de índice pré-construído entre agentes de IA e bases de código:

Base de Código (TypeScript / Python / Go / ...)
        ↓ análise tree-sitter
  Grafo semântico (símbolos + relacionamentos + cadeias de chamadas)
        ↓ armazenado em SQLite FTS5
  Base de conhecimento local
        ↓ exposto via MCP
  Agentes de codificação de IA (Claude Code / Cursor / Codex CLI / OpenCode)

Sem CodeGraph:

Usuário: "Como o AuthService está sendo chamado?"
→ Agente: glob("src/**/*.ts")         # Chamada de ferramenta 1
→ Agente: grep("AuthService")         # Chamada de ferramenta 2
→ Agente: ler("auth.service.ts")     # Chamada de ferramenta 3
→ Agente: grep("import.*Auth")        # Chamada de ferramenta 4
→ Agente: ler("user.controller.ts")  # Chamada de ferramenta 5
→ Agente: ler("app.module.ts")       # Chamada de ferramenta 6
... 10–15 chamadas de ferramentas no total, consumo massivo de tokens

Com CodeGraph:

Usuário: "Como o AuthService está sendo chamado?"
→ Agente: codegraph_callers("AuthService")   # Chamada de ferramenta 1
→ Retorna: lista completa de chamadores  + locais de chamada + trechos de código
→ Agente responde diretamente, sem necessidade de leitura de arquivos

Início Rápido

Instalação com um comando (recomendado):

# Execute o instalador interativo — detecta automaticamente agentes de IA instalados e os configura
npx @colbymchenry/codegraph

# Inicialize em seu projeto (-i para interativo)
cd seu-projeto
codegraph init -i

Instalação não interativa (ambientes CI):

# Detecta automaticamente todos os agentes instalados, instalação global
codegraph install --yes

# Alvo de agentes específicos
codegraph install --target=cursor,claude --yes

# Instalação local do projeto
codegraph install --target=auto --location=local

Configuração manual do Claude Code:

npm install -g @colbymchenry/codegraph

Adicione ao ~/.claude.json (ou ao .claude.json no nível do projeto):

{
  "mcpServers": {
    "codegraph"