Guia de Configuração do CodeGraph 2026: Reduza Chamadas de Ferramentas do Claude Code em 58%

Este artigo foi publicado originalmente em aifoss.dev

Resumo: O CodeGraph v0.9.9 é um servidor MCP local que pré-indexa sua base de código usando tree-sitter e SQLite, e então serve um gráfico de conhecimento de símbolos para o Claude Code e Cursor, em vez de deixar o agente grep e ler arquivos em cada consulta. Benchmarks oficiais em sete bases de código reais mostram 58% menos chamadas de ferramentas, 47% menos tokens e 16% menos custo de API — validado no Claude Opus 4.8 em 2 de junho de 2026. Três comandos de instalação. Licença MIT. Nada sai da sua máquina.

O que você terá funcionando após este guia:

• Servidor MCP do CodeGraph conectado ao Claude Code e/ou Cursor
• Sua base de código pré-indexada em um gráfico de conhecimento SQLite local
• Re-indexação incremental em cada salvamento de arquivo via eventos de arquivo nativos do SO

Opinião honesta: Para usuários do Claude Code e Cursor, a versão colbymchenry é a que deve ser instalada. Ela possui benchmarks públicos, desenvolvimento ativo (v0.9.9 lançada em 2 de junho de 2026) e um instalador de um comando que auto-configura ambos os agentes. Mude para codegraph-ai apenas se a extensão do VS Code for mais importante do que números verificados.

Por que o Claude Code lê tantos arquivos

Quando você pergunta ao Claude Code "como o middleware de autenticação valida tokens JWT?" o agente não tem um mapa do seu projeto. Ele lê arquivos, executa greps, segue imports, lê mais arquivos. Em uma base de código TypeScript de 1.000 arquivos, responder a uma pergunta de arquitetura pode consumir de 15 a 30 chamadas de ferramentas antes que o agente tenha coletado contexto suficiente para responder.

Esse é o comportamento esperado de um agente que lê arquivos operando sem um índice pré-construído. Ele explora o gráfico de código no momento da consulta, o que é lento e consome tokens. Quanto maior o repositório, pior a sobrecarga da exploração escala.

O CodeGraph resolve isso construindo o gráfico antes que a sessão comece. Em vez de leituras de arquivos e greps, o Claude Code emite de 1 a 3 chamadas MCP estruturadas para um banco de dados SQLite local e recebe de volta relacionamentos de símbolos, cadeias de chamadas e mapas de importação diretamente.

Como o Índice Funciona

Três componentes são executados localmente:

tree-sitter analisa cada arquivo de origem em uma AST. Consultas específicas de linguagem extraem nós (funções, classes, métodos, interfaces) e arestas (relacionamentos de chamadas, cadeias de importação, hierarquias de herança). Os idiomas suportados incluem TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Lua, Luau e Pascal/Delphi — mais de 20 no total.

SQLite com FTS5 armazena o gráfico extraído em .codegraph/codegraph.db na raiz do seu projeto. A extensão de busca de texto completo FTS5 lida com consultas como "encontrar todas as utilizações de UserService" em tempo sub-milissegundo, sem escaneamento de arquivos. O índice para um repositório do VS Code com 10k arquivos cabe em menos de 200 MB.

Um servidor MCP envolve o banco de dados e expõe ferramentas ao seu agente. O servidor observa o diretório do projeto usando eventos de arquivo nativos do SO (FSEvents no macOS, inotify no Linux) com uma janela de debounce de 2 segundos. Quando você salva um arquivo, apenas aquele arquivo é re-indexado — atualizações incrementais normalmente terminam em menos de 100 ms.

O servidor MCP também envia seu conjunto completo de instruções ao Claude Code na inicialização via src/mcp/server-instructions.ts, para que o Claude Code aprenda a consultar o gráfico de forma eficaz sem que você precise modificar seu CLAUDE.md.

Benchmarks

Os benchmarks oficiais do CodeGraph são executados contra sete bases de código open-source reais, revalidadas no Claude Opus 4.8 em 2 de junho de 2026 (v0.9.9):

Os números do VS Code são o caso máximo — 81% menos chamadas de ferramentas porque repositórios maiores acumulam a maior sobrecarga de descoberta de arquivos sem um índice. Os ganhos diminuem à medida que o tamanho do repositório diminui. Abaixo de aproximadamente 100 arquivos, você verá melhorias mínimas.

Dados independentes da comunidade: um desenvolvedor testando em quatro repositórios privados encontrou uma mediana de 70% menos chamadas de ferramentas, 59% menos tokens e 49% mais rápido no tempo de resposta (fonte).

Instalação

Pré-requisitos

O CodeGraph v0.9.9 requer Node.js 22+ para uso de biblioteca programática. O CLI e o servidor MCP incluem seu próprio runtime, portanto, uma instalação global funciona sem gerenciar uma versão do Node manualmente. Se você estiver atualizando de uma versão anterior a 0.9 em Node 24, reinstale do zero para puxar as novas ligações nativas do SQLite.

Execute codegraph status após a instalação para confirmar que o backend é native, não wasm:

Backend:  native (sqlite3 v5.1.7)   ← bom
Backend:  wasm                       ← reinstalação necessária

Três comandos

# 1. Instalar globalmente
npm i -g @colbymchenry/codegraph

# 2. Registrar com seus agentes
codegraph install

# 3. Inicializar o índice no seu projeto
cd /caminho/para/seu/projeto
codegraph init

codegraph install detecta automaticamente quais agentes estão instalados e escreve a configuração do servidor MCP no arquivo de configurações de cada um:

✓ Claude Code   → ~/.claude/mcp_servers.json atualizado
✓ Cursor        → ~/.cursor/mcp.json atualizado
  Codex CLI     → não encontrado, ignorado
  Gemini CLI    → não encontrado, ignorado

codegraph init cria .codegraph/ na raiz do projeto e constrói o primeiro gráfico. Em um projeto Python com 3k arquivos, espere de 10 a 30 segundos. Um repositório TypeScript com 10k arquivos leva até 2 minutos. Após a inicialização, reinicie o Claude Code ou Cursor para que eles carreguem a nova configuração do MCP.

Sua Primeira Consulta Com o Índice

Uma vez que o Claude Code comece com o servidor MCP ativo, verifique /mcp — você deve ver codegraph listado com um status verde. Então pergunte algo que normalmente acionaria uma longa cadeia de descoberta: