CodeGraph é 100% local: o que isso significa para código que não pode sair da máquina

Tem empresa que barra ferramenta de IA por um motivo bem simples: o código não pode sair da máquina

Não é frescura, é contrato assinado. NDA, propriedade intelectual, revisão de segurança interna, aquele cliente que exige que nada do repositório dele toque servidor de terceiro

E aí entra o CodeGraph, projeto open source mantido por Colby McHenry sob licença MIT. Ele se descreve como 100% local: sem componente de nuvem e sem chave de API pra indexar o teu projeto

O repositório passa de 66,7 mil estrelas no GitHub e a versão atual é a 1.5.0, publicada em 21/07/2026, apelidada de "The Rust engine release"

Só que "local" virou palavra de marketing, né? Então bora abrir a caixa e ver onde o código realmente passa 🙂

O que "local" significa aqui: onde o código realmente passa

A alegação de local só vale se a cadeia técnica sustentar ela. E nesse caso dá pra apontar cada peça

A indexação é feita com tree-sitter, com gramáticas compiladas dentro de um kernel nativo em Rust. O parser lê teu código e extrai duas coisas: nós (funções, classes, métodos) e arestas (calls, imports, extends, implements)

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

Repara no ponto: isso é parsing determinístico. Não tem envio de código pra um modelo, não tem serviço de embeddings do outro lado do fio

É a diferença entre um compilador e um tradutor humano. O parser lê a sintaxe e monta a estrutura sempre igual, sem precisar "entender" nada em uma GPU remota

O resultado disso tudo vai pra um arquivo SQLite em .codegraph/codegraph.db, com busca full-text via FTS5. Um arquivo, dentro do teu projeto

E como o agente consulta esse grafo? Por MCP

"Que MCP?" O Model Context Protocol, o padrão que os agentes usam pra falar com ferramentas externas. O CodeGraph roda como servidor MCP na tua máquina, e o agente pergunta pra ele em vez de sair lendo arquivo por arquivo

Biblioteca, CLI e servidor MCP: as três pontas rodam do teu lado

O que muda na prática para código sob NDA e propriedade intelectual

Agora traduzindo isso pra critério de adoção, que é o que interessa quando alguém do time de segurança senta na mesa

Não existe dependência de serviço externo pra construir o índice. Sem conta, sem chave de API, sem "crie um projeto no painel". O codegraph init roda e o grafo nasce ali

O índice vive dentro do repositório. Todo o estado do projeto fica na pasta .codegraph/, o que torna a resposta pra pergunta "onde os dados ficam?" bem curta

Dá pra auditar. É MIT e o código está aberto, então a revisão interna não precisa acreditar em post de blog (nem neste aqui!), pode ler o repositório

Esse critério de onde o dado mora já apareceu por aqui quando falamos de ferramentas local-first e privacidade, e é sempre a mesma pergunta de fundo

Um aviso honesto pra não te vender ilusão: não vou dizer que o CodeGraph atende norma X ou certificação Y, porque isso não está documentado em lugar nenhum que dê pra citar. O que dá pra afirmar é a arquitetura

Cenários em que rodar local decide a adoção

1. Empresa que proíbe envio de código a terceiros

Aqui o bloqueio costuma ser binário: se a ferramenta pede API key pra indexar, morreu na primeira reunião. Como o índice do CodeGraph é construído sem chave e sem serviço externo, a conversa muda de "não pode" pra "vamos revisar"

2. Consultoria com NDA por cliente

Cada cliente, um repositório, um contrato diferente. Com o servidor MCP rodando local e o grafo dentro da pasta do próprio projeto, o isolamento acompanha a estrutura que tu já tem no disco

3. Monorepo gigante em que o agente precisa de mapa

Esse é o caso clássico. O agente não consegue segurar o monorepo inteiro no contexto, então ou ele lê arquivo por arquivo, ou ele consulta um mapa

E o mapa se mantém sozinho: o auto sync vem ligado por padrão, com file watchers nativos observando o projeto e atualizando o grafo a cada mudança de arquivo, inclusive as edições que o próprio agente faz

O índice também não engorda com lixo: node_modules, vendor, dist, build, target, .venv, Pods, .next e similares ficam de fora automaticamente, mesmo sem .gitignore. E o que estiver no teu .gitignore é honrado

4. Máquina corporativa com rede restrita ou pipeline de CI

Como não tem chave de API nem conta no meio, o passo de indexar não depende de liberar endpoint de fornecedor no firewall

Tome cuidado com um detalhe aqui: o instalador baixa o bundle do GitHub Releases, e o projeto não declara oficialmente operação em ambiente air gapped depois de instalado. Então não prometa isso pro time de infra sem testar antes

Vale lembrar que o CodeGraph só entrega o mapa, quem mexe no código é o agente. Quem quiser fechar o cerco dos dois lados, dá uma olhada em permissões e sandbox do Codex também

A telemetria: o que é coletado, o que não é e como desligar

Agora o ponto que sempre acende o alerta do time de segurança

O sintoma: a ferramenta se vende como 100% local, mas tem telemetria com o toggle ligado por padrão. Pra quem revisa segurança, isso soa contraditório na hora

A causa: o CodeGraph coleta estatísticas anônimas de uso. Quais comandos e ferramentas são usados, quais linguagens são indexadas, quais agentes dirigem o uso. Esses eventos são agregados localmente em totais diários antes do envio

