Graphify local-first: o seu código sai da máquina ou não?

Fala aí, beleza? Existe um medo que todo mundo de código fechado conhece bem: instalar a ferramenta de IA da moda e descobrir depois que o repositório inteiro foi parar num servidor de terceiro

E é um medo justo, não é paranoia

O graphify é uma skill /graphify para assistentes de código (Claude Code, Cursor, Codex e Gemini CLI) que pega um projeto (código, docs, schemas SQL, configs e PDFs) e transforma tudo num grafo de conhecimento consultável

A proposta é mto massa, mas pra quem tem NDA na mesa a pergunta é outra, e é ela que a gente responde aqui: ONDE esse código é processado?

Como o graphify lê o código sem mandar nada para fora

A documentação oficial é direta nesse ponto: "Code is parsed with tree-sitter AST: deterministic, no LLM, nothing leaves your machine"

Ou seja, o código-fonte é parseado localmente, de forma determinística, sem LLM e sem sair da máquina

Formação Recomendada

Formação Claude Code

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

• 110 aulas
• 4 projetos
• 9h 2min

Conhecer formação

Que AST? É a árvore sintática do arquivo

Um parser lê o texto do seu código e monta uma estrutura com o que está escrito ali: função, classe, import, herança, chamada

As arestas de calls, imports e inherits do grafo vêm direto dessa árvore, sem custo de API

E aqui está o PORQUÊ de isso funcionar sem modelo nenhum: a estrutura já está no arquivo

Se você conhece o "ir para definição" do seu editor ou um linter, é a mesma família de coisa

Ninguém precisa de um modelo de linguagem pra saber que o arquivo A importa o arquivo B, isso está literalmente escrito lá

Determinístico significa que o mesmo arquivo gera sempre o mesmo resultado, sem interpretação criativa no meio

A descrição oficial do repositório resume o desenho em uma linha: "local deterministic AST parsing, every edge explained, no vector store"

O projeto vive sob a organização Graphify Labs, no repositório oficial Graphify-Labs/graphify

Se você guardou o link antigo, relaxa: a URL github.com/safishamsi/graphify aponta pro mesmo repositório

O que roda local e o que usa modelo externo

Aqui mora a parte que mais gera confusão, então bora separar direitinho

A fronteira do graphify local-first não é "o produto inteiro é offline"

A fronteira é o TIPO de arquivo que entra no corpus

A documentação é explícita: "If a corpus contains only code files, Pass 3 is skipped entirely; semantic extraction is reserved for docs, papers, images, and transcripts"

Traduzindo pro seu dia a dia: arquivos de código não são enviados ao extrator semântico no pipeline normal

A doc também afirma que um corpus só de código não exige chave de API e que graphify extract roda totalmente offline

Então a decisão de privacidade fica na sua mão, e ela é uma só: o que você joga dentro do corpus

Se o README interno com arquitetura do cliente entra junto, ele passa pelo passo semântico

Quando o extract pede chave de API mesmo sem precisar

Agora a parte honesta, porque tem um atrito relatado aqui

O sintoma: você aponta o graphify pra uma base só de código e o comando de extração pede uma chave de LLM assim mesmo

A reação natural é imaginar o pior ("então ele VAI mandar meu código pra algum lugar")

A causa apontada: a issue #1122 do repositório descreve exatamente isso, "extract requires an LLM API key for code-only corpora, even though code extraction makes no LLM calls"

O motivo levantado é de ordem de execução: detect_backend() é resolvido ANTES da detecção da composição dos arquivos

Ou seja, o programa decide qual backend de modelo vai usar antes de olhar se existe algum arquivo que precisa de modelo

A correção proposta na issue: adiar a resolução do backend e só exigir chave quando houver arquivos semânticos no corpus ou quando --dedup-llm for usado

Não consegui confirmar se essa correção já entrou e em qual versão, então não vou te vender "roda offline sem chave" como passo garantido

Como prevenir a conclusão errada: trate a exigência da chave como um sinal pra conferir a composição do corpus, não como prova de que houve envio de código

A própria issue diz que a extração de código não faz chamadas ao modelo

Na dúvida, olha primeiro o que foi incluído: entrou doc? entrou PDF? entrou imagem?

Para quem o local-first muda o jogo

Pra quem só tem projeto pessoal no GitHub público, isso aqui é detalhe

Pra esses perfis abaixo, é o critério de compra inteiro:

• Times com política de não enviar código para serviços externos. Dá pra mapear a base sem que o processamento do código dependa de terceiro, porque a árvore sintática é montada na máquina
• Consultoria sob NDA, com código de cliente na máquina. O mapa do projeto sai sem que o fonte do cliente vire input de um serviço de fora
• Setores regulados. O que pesa aqui é conseguir apontar qual etapa usa modelo e qual não usa, em vez de responder "a ferramenta é segura, confia"
• Repositório interno gigante e sem dono. Aquele monolito que ninguém entende inteiro, e que justamente por ser crítico não pode ser despejado num serviço externo
• Gente de produto e liderança técnica. Quem quer entender a base sem abrir arquivo por arquivo, na mesma linha de usar IA sem programar no dia a dia

Em todos eles o ponto prático é o mesmo: a inclusão de docs e PDFs no corpus vira uma decisão consciente, não um efeito colateral

Auditabilidade: onde o resultado fica e como conferir cada aresta

Privacidade sem auditabilidade é só promessa, né?

A saída do graphify fica numa pasta local do próprio projeto, graphify-out/, com quatro coisas dentro:

• graph.html: o grafo interativo pra você navegar
• GRAPH_REPORT.md: um resumo em linguagem simples, na pegada de quando você escreve um pseudocódigo pra explicar uma lógica pra outra pessoa
• graph.json: o grafo persistente, usado pra consulta
• cache/: cache baseado em SHA256, que só reprocessa arquivo alterado

Esse cache por hash tem um efeito prático bom: rodar de novo depois de mudar dois arquivos não significa reprocessar o projeto inteiro

E a pasta foi pensada pra ser versionada junto com o repositório, nas palavras da doc: "The directory is designed to be committed, so a teammate who pulls gets the map without rebuilding"

Quem dá pull recebe o mapa pronto, sem reconstruir

Tome cuidado com um detalhe aqui: eu não confirmei se o graph.json guarda trechos literais de código ou apenas nomes e relações

Se o seu repositório é fechado e você vai commitar a pasta, abre o arquivo e olha antes, é um minuto de trabalho

Agora a parte que mais gosto do desenho: não existe vector store, e cada aresta do grafo vem marcada como EXTRACTED (explícito na fonte) ou INFERRED (resolvido pelo graphify)

Isso muda a conversa de lugar

Em vez de aceitar um resultado de caixa-preta, você consegue perguntar de cada ligação: isso está escrito no código ou a ferramenta deduziu?

Vale confiar? O que está documentado e o que está em aberto

Bora fechar sem hype dos dois lados

O que está documentado e é verificável:

• parsing de código local, determinístico, com tree-sitter, sem LLM
• Pass 3 pulado por completo quando o corpus só tem arquivos de código
• saída inspecionável em arquivos locais dentro do próprio projeto
• arestas rotuladas como EXTRACTED ou INFERRED, sem vector store
• a afirmação da doc de que corpus só de código roda totalmente offline, sem chave de API

O que fica em aberto:

• o atrito relatado na issue #1122, com o pedido de chave de API em corpus só de código, sem confirmação de correção
• docs, PDFs, imagens e vídeo continuam usando o modelo do assistente ou uma API key configurada, isso é desenho, não bug

E a adoção? O repositório passou de 100 mil estrelas no GitHub, marca atingida em 01/08/2026

Isso é sinal de tração e de olhos em cima do projeto, o que ajuda

Mas estrela não é prova técnica de privacidade, e seria zoado tratar como se fosse

Conclusão

Respondendo a pergunta do título: no fluxo de código, o desenho é local-first e o fonte não sai da máquina, com a extração semântica sendo pulada quando o corpus só tem código

Quem sai da máquina são os arquivos NÃO código que você decidir incluir

O próximo passo concreto, se quiser conferir com os próprios olhos:

1. Instale a ferramenta:

uv tool install graphifyy && graphify install

O erro comum deste passo: o pacote no PyPI é graphifyy (com dois "y"), mas o comando de linha continua sendo graphify

2. Rode a extração (graphify extract) num projeto seu, de preferência começando por um corpus só de código

O erro comum deste passo: jogar a pasta de docs junto na primeira rodada e depois não saber dizer o que passou pelo passo semântico

3. Abra GRAPH_REPORT.md e graph.html dentro de graphify-out/ e inspecione o resultado localmente

4. Só DEPOIS decida se vale incluir docs, PDFs, imagens e vídeo no corpus, sabendo que esses usam modelo

5. Pra atualizar mais tarde:

uv tool upgrade graphifyy
graphify install

O erro comum deste passo: rodar só o upgrade e esquecer do graphify install

É isso, faça o teste e tire suas conclusões olhando os arquivos gerados, que é bem melhor do que confiar em post de blog (inclusive neste aqui) 😀

até o próximo post!