Auto sync do CodeGraph: por que você não precisa reindexar o código a cada mudança?

Você renomeia uma função, salva, pede pro agente mexer nela

e ele volta citando o nome antigo, com toda a confiança do mundo 😅

O chato não é o erro em si, é que nada acusa o erro. O índice não grita "olha, eu estou velho", ele só responde do jeito que sabe responder

O auto sync do CodeGraph existe pra matar exatamente esse ponto cego: o grafo acompanha as mudanças do código enquanto você trabalha, sem depender de você lembrar de reindexar

Bora entender COMO isso funciona por baixo?

O que é o CodeGraph e o que ele indexa

Antes de falar de sync, um passo atrás pra quem chegou agora pelo tema

O CodeGraph é um grafo de conhecimento de código pré-indexado, voltado pra agentes tipo Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro e Hermes Agent

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 15min

Conhecer formação

A ideia é simples: em vez do agente sair lendo arquivo por arquivo pra descobrir quem chama quem, ele consulta um índice que já sabe

E como esse índice é feito? O CodeGraph analisa o código com tree-sitter e guarda símbolos, arestas e arquivos num banco SQLite local, com busca full-text FTS5. Os dados do projeto ficam em .codegraph/

Outro detalhe que muda tudo: é local-first, roda inteiramente na sua máquina, sem serviços externos

Esse papo de não mandar seu código pra lugar nenhum é o mesmo tipo de escolha de quem prefere usar o DeepSeek sem a API: menos dependência de fora, mais controle

Atribuição, que aqui importa: o projeto é criado e mantido por Colby McHenry, no repositório colbymchenry/codegraph, sob licença MIT

O problema do índice estático: envelhecer em silêncio

O sintoma

O agente cita uma função que você já renomeou

Ou abre um caminho de arquivo que já não existe

Ou sugere "reaproveitar" um helper que você deletou ontem

E em nenhum momento aparece um erro. A resposta vem redondinha, bem escrita e ERRADA, o que é bem pior do que vir quebrada

A causa

Índice estático é uma foto

Tirada num instante, congelada ali, enquanto o código continua andando. Cada commit, cada refactor, cada git pull aumenta a distância entre a foto e a realidade

Se você conhece cache de aplicação, é o mesmo drama: o problema nunca é o cache existir, é ninguém invalidar ele

A solução: três camadas rodando juntas

O auto sync vem ligado por padrão. Quando o agente sobe o servidor MCP, o CodeGraph mantém o índice em dia por três frentes:

1. File watcher com auto sync debounced

O watcher usa eventos nativos do sistema operacional: FSEvents no macOS, inotify no Linux, ReadDirectoryChangesW no Windows

Ele captura criação, modificação e remoção de arquivos de código. A reindexação dispara depois de uma janela de debounce, com padrão de 2000 ms

"E por que esperar 2 segundos?" Porque você não edita um arquivo por vez. Salvou dez arquivos numa rajada de refactor? Vira uma única sincronização, em vez de dez reindexações se atropelando

2. Banner de arquivo desatualizado

Essa é a parte esperta, se liga

Durante a janela de debounce existe um vão: o arquivo mudou, o grafo ainda não sabe. Se alguma resposta de ferramenta MCP fosse citar justamente um arquivo pendente de reindexação, o CodeGraph prefixa a resposta com um banner de aviso, nomeando o arquivo

Ou seja: o índice pode estar alguns segundos atrás, mas ele não mente em silêncio

3. Reconciliação no connect time

E o que muda enquanto o servidor MCP está fora do ar?

Um git pull no terminal, uma edição em outro editor, o agente que você encerrou ontem à noite. Nenhum watcher viu nada disso acontecer

Na reconexão do agente ao servidor MCP, o CodeGraph roda uma reconciliação por sistema de arquivos antes de responder a primeira consulta: um pré-filtro por tamanho e mtime, depois hash de conteúdo no que sobrou

Resultado: essas mudanças entram no índice logo na primeira chamada da sessão seguinte

Entender essa terceira camada é o que evita o medo de "será que ele viu o pull?"

Reindexação manual x auto sync: o que muda na prática

