Como começar a usar o CodeGraph: install, init, upgrade e uninstall na prática

Fala aí, beleza? Seu agente abre um arquivo, lê, abre outro, lê de novo, e quando você percebe já queimou meia janela de contexto passeando pelo repositório sem responder nada

O CodeGraph ataca exatamente isso: é um grafo de conhecimento de código pré-indexado, roda 100% local e serve agentes como Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro e Hermes Agent

É um bicho bem diferente de ferramenta de IA que vive no navegador, tipo a busca com IA da Perplexity: aqui nada sai da sua máquina, a coisa toda acontece em cima do seu repositório

O projeto é open source, licença MIT, mantido no repositório colbymchenry/codegraph

E o post de hoje é o caminho completo pela CodeGraph CLI: instalar, indexar o primeiro projeto, conferir se o índice está de pé, atualizar e sair sem deixar sujeira 🙂

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

O que você precisa antes de instalar o CodeGraph

A lista é curtinha, se liga:

• Um repositório de código pra indexar (o ideal é começar por um projeto de teste, não pelo monorepo da empresa)
• Um agente suportado já instalado na máquina: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE ou Kiro. Isso importa porque o instalador autodetecta o que já existe por aí e te oferece a configuração pronta
• Node.js só se você quiser ir pelo caminho do npm, seja npm i -g ou npx

Essa última é a parte que mais confunde

O canal standalone dispensa npm, dispensa o Node.js do sistema e dispensa configuração de registry

Ele cobre seis alvos de plataforma: win32-x64, win32-arm64, darwin-x64, darwin-arm64, linux-x64 e linux-arm64, com asset .zip no Windows e .tar.gz no macOS e no Linux com glibc

Ou seja: máquina sem Node, ou empresa com registry trancado, também entra na brincadeira

Install é global, init é por projeto:

Guarda essa frase, ela evita boa parte da confusão que vem depois

Uma única instalação global do CodeGraph cobre todos os seus projetos

O que você repete a cada repositório é o codegraph init, e só ele

Passo a passo: do install ao primeiro grafo indexado

1. Escolha o canal de instalação

No macOS e no Linux, o script oficial:

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

No Windows, pelo PowerShell:

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Já tem Node e prefere o npm? Instala global:

npm i -g @colbymchenry/codegraph

E se você só quer dar uma espiada sem instalar nada globalmente, tem o atalho que baixa e roda em um passo:

npx @colbymchenry/codegraph

O erro comum deste passo: achar que precisa de Node pra qualquer caminho. Não precisa, o bundle standalone é justamente o canal que não pede npm nem Node do sistema

2. Rode o instalador interativo

Dois jeitos, dá no mesmo:

codegraph
# ou
codegraph install

Aqui é a parte legal: ele pergunta quais agentes você quer configurar e autodetecta os que já estão instalados na máquina

Depois ele faz mais três coisas

Pede pra se colocar no PATH (isso é necessário pros agentes conseguirem subir o servidor MCP), pergunta se as configurações valem pra todos os projetos ou só pro atual, e grava a config do servidor MCP de cada agente escolhido

Além disso, ele escreve uma seção própria, delimitada por marcadores, dentro do arquivo de instruções do agente

Que servidor MCP? É por ele que o agente conversa com o CodeGraph em vez de sair lendo arquivo na unha. Por isso o PATH não é frescura: sem ele, o agente não consegue levantar o servidor

O erro comum deste passo: seguir batendo comando no MESMO terminal. O instalador coloca o codegraph no PATH, mas não altera o shell que já estava aberto

3. Abra um terminal novo

Parece bobo, mas é literalmente o passo que mais gera aquele "comando não encontrado" logo depois de uma instalação bem sucedida

Fecha, abre de novo, segue o baile 😀

4. Rode o init na raiz do projeto

codegraph init

Esse comando cria o diretório local .codegraph/ e constrói o grafo completo no mesmo passo, com auto-sync ligado por padrão

Um comando só, sem etapa separada de indexação

O erro comum deste passo: repetir o codegraph install a cada repositório novo achando que a instalação é por projeto. Não é. Install você fez uma vez, o init é o que se repete

5. Confira a saúde do índice

codegraph status

Ele mostra a contagem de nós e arestas do grafo

É o seu "tá de pé?" antes de sair pedindo coisa pro agente. Se o número parecer estranho pro tamanho do projeto, é ali que você percebe

Como atualizar o CodeGraph com codegraph upgrade

Bloco rápido, três variações do mesmo comando:

1. Só verificar se tem versão nova:

codegraph upgrade --check