O instalador interativo (codegraph install) pergunta na hora, com o toggle visível e o padrão ligado, e não pergunta de novo. Ou seja: se tu saiu apertando enter sem ler o que estava na tela, ficou ligado

Segundo o TELEMETRY.md do projeto, o que ele nunca coleta é: código, caminhos de arquivo, nomes de arquivo ou de símbolo, queries de busca e endereços IP

A solução: existem três caminhos documentados pra desligar

E desligada significa desligada de verdade: não registra nada, não abre conexão com o endpoint e não envia nem ping de opt out

Transparência do destino: os eventos vão por POST pra telemetry.getcodegraph.com, um endpoint first party cujo código do worker vive em telemetry-worker/ no próprio repositório. Ele valida cada evento contra uma allowlist, remove IPs, aplica rate limit e encaminha pra um armazenamento de analytics gerenciado (PostHog, região US) como eventos anônimos

Como prevenir em vez de remediar: definir a variável de ambiente antes de instalar na máquina corporativa. Coloca CODEGRAPH_TELEMETRY=0 (ou DO_NOT_TRACK=1) no provisionamento e o toggle do instalador deixa de ser um ponto de falha humano

A pasta .codegraph/ pode vazar para o Git: a falha aberta

Esse aqui é o segundo risco prático, e ele é bem mais silencioso que o primeiro

O sintoma: o índice do teu código-fonte acaba versionado e vai junto no push. Um arquivo SQLite com a estrutura inteira do projeto, dentro do histórico do repositório

A causa: o CodeGraph gera um .gitignore dentro da própria pasta .codegraph/, mas a issue #492 relata que esse arquivo não impede a pasta de continuar rastreável pelo Git

A solução: o .gitignore do próprio repositório do CodeGraph lista .codegraph/ como diretório de dados que não deve ser rastreado. Faça o mesmo no teu

.codegraph/

Transforma isso em item de checklist antes do primeiro commit depois de rodar o init, beleza? É uma linha que evita uma conversa desagradável com o cliente depois

Como instalar o CodeGraph sem depender de serviço externo

São três passos distintos, e é justamente aí que a maioria tropeça. Instalar o CLI, registrar o servidor MCP no agente e indexar o projeto. Vou por partes, com o erro típico de cada um

1. Instalar o CLI:

npm install -g @colbymchenry/codegraph

Ou sem instalar nada global:

npx @colbymchenry/codegraph

O erro comum deste passo: máquina corporativa sem Node, sem npm ou sem build tools liberadas. Pra esse caso existe o instalador via shell, que baixa um bundle self-contained (com runtime Node embutido) a partir do GitHub Releases:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Sem Node, sem build tools, sem npm. Resolve a máquina travada pelo TI 🙂

2. Registrar o servidor MCP no teu agente:

codegraph install

O erro comum deste passo (e é o mais frequente de todos): instalar o CLI sozinho NÃO registra o MCP. Se tu parar no passo 1 e for perguntar pro agente, ele simplesmente não conhece a ferramenta

Esse instalador é interativo: ele detecta e auto configura Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE e Kiro, ligando o servidor MCP do CodeGraph em cada um. Se tu quiser sem prompt, existe o codegraph install --yes

É aqui também que aparece o toggle de telemetria que citei lá em cima, com padrão ligado. Olho vivo na hora que ele perguntar

3. Indexar o projeto:

codegraph init

Rode dentro da pasta do projeto. Ele cria o .codegraph/ e constrói o grafo

O erro comum deste passo: sair commitando logo em seguida sem ter colocado .codegraph/ no .gitignore (aquela issue #492 do tópico anterior)

Pra manter atualizado depois, tem comando próprio:

codegraph upgrade

Ele detecta se a instalação foi por bundle, npm ou npx e atualiza no lugar. Bem prático 😀

Vale adotar em ambiente com código fechado?

Veredito curto e honesto

O núcleo (indexação, grafo e consulta do agente) roda na máquina e é auditável, porque é MIT e o código está aberto. Não tem chave de API no caminho, não tem serviço externo construindo o índice

A única saída de rede documentada é a telemetria anônima de uso, que tem três formas de desligar e que, segundo a documentação do projeto, não carrega código nem identificadores do teu projeto

Quem for levar isso pra dentro de empresa deveria tratar dois itens como pendência aberta, não como detalhe:

• desligar a telemetria por variável de ambiente já na provisão da máquina, e não confiar no toggle do instalador
• garantir .codegraph/ fora do Git, por causa da issue #492

Resolvidos esses dois, o que sobra é uma ferramenta cuja arquitetura você consegue explicar linha a linha pro time de segurança. E isso, em ambiente com NDA, vale mais que qualquer feature list

Conclusão

"Local" aqui não é slogan, é propriedade da arquitetura: tree-sitter fazendo parsing determinístico, SQLite guardando o grafo dentro do projeto e um servidor MCP rodando na tua máquina

Dá pra verificar cada uma dessas peças sem acreditar em ninguém, e é exatamente isso que faz a diferença numa revisão interna

Próximo passo, se o assunto te pegou: abre o TELEMETRY.md e o LICENSE no repositório antes de levar a proposta pro time de segurança, porque as duas perguntas que vão te fazer estão lá

Depois roda um codegraph init num projeto de teste e vê o grafo nascer sem nenhuma chave de API. É meio insano ver isso funcionando offline no teu próprio disco…

Até o próximo post! =)