A tabela abaixo compara o hábito de reindexar na mão com o que o auto sync faz sozinho:

Repara que a coluna da direita não ganha por ser mais rápida

Ela ganha por tirar você do loop

Por que o sync deixou de doer na versão 1.5.0

Sincronizar a cada save só é viável se sincronizar for barato, né?

A versão 1.5.0, publicada em 21/07/2026, reconstruiu o motor de parsing como um kernel nativo em Rust, e é aí que a conta fecha

Segundo a nota dessa versão, a atualização do grafo virou praticamente instantânea: saves chegando ao grafo em bem menos de um segundo mesmo num repositório de 27.000 arquivos

O kernel nativo cobre 20 linguagens, entre elas TypeScript, JavaScript (com TSX/JSX), Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua e Luau

E tem um número que corre por fora dessa reescrita, do benchmark do próprio projeto: a remedição de agosto de 2026 aponta 88% menos chamadas de ferramenta e 62% menos tokens

Número do projeto, não medição nossa, fica o registro. E repara que ele não mede o kernel em Rust, mede outra coisa: agente que consulta um índice em vez de sair lendo arquivo por arquivo procura menos, e procurar menos é onde o token some

Como deixar o auto sync rodando no seu projeto

São três passos, e a maior parte da confusão mora em achar que tem mais 😀

1. Instale global

npm i -g @colbymchenry/codegraph

O erro comum aqui é repetir a instalação global a cada projeto novo. A global cobre todos, você faz isso uma vez na máquina

2. Registre o servidor MCP nos agentes

codegraph install

Esse é um passo SEPARADO da instalação, e é o que faz seu agente enxergar o CodeGraph. Instalar o pacote e parar por aí é o tropeço clássico

3. Inicialize o projeto

codegraph init

O codegraph init cria o diretório local .codegraph/ e constrói o grafo completo do projeto no mesmo passo

O erro comum deste passo: achar que o init precisa rodar a cada mudança de código. Não precisa. Ele roda uma vez por projeto, e depois disso o auto sync já está ligado por padrão, observando o projeto e atualizando o grafo a cada mudança de arquivo, sem configuração

Ajuste opcional: se 2000 ms não for a janela que você quer, dá pra mexer no debounce pela variável de ambiente CODEGRAPH_WATCH_DEBOUNCE_MS, dentro da faixa de 100 ms a 60 s

Janela menor reage mais rápido, janela maior agrupa mais edições numa sincronização só. Escolha sua aventura

Quando ainda faz sentido rodar codegraph sync na mão

O comando manual não sumiu, ele só virou exceção

O codegraph sync é uma sincronização manual incremental: ele processa só os arquivos alterados, o que é mais rápido do que reconstruir tudo do zero

Os casos citados pelo projeto em que ele ainda entra:

• watcher desabilitado
• sandboxes que bloqueiam file watchers
• execução com CODEGRAPH_NO_DAEMON=1
• um sync de pré-voo no início de um script de CI

O ponto comum entre eles? São situações onde o watcher não tem como fazer o trabalho dele, e não situações do dia a dia

E antes de sair rodando por precaução, tem um jeito melhor de decidir:

codegraph status

O codegraph status mostra o estado de sincronização, e exibe uma seção de sync pendente nomeando os arquivos e a idade da edição quando tem algo na fila

Se a fila está vazia, você não precisa fazer nada. Massa, né?

Conclusão

O valor do auto sync do CodeGraph não é ser rápido

Velocidade é consequência do kernel em Rust da 1.5.0. O valor de verdade é outro: o índice estar certo deixou de depender da sua memória

Índice estático não avisa que envelheceu, e é justamente por isso que ele estraga resposta de agente sem levantar suspeita. As três camadas (watcher com debounce, banner nomeando o arquivo pendente e reconciliação na hora da conexão) existem pra fechar esse vão em vez de confiar na sua disciplina

Próximo passo se você já tem o CodeGraph no projeto: roda um codegraph status e olha a seção de sync pendente

Edita um arquivo, roda de novo e vê o mecanismo trabalhando na sua frente. É a melhor forma de confiar nele…

até o próximo post! 😀