2. Atualizar no lugar:

codegraph upgrade

O comando detecta como o CodeGraph foi instalado (bundle standalone, npm ou npx) e atualiza naquele mesmo canal

3. Fixar uma versão específica:

codegraph upgrade 1.5.0

Útil quando o time inteiro precisa ficar na mesma régua

Duas notas de bastidor: a partir da v1.5.0, os comandos de instalação e de atualização oferecem, ao terminar, acesso ao beta do CodeGraph Pro, com entrada opcional na lista de espera informando o e-mail

É opt-in, você pode simplesmente não informar nada

E a versão mais recente publicada até aqui é a v1.5.0, de 2026-07-21

O erro comum desta parte: assumir que atualizar significa rodar o script de instalação de novo. Tem comando próprio pra isso, e ele já sabe de onde você veio

Como desinstalar: codegraph uninstall e codegraph uninit

Essas duas coisas são diferentes e MUITA gente mistura

O que o uninstall faz:

codegraph uninstall

Ele reverte o instalador

Remove a config do servidor MCP, as instruções e as permissões de cada agente que você configurou

E remove também o próprio CLI em todas as formas que encontrar na máquina: bundle standalone, pacote npm global e link do launcher

Antes de sair apagando, ele mostra o que encontrou e pede confirmação, então dá pra ler com calma o que vai embora

Quer manter o CLI instalado e tirar só as configurações dos agentes? Tem flag pra isso, que era o comportamento padrão antigo:

codegraph uninstall --keep-cli

E os índices dos projetos?

Continuam lá

A desinstalação não apaga o que está em .codegraph/

Cada projeto sai com um comando separado, que aceita o caminho do projeto como argumento:

codegraph uninit
codegraph uninit --force

O --force pula o prompt de confirmação, então cuidado ao colar isso em script 🙂

Sobre a flag -i/–index:

Se você tem script antigo por aí usando -i ou --index, relaxa: a flag virou no-op

Ela é aceita apenas pra não quebrar o que já existia, mas não faz mais nada

Quando vale rodar o codegraph init no seu repositório

Nem todo projeto pede isso no dia um. Alguns cenários em que faz sentido:

Repositório grande onde o agente vive lendo arquivo. A v1.5.0 reconstruiu o motor de parsing como um kernel nativo em Rust, com parsing em Rust pra 20 linguagens, entre elas TypeScript, JavaScript (incluindo TSX/JSX), Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua e Luau. O release reporta sync abaixo de um segundo em um repositório de 27.000 arquivos

Mais de um agente na mesma máquina. Como a instalação é global e o instalador configura vários agentes de uma vez, você não paga o pedágio de setup por ferramenta

Ambiente sem Node ou com registry restrito. É o caso clássico do canal standalone, que não pede npm, nem Node do sistema, nem configuração de registry

Contexto que exige rastreabilidade. A partir da v1.5.0, os pacotes npm saem com npm provenance e os bundles do GitHub Release trazem build attestations assinadas, ou seja, releases verificáveis criptograficamente. Se o seu time precisa justificar de onde veio o binário, isso ajuda na conversa

E o ganho real, em número?

Aqui vale o aviso de sempre: os números abaixo são do benchmark publicado pelo próprio projeto, remedido em 2026-08-05 contra o Claude Opus 4.8, com uma correção de contaminação que bloqueia o CLI do codegraph nos dois braços do teste

São médias em sete repositórios, do fornecedor, não de terceiro independente:

Número de fornecedor a gente lê com uma sobrancelha levantada, sempre

Mas a direção é coerente com a proposta: se o grafo já está pronto, o agente pergunta em vez de vasculhar

Conclusão

O ciclo inteiro da CodeGraph CLI cabe em cinco movimentos, e é isso que fica de bagagem:

• codegraph install uma vez na máquina (ou o comando codegraph sem argumentos)
• codegraph init uma vez por projeto, que cria o .codegraph/ e já indexa
• codegraph status pra confirmar que o índice está saudável
• codegraph upgrade pra manter atualizado, com --check quando você só quer espiar
• codegraph uninstall e codegraph uninit pra sair sem sobra nenhuma

Próximo passo? Pega um repositório de teste, roda o codegraph init, olha o codegraph status e compara o comportamento do seu agente com e sem o grafo na jogada

É o tipo de coisa que só convence quando você vê rodando no SEU código

O projeto é MIT e está aberto em github.com/colbymchenry/codegraph, com cerca de 66,7 mil estrelas segundo o rastreador Star History, então dá pra abrir o código e entender o que cada comando faz por baixo

Até o próximo post! 😀