codegraph

CodeGraph

Já instalado? Execute codegraph upgrade

Siga @getcodegraph no X para atualizações.

Potencialize Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity e Kiro com Inteligência Semântica de Código

O grafo de código completo mais rápido · contexto cirúrgico · feito para como os agentes realmente trabalham · 100% local

**Kernel desenvolvido em Rust**

Documentação e Site →

A plataforma CodeGraph está chegando — para cada PR, saiba exatamente o que testar, o que pode quebrar, quais fluxos são afetados e se a lógica de negócio está comprometida.

_{Obtenha acesso antecipado beta ao produto hospedado · getcodegraph.com}

Conteúdo

Comece Agora

1. Instale a CLI

Node.js não é necessário — um único comando baixa a versão correta para o seu sistema operacional:

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

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Já tem Node? Use npm (funciona em qualquer versão)

npm i -g @colbymchenry/codegraph

_{O CodeGraph inclui seu próprio runtime — nada para compilar, sem build nativo, funciona igual em qualquer lugar. O instalador coloca codegraph no seu PATH, mas não altera o seu shell atual — abra um novo terminal antes do próximo passo para que o comando seja reconhecido.}

_{Atualize a qualquer momento com codegraph upgrade — ele detecta como você instalou (bundle, npm ou npx) e atualiza no local. Adicione --check para ver se há uma atualização disponível, ou codegraph upgrade <versão> para fixar uma versão específica.}

2. Conecte seus agentes

Em um novo terminal, execute o instalador para conectar o CodeGraph aos agentes que você usa:

codegraph install

_{Detecta e configura automaticamente Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE e Kiro — conectando o servidor MCP do CodeGraph a cada um deles. Este é o passo que conecta o CodeGraph ao seu agente; instalar a CLI no passo 1 não faz isso sozinho. Ele apenas configura o seu agente — não indexa nenhum código; construir o grafo de cada projeto é o passo separado codegraph init do passo 3. (Atalho: npx @colbymchenry/codegraph baixa e executa tudo isso de uma vez.)}

3. Inicialize cada projeto

cd your-project
codegraph init

_{codegraph init cria o diretório local .codegraph/ e constrói o grafo completo no mesmo passo — um comando, pronto.}

4. Chega de sincronizar!

A sincronização automática está habilitada por padrão. O CodeGraph monitora o projeto e atualiza o grafo a cada alteração de arquivo — enquanto seu agente edita código, ou você adiciona, modifica ou exclui arquivos. O índice nunca fica desatualizado e não há nada para reexecutar.

Desinstalação

Mudou de ideia? Um único comando remove o CodeGraph de todos os agentes configurados e a própria CLI — todas as instalações encontradas (bundle autônomo, pacote global npm, link do launcher), exibidas antes de qualquer exclusão:

codegraph uninstall

Passe --keep-cli para remover apenas as configurações dos agentes e manter a CLI instalada.

_{Reverte o instalador — remove a configuração do servidor MCP do CodeGraph, instruções e permissões de cada agente configurado. Seus índices de projeto (.codegraph/) permanecem intactos; remova-os por projeto com codegraph uninit. Use --target para remover de agentes específicos, ou --yes para executar sem interação.}

---

Suporte a Linguagens

Cada linguagem abaixo recebe o mesmo tratamento — extração estrutural completa e resolução entre arquivos em um único grafo, sem configuração por linguagem:

_{Detalhes por linguagem — extensões, frameworks e exatamente o que é extraído — em Linguagens Suportadas.}

---

Por que CodeGraph?

Quando um agente de IA precisa entender código — para responder a uma pergunta ou fazer uma alteração — ele descobre a estrutura do jeito lento: grep, glob e Read, um arquivo por vez, reconstruindo caminhos de chamada e dependências manualmente. Isso é uma pilha de chamadas de ferramentas e idas e voltas antes mesmo de começar o trabalho real.

O CodeGraph entrega ao agente exatamente o código que ele precisa em uma única chamada. É um grafo de conhecimento pré-construído de cada símbolo, aresta de chamada e dependência no seu código — então, em vez de percorrer arquivos, o agente faz uma pergunta e recebe o código-fonte relevante, os caminhos de chamada entre esses símbolos (incluindo saltos de despacho dinâmico que o grep não consegue seguir) e o raio de impacto de uma alteração. Contexto cirúrgico, não uma busca arquivo por arquivo — o que significa menos chamadas de ferramentas e respostas mais rápidas em qualquer código, grande ou pequeno.

Uma nota sobre custo: A vantagem do CodeGraph em todo código é a precisão — o agente para de percorrer arquivos e responde a partir do grafo. Nos modelos atuais, essa precisão também é uma grande economia direta: a revalidação de 2026-07 mediu 60% menos custo e 69% menos tokens em média nos sete repositórios de referência, porque um modelo forte sem o grafo queima milhões de tokens redescobrindo a estrutura. A economia escala com o tamanho e a complexidade do repositório — dramática em árvores do tipo VS Code, modesta em um projeto de 100 arquivos — e se acumula no uso diário de agentes de uma equipe.

Resultados de Benchmark

Testado em 7 codebases open-source reais abrangendo 7 linguagens, comparando um agente (Claude Code, headless) respondendo a uma pergunta de arquitetura com e sem CodeGraph, na mediana de 4 execuções por braço. Revalidado em 2026-07-21 no Claude Opus 4.8 contra a versão atual — o kernel Rust mais a reformulação de resolução deste ciclo.

A vitória universal — todo repositório, todo tamanho: 89% menos chamadas de ferramentas · 60% mais barato · 69% menos tokens · leituras de arquivo reduzidas a zero em todos os sete repositórios.

Com o índice disponível, o agente responde a partir de algumas chamadas codegraph_explore e para. Sem ele, o agente gasta seu orçamento em descoberta — até 57 chamadas de ferramentas e 4,3M de tokens redescobrindo o que o grafo já sabia. A coluna Tempo é em média 20% mais rápida, mas é a métrica mais ruidosa: em dois repositórios pequenos, o loop de grep bruto de um modelo forte vence a corrida de tempo real, mas ainda gasta 5–10× os tokens e o dinheiro — observado por linha abaixo.

Codebase	Linguagem	Chamadas de ferramentas	Tempo	Leituras de arquivo	Tokens	Custo
VS Code	TypeScript · ~11k arquivos	2 vs 40	5× mais rápido (41s vs 3m 24s)	0 vs 17	83% menos	75% mais barato
Excalidraw	TypeScript · ~640	3 vs 55	36s vs 23s¹	0 vs 24	89% menos	78% mais barato
Django	Python · ~3k	2 vs 29	38% mais rápido	0 vs 16	78% menos	69% mais barato
Tokio	Rust · ~790	3 vs 57	65% mais rápido	0 vs 15	91% menos	86% mais barato
OkHttp	Java · ~645	1 vs 5	10% mais rápido	0 vs 1	33% menos	~equivalente²
Gin	Go · ~110	3 vs 10	57% mais rápido	0 vs 4	18% menos	41% mais barato
Alamofire	Swift · ~110	3 vs 53	49s vs 31s¹	0 vs 18	90% menos	86% mais barato

_{¹ O efeito de piso de repositórios pequenos: o Opus 4.8 faz grep em árvores pequenas rápido o suficiente para vencer no tempo real, enquanto gasta ~5–10× os tokens e ~4–7× o custo — o braço com o grafo ainda responde com zero leituras de arquivo. ² O braço sem o grafo do OkHttp teve sorte em 5 chamadas; o braço com o grafo respondeu em 1 chamada por ~$0,03 a mais. Leituras de arquivo = mediana de arquivos abertos — a vitória do contexto cirúrgico em uma coluna: o agente nunca lê um arquivo em nenhum dos sete repositórios quando o CodeGraph está presente.}

Detalhamento por repositório — COM vs SEM (mediana de 4)

Codebase	Métrica	COM cg	SEM cg
VS Code	Tempo / Ferramentas / Tokens / Custo	41s / 2 / 265k / $0,36	3m 24s / 40 / 1,5M / $1,41
Excalidraw	Tempo / Ferramentas / Tokens / Custo	36s / 3 / 324k / $0,40	23s / 55 / 2,9M / $1,81
Django	Tempo / Ferramentas / Tokens / Custo	42s / 2 / 254k / $0,35	1m 8s / 29 / 1,2M / $1,13
Tokio	Tempo / Ferramentas / Tokens / Custo	46s / 3 / 386k / $0,44	2m 11s / 57 / 4,3M / $3,04
OkHttp	Tempo / Ferramentas / Tokens / Custo	27s / 1 / 156k / $0,23	30s / 5 / 233k / $0,20
Gin	Tempo / Ferramentas / Tokens / Custo	30s / 3 / 246k / $0,27	1m 10s / 10 / 300k / $0,46
Alamofire	Tempo / Ferramentas / Tokens / Custo	49s / 3 / 316k / $0,35	31s / 53 / 3,1M / $2,51

Detalhes completos do benchmark

Metodologia. Cada braço é claude -p (Claude Opus 4.8) executado headless contra o repositório com --strict-mcp-config: COM = servidor MCP do CodeGraph habilitado, SEM = configuração MCP vazia. Read/Grep/Bash integrados permanecem disponíveis para ambos. Mesma pergunta por repositório, 4 execuções por braço, mediana reportada. Custo = total_cost_usd da execução; Tokens = total de tokens processados (entrada incl. cache + saída); Tempo = tempo real; Chamadas de ferramentas = toda invocação de ferramenta, incluindo aquelas dentro de subagentes que o modelo cria. Repositórios clonados em --depth 1 e indexados pela mesma versão do CodeGraph que os serviu. Revalidado em 2026-07-21 na versão atual (kernel Rust nativo, resolução paralela adaptativa, sincronização com escopo).

Consultas:

Codebase	Consulta
VS Code	"Como o host de extensões se comunica com o processo principal?"
Excalidraw	"Como o Excalidraw renderiza e atualiza elementos do canvas?"
Django	"Como o ORM do Django constrói e executa uma consulta a partir de um QuerySet?"
Tokio	"Como o tokio agenda e executa tarefas assíncronas em seu runtime?"
OkHttp	"Como o OkHttp processa uma requisição através de sua cadeia de interceptadores?"
Gin	"Como o gin roteia requisições através de sua cadeia de middleware?"
Alamofire	"Como o Alamofire constrói, envia e valida uma requisição?"

Por que o CodeGraph vence: com o índice disponível, o agente responde diretamente — geralmente uma única chamada codegraph_explore retorna o código-fonte relevante — e para, com zero leituras de arquivos em todos os repositórios do benchmark. Sem ele, o agente gasta a maior parte do seu orçamento em descoberta (find/ls/grep) antes de ler o código certo. O CodeGraph só ajuda quando consultado diretamente, então suas instruções orientam os agentes a responder diretamente em vez de delegar a exploração para subagentes de leitura de arquivos — caso contrário, um subagente lê arquivos independentemente e o CodeGraph se torna sobrecarga.

---

Feito para velocidade — o kernel Rust

O mecanismo de análise do CodeGraph é um kernel Rust nativo: 20 linguagens — TypeScript, JavaScript, Java, Python, Go, C, C++, Rust, C#, PHP, Ruby, Swift, Kotlin, Scala, Dart, R, Lua, Luau (Metal e CUDA seguem o caminho do C++) — são analisadas em código compilado com uma única travessia de fronteira por arquivo. Cada linguagem é lançada somente após seus grafos provarem ser byte a byte idênticos ao mecanismo de referência em repositórios reais, de pequenas bibliotecas até o kernel Linux; plataformas sem binário pré-compilado e arquivos com erros de sintaxe têm fallback automático por arquivo, com o mesmo grafo em ambos os casos.

E ele se dimensiona para a máquina em que está. Pools de workers, resolução paralela e caches de análise são dimensionados com base no que o sistema realmente tem — contagens reais de núcleos (ciente de container/cgroup, então um VPS que concede 2 núcleos é dimensionado para 2, não para os 64 do host), RAM disponível medida honestamente no macOS e Linux, e o custo medido do trabalho de resolução do seu projeto:

• Em uma workstation: o pipeline paralelo completo — workers de análise nativos, um pool de resolvedores multi-worker que entra em ação no momento em que se paga, caches de análise limitados por memória. O repositório do compilador Swift (27 mil arquivos de Swift e C++) é indexado do zero em cerca de 100 segundos; uma edição de um arquivo é ressincronizada em ~4.
• Em um VPS de 2 núcleos / 6GB: o mesmo grafo, a partir de um pipeline ajustado para terminar — o kernel Linux (70 mil arquivos, 2 milhões de símbolos, 6,4 milhões de relacionamentos) é indexado até a conclusão em menos de 12 minutos, onde designs que priorizam RAM ficam sem memória antes de atingir 1%.
• Todos os dias após o primeiro: salvar um arquivo atualiza o grafo em bem menos de um segundo — o watcher dispara 300ms após um salvamento isolado e sincroniza exatamente o que mudou (~0,3s de trabalho em um projeto de 4.400 arquivos, ~0,4s no repositório do compilador Swift com 27.000 arquivos), nunca reescaneando a árvore. Medido contra o reindexador sob mudança mais rápido concorrente: 2–7× mais rápido em repositórios médios e grandes em um benchmark de 31 repositórios e 30 linguagens — e a diferença aumenta com o tamanho do repositório, porque o custo deles cresce com o repositório e o nosso cresce com a mudança.

---

Principais Recursos

Kernel Rust Nativo	Análise e extração rodam em um mecanismo Rust compilado para 20 linguagens — com grafos verificados byte a byte idênticos ao mecanismo de referência, e fallback automático por arquivo para que nada quebre
Adapta-se à Sua Máquina	Dimensiona seus pools de workers e caches com base no que o sistema realmente tem — contagens reais de núcleos (ciente de container), RAM disponível honesta, custo medido por projeto. Uma workstation recebe o pipeline paralelo completo; um VPS de 2 núcleos recebe um ajustado para terminar de forma confiável
Contexto Cirúrgico	Uma única chamada de ferramenta retorna pontos de entrada, símbolos relacionados e trechos de código — sem exploração lenta arquivo por arquivo
Busca de Texto Completo	Encontre código por nome instantaneamente em todo o seu codebase, alimentado por FTS5
Análise de Impacto	Rastreie chamadores, chamados e o raio de impacto total de qualquer símbolo antes de fazer alterações
Sempre Atualizado	O watcher de arquivos usa eventos nativos do SO (FSEvents/inotify/ReadDirectoryChangesW) com auto-sincronização com debounce — o grafo permanece atualizado enquanto você codifica, zero configuração
20+ Linguagens	TypeScript, JavaScript, ArkTS, Python, Go, Rust, Java, C#, VB.NET, PHP, Ruby, C, C++, CUDA, Objective-C, Metal, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Nix, Erlang, CFML, COBOL, Solidity, Terraform/OpenTofu, Svelte, Vue, Astro, Liquid, Pascal/Delphi
Rotas Cientes de Frameworks	Reconhece arquivos de roteamento de frameworks web e vincula padrões de URL aos seus handlers em 17 frameworks
Integração iOS / React Native / Expo	Fecha fluxos entre linguagens que a análise estática perde: ponte Swift ↔ ObjC, ponte legada React Native + TurboModules + componentes de view Fabric, emissores de eventos nativo → JS, Expo Modules
100% Local	Nenhum dado sai da sua máquina. Sem chaves de API. Sem serviços externos. Apenas banco de dados SQLite

Como a auto-sincronização funciona — e por que você não precisa rodar codegraph sync manualmente

Quando seu agente (Claude Code, Cursor, Codex, opencode) inicia o codegraph serve --mcp, três camadas mantêm o índice em sincronia com seu código — e garantem que o agente nunca receba uma resposta errada silenciosa na breve janela entre uma edição e a próxima sincronização:

1. Watcher de arquivos com auto-sincronização com debounce. Um watcher nativo FSEvents / inotify / ReadDirectoryChangesW captura cada criação / modificação / exclusão de arquivo-fonte e dispara uma reindexação após uma janela de debounce (padrão 2000ms, ajustável via CODEGRAPH_WATCH_DEBOUNCE_MS, limitado a [100ms, 60s]). Rajadas de edições se colapsam em uma única sincronização.
2. Banner de desatualização por arquivo. Durante a breve janela de debounce, respostas de ferramentas MCP que referenciariam um arquivo ainda pendente prefixam um banner ⚠️ nomeando-o e dizendo ao agente para Read diretamente. Arquivos pendentes NÃO referenciados pela resposta aparecem como um pequeno rodapé. De qualquer forma, o agente recebe um sinal explícito — validado com Claude Code, onde o agente literalmente diz "Lendo o arquivo diretamente para o conteúdo ao vivo" antes de abri-lo.
3. Atualização na conexão. Quando o servidor MCP (re)conecta, o codegraph executa uma reconciliação rápida de (size, mtime) + hash de conteúdo contra a árvore de trabalho antes de responder à primeira consulta — então edições feitas enquanto nenhum servidor MCP estava rodando (um git pull do terminal, edições de outro editor, uma sessão de agente anterior que saiu) são absorvidas na primeira chamada de ferramenta da próxima sessão.

agent writes src/Widget.ts
  → watcher fires (<100ms)
  → debounce (default 2s)
  → sync; Widget.ts is in the index
  → next agent query sees it

Verifique a qualquer momento com codegraph status (CLI). Se houver algo pendente, você verá uma seção ### Pending sync: nomeando os arquivos e sua idade de edição.

Os poucos casos em que o codegraph sync manual faz sentido: o watcher está desabilitado (ambientes sandbox, ou CODEGRAPH_NO_DAEMON=1), ou você está fazendo script contra o índice fora de uma sessão de agente e quer uma sincronização pré-voo no início do seu script.

→ Mergulho profundo completo em Guias → Indexando um Projeto.

---

Rotas Cientes de Frameworks

O CodeGraph detecta arquivos de roteamento de frameworks web e emite nós route vinculados por arestas references às suas classes ou funções handler. Consultar chamadores de uma view/controller agora revela o padrão de URL que a vincula.

Framework	Formas reconhecidas
Django	path(), re_path(), url(), include() em urls.py (CBV .as_view(), caminhos pontilhados)
Flask	@app.route('/path', methods=[...]), rotas de blueprint
FastAPI	@app.get(...), @router.post(...), todos os métodos padrão
Express	app.get(...), router.post(...) com cadeias de middleware
NestJS	@Controller + @Get/@Post/..., GraphQL @Resolver + @Query/@Mutation, @MessagePattern / @EventPattern, @SubscribeMessage
Laravel	Route::get(), Route::resource(), Controller@action, sintaxe de tupla
Drupal	Rotas *.routing.yml (_controller, _form, handlers de entidade); implementações hook_* em .module /.theme /.install /.inc
Rails	get '/x', to: 'users#index', sintaxe hash-rocket =>
Spring	@GetMapping, @PostMapping, @RequestMapping em métodos
Play	Rotas de verbo GET / POST /… em conf/routes → ações Controller.method (Scala + Java)
Gin / chi / gorilla / mux	r.GET(...), router.HandleFunc(...)
Axum / actix / Rocket	.route("/x", get(handler))
ASP.NET	Atributos [HttpGet("/x")] em métodos de ação
Vapor	app.get("x", use: handler)
React Router / SvelteKit	Nós de componentes de rota
Vue Router / Nuxt	Rotas baseadas em arquivo pages/, endpoints server/api/, middleware de rota
Astro	Rotas baseadas em arquivo src/pages/ (páginas .astro + endpoints .ts, sintaxe [param] / [...rest])

---

Integração iOS / React Native / Expo

Codebases reais de iOS e React Native vivem em múltiplas linguagens — um chamador Swift invoca um seletor Objective-C que foi auto-bridged, um arquivo JS chama um módulo nativo via ponte React Native, um componente JSX delega a um gerenciador de view nativo. A extração estática tree-sitter para em cada fronteira de linguagem. O CodeGraph as une para que codegraph_explore conecte o fluxo de ponta a ponta através da lacuna — caminhos de chamada e raio de explosão cruzam a fronteira em vez de parar nela.

Fronteira	Lado JS / Swift	Lado nativo	Como
Swift → ObjC	Swift obj.foo(bar:)	Seletor ObjC -fooWithBar:	Regras de auto-bridging @objc (incluindo formas init/property/protocol) + prefixos de preposição Cocoa (With / For / By / In / On / At /…)
ObjC → Swift	ObjC [obj fooWithBar:]	Swift @objc func foo(bar:)	Candidatos a nomes de ponte reversa; verifica exposição @objc a partir do código-fonte
Ponte legada React Native	JS NativeModules.X.fn(...)	ObjC RCT_EXPORT_METHOD / RCT_REMAP_METHOD · Java/Kotlin @ReactMethod	Analisa declarações de macro/annotation para construir um mapa nome-JS → método-nativo
React Native TurboModules	JS import M from './NativeM'; M.fn(...)	Implementação nativa correspondente à spec Codegen	Trata a interface da spec Native<X>.ts como fonte da verdade
Eventos RN nativo → JS	JS new NativeEventEmitter(...).addListener('e', cb)	ObjC [self sendEventWithName:@"e" body:...] · Swift sendEvent(withName: "e", ...) · Java/Kotlin .emit("e", ...)	Canal de eventos entre linguagens sintetizado, chaveado por nome literal do evento
Expo Modules	JS requireNativeModule('X').fn(...)	Swift / Kotlin Module { Name("X"); AsyncFunction("fn") { ... } }	Analisa literais do DSL Expo; nós de método sintéticos resolvem via correspondência de nome existente
Componentes de view Fabric	JSX <MyView prop={v}/>	Spec Codegen TS + classe de implementação nativa	Spec → nó component; busca por convenção de nome + sufixo (View / ComponentView / Manager / ViewManager) faz a ponte para o nativo
Gerenciadores de view legados Paper	JSX <MyView prop={v}/>	ObjC RCT_EXPORT_VIEW_PROPERTY · Java/Kotlin @ReactProp	Igual ao Fabric — declarações da era Paper também produzem nós component + property

Validado em codebases reais (pequeno + médio + grande para cada ponte):

Bridge	Pequeno	Médio	Grande
Swift ↔ ObjC	Charts	realm-swift	Wikipedia-iOS
Bridge legado do RN	AsyncStorage	react-native-svg	react-native-firebase
Eventos nativos → JS do RN	RNGeolocation	—	react-native-firebase
Módulos do Expo	expo-haptics	expo-camera	varredura do SDK do Expo (7 pacotes)
Views Fabric / Paper	react-native-segmented-control	react-native-screens	react-native-skia

Cada bridge emite arestas marcadas com provenance:'heuristic' com metadata.synthesizedBy: definido como um nome de canal estável (ex.: swift-objc-bridge, rn-event-channel, fabric-native-impl, expo-module-extract), para que o agente possa identificar rapidamente como um salto entrou no grafo.

---

Início Rápido

1. Execute o Instalador

npx @colbymchenry/codegraph

O instalador irá:

• Perguntar quais agente(s) configurar — detecta automaticamente os instalados entre: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro
• Solicitar a instalação do codegraph no seu PATH (para que os agentes possam iniciar o servidor MCP)
• Perguntar se as configurações se aplicam a todos os seus projetos ou apenas a este
• Gravar a configuração do servidor MCP de cada agente escolhido, além de uma pequena seção do CodeGraph delimitada por marcadores no arquivo de instruções do agente (CLAUDE.md / AGENTS.md / GEMINI.md) — é assim que subagentes e agentes não-MCP aprendem o comando codegraph explore, já que a orientação do próprio servidor MCP só alcança o agente principal. Removido de forma limpa pelo codegraph uninstall.
• Configurar permissões de aprovação automática quando o Claude Code for um dos alvos

O instalador apenas conecta seus agentes — ele não indexa seu código. Após terminar, construa o grafo de cada projeto você mesmo com codegraph init (passo 3). Um único codegraph install global cobre todos os projetos; você executa codegraph init uma vez por projeto.

Não interativo (scripting / CI):

codegraph install --yes                              # auto-detect agents, install global
codegraph install --target=cursor,claude --yes       # explicit target list
codegraph install --target=auto --location=local     # detected agents, project-local
codegraph install --print-config codex               # print snippet, no file writes

Flag	Valores	Padrão
--target	auto, all, none, ou csv (claude,cursor,...)	prompt
--location	global, local	prompt
--yes	(booleano)	prompt em cada etapa
--no-permissions	(booleano) pular lista de aprovação automática do Claude	permissões ativadas
--print-config <id>	despejar trecho para um agente e sair	—

2. Reinicie Seu Agente

Reinicie seu agente (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) para que o servidor MCP seja carregado.

3. Inicialize os Projetos

cd your-project
codegraph init

Constrói o índice do grafo de conhecimento por projeto, que então sincroniza automaticamente a cada alteração de arquivo. Um único codegraph install global funciona em todos os projetos que você abrir — sem necessidade de executar o instalador novamente por projeto.

É isso — seu agente usará as ferramentas do CodeGraph automaticamente quando existir um diretório .codegraph/.

Configuração Manual (Alternativa)

Instale globalmente:

npm install -g @colbymchenry/codegraph

Adicione ao ~/.claude.json:

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

Adicione ao ~/.claude/settings.json (opcional, para aprovação automática):

{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}

_{Um curinga aprova automaticamente todas as ferramentas do CodeGraph — codegraph_explore é a única listada por padrão, mas se você reativar outras via CODEGRAPH_MCP_TOOLS, elas já estarão permitidas, sem prompt.}

Orientação de Ferramentas para o Agente

O servidor MCP do CodeGraph entrega suas orientações de uso ao seu agente automaticamente, na resposta do MCP initialize. Em resumo, ele instrui o agente a:

• Responder perguntas estruturais diretamente com o CodeGraph — ele é o índice pré-construído, então um loop de grep/leitura apenas repete o trabalho que ele já fez. Trate o código-fonte retornado como já lido.
• Recorrer ao codegraph_explore para quase tudo — "como X funciona", um fluxo/"como X alcança Y", ou mapear uma área. Uma única chamada retorna o código-fonte verbatim dos símbolos relevantes agrupado por arquivo, os caminhos de chamada entre eles (incluindo saltos de despacho dinâmico) e um resumo do raio de impacto. Nomeie um arquivo ou símbolo na consulta para ler seu código-fonte atual numerado por linha.
• Confiar nos resultados — não reverificar com grep, e verificar o banner de desatualização após edições.
• Funciona por projeto: consulte qualquer projeto que tenha um índice .codegraph/ passando projectPath — assim, um monorepo onde apenas alguns serviços são indexados, ou um segundo repositório, funciona em uma única sessão. Um caminho sem índice retorna orientação limpa para usar ferramentas integradas; a indexação continua sendo sua decisão.

O texto exato é src/mcp/server-instructions.ts — a fonte única de verdade para o agente principal. Como subagentes e harnesses não-MCP nunca veem a orientação do MCP, o instalador também grava uma pequena seção delimitada por marcadores no arquivo de instruções do agente apontando para o equivalente da CLI codegraph explore.

---

Como Funciona

┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "How does a request reach the database?"                        │
│       calls CodeGraph tools directly — no Explore sub-agent       │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                       │
│                                                                   │
│ explore  ·  one call → verbatim source + call flow + blast radius │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite knowledge graph                      │
│          symbols · edges · files · FTS5 full-text search          │
└───────────────────────────────────────────────────────────────────┘

1. Extração — um kernel nativo em Rust analisa o código-fonte com gramáticas tree-sitter compiladas nele, extraindo nós (funções, classes, métodos) e arestas (chamadas, imports, extends, implements) para 20 linguagens; as linguagens restantes e fallbacks por arquivo usam a mesma lógica de extração no motor portátil, produzindo grafos idênticos.
2. Armazenamento — Tudo vai para um banco de dados SQLite local (.codegraph/codegraph.db) com busca em texto completo FTS5.
3. Resolução — Após a extração, as referências são resolvidas: chamadas de função → definições, imports → arquivos-fonte, herança de classes e padrões específicos de frameworks.
4. Sincronização Automática — O servidor MCP monitora seu projeto usando eventos de arquivo nativos do SO. As alterações são agrupadas (janela silenciosa de 2 segundos), filtradas apenas para arquivos-fonte e sincronizadas incrementalmente. O grafo permanece atualizado enquanto você codifica — sem necessidade de configuração.

---

Referência da CLI

codegraph                         # Run interactive installer
codegraph install                 # Run installer (explicit)
codegraph uninstall               # Remove CodeGraph from your agents AND the CLI (--keep-cli for configs only)
codegraph init [path]             # Initialize a project + build its graph (one step)
codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
codegraph sync [path]             # Incremental update
codegraph status [path]           # Show statistics
codegraph unlock [path]           # Remove a stale lock file that's blocking indexing
codegraph query <search>          # Search symbols (--kind, --limit, --json)
codegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
codegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
codegraph affected [files...]     # Find test files affected by changes (see below)
codegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)
codegraph telemetry [on|off]      # Show or change anonymous usage telemetry
codegraph upgrade [version]       # Update to the latest release (--check, --force)
codegraph version                 # Print the installed version (also -v, --version)
codegraph help [command]          # Show help, optionally for one command

codegraph affected

Rastreia dependências de import transitivamente para encontrar quais arquivos de teste são afetados por alterações em arquivos-fonte.

codegraph affected src/utils.ts src/api.ts         # Pass files as arguments
git diff --name-only | codegraph affected --stdin   # Pipe from git diff
codegraph affected src/auth.ts --filter "e2e/*"     # Custom test file pattern

Opção	Descrição	Padrão
--stdin	Ler lista de arquivos da entrada padrão	false
-d, --depth <n>	Profundidade máxima de travessia de dependências	5
-f, --filter <glob>	Glob personalizado para identificar arquivos de teste	detecção automática
-j, --json	Saída como JSON	false
-q, --quiet	Saída apenas com caminhos de arquivo	false

Exemplo de CI/hook:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

---

Ferramentas MCP

Ao executar como servidor MCP, o CodeGraph expõe uma única ferramenta — codegraph_explore. O comportamento medido dos agentes mostrou que uma ferramenta forte orienta melhor os agentes do que um menu de várias mais específicas — menos escolhas erradas e economia de contexto a cada sessão:

Ferramenta

Propósito

codegraph_explore

Responder quase qualquer pergunta em uma única chamada — "como X funciona", um fluxo ("como X alcança Y") ou mapear uma área — retornando o código-fonte verbatim dos símbolos relevantes agrupado por arquivo, além dos caminhos de chamada entre eles e um resumo do raio de impacto. Revela saltos de despacho dinâmico (callbacks, re-render do React, interface→impl) que o grep não consegue seguir. Nomeie um arquivo ou símbolo na consulta para ler seu código-fonte atual numerado por linha, no mesmo formato que a ferramenta Read fornece.

As outras ferramentas (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) permanecem totalmente funcionais, mas não listadas por padrão — tudo o que retornam já chega inline no codegraph_explore (sua seção de raio de impacto, o mapa de relacionamentos, o corpo de um símbolo como sua lista de chamadas). Reative qualquer uma delas para a superfície MCP com a variável de ambiente CODEGRAPH_MCP_TOOLS (ex.: CODEGRAPH_MCP_TOOLS=explore,node,search,callers), ou use seus equivalentes da CLI (codegraph node / query / callers / callees / impact / files / status).

Mesmo quando a raiz do próprio servidor não tem índice .codegraph/, as ferramentas permanecem disponíveis: passe projectPath para consultar qualquer projeto indexado — um sub-serviço em um monorepo, ou um segundo repositório — na mesma sessão. Um caminho sem índice retorna orientação limpa para usar ferramentas integradas, então nada falha de forma ruidosa, e a indexação continua sendo sua decisão.

---

Uso como Biblioteca

O CodeGraph pode ser embutido diretamente. O pacote npm reexporta sua API programática, então tanto import quanto require resolvem a classe CodeGraph no seu próprio processo — útil para embuti-lo em um aplicativo (ex.: um processo principal do Electron).

import CodeGraph from '@colbymchenry/codegraph';
// CommonJS works too:
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// Or: const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(\`${p.phase}: ${p.current}/${p.total}\`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

Blocos de construção de nível mais baixo são exportados do mesmo ponto de entrada para chamadores que dirigem o grafo diretamente: DatabaseConnection, QueryBuilder, getDatabasePath, initGrammars / loadGrammarsForLanguages e FileLock.

Requisitos de embutimento

• Instale a partir do npm (npm i @colbymchenry/codegraph) para que o pacote correspondente por plataforma — que carrega a biblioteca compilada e suas dependências — seja buscado junto com o shim.
• A API roda no seu runtime, então precisa de Node 22.5+ para o node:sqlite integrado (Electron se qualifica quando seu Node embutido é 22.5+). A CLI e o servidor MCP não são afetados — eles rodam no runtime empacotado autocontido.
• Tipos TypeScript acompanham o pacote. Como em qualquer biblioteca voltada para Node, mantenha @types/node disponível e skipLibCheck: true (o padrão comum).

---

Configuração

Quase nenhuma — o CodeGraph é zero-configuração por padrão, sem nada para escrever ou manter em sincronia para começar. O suporte a linguagens é automático a partir da extensão do arquivo; não há nada para conectar por linguagem. O único arquivo opcional é para mapear extensões de arquivo personalizadas.

O que ele ignora por padrão:

• Diretórios de dependências, build e cache — node_modules, vendor, dist, build, target, .venv, Pods, .next e similares em cada stack suportada — para que o grafo seja seu código, não ruído de terceiros. Isso vale mesmo sem .gitignore.
• Qualquer coisa no seu .gitignore — respeitado em repositórios git via git, e em projetos não-git lendo .gitignore diretamente (raiz e aninhados).
• Arquivos maiores que 1 MB — bundles gerados, JS minificado, blobs de fornecedores.

Para manter algo mais fora, adicione-o ao .gitignore. Para trazer um diretório excluído por padrão de volta para dentro (digamos que você realmente queira uma dependência de fornecedor indexada), adicione uma negação — !vendor/. Os padrões se aplicam uniformemente, então commitar um diretório de dependência ou build não o força para dentro do grafo; a negação .gitignore é a adesão explícita.

.gitignore não pode remover um diretório que você commitou, no entanto. Para um tema ou SDK de fornecedor verificado no repositório (ex.: um tema Metronic sob static/), liste-o sob exclude em codegraph.json — padrões estilo gitignore, correspondidos contra caminhos relativos à raiz do repositório, respeitados na indexação, sincronização e monitoramento:

{
  "exclude": ["static/", "**/vendor/**"]
}

Por outro lado, quando código-fonte real é ignorado pelo git de propósito — um projeto sob um segundo VCS (SVN, Perforce) que .gitignore seu próprio código-fonte para mantê-lo fora do Git — force-o de volta com include (o oposto de exclude; includeIgnored apenas revive repositórios git embutidos, não código-fonte comum):

{
  "include": ["Tools/", "Local/typescript/"]
}

O CodeGraph descobre esses arquivos no disco, sobrescrevendo .gitignore, na indexação, sincronização e monitoramento. Um exclude explícito ainda vence, e pulos integrados (node_modules, dist, .git) nunca são reincluídos.

Extensões de arquivo personalizadas

Se seu projeto usa uma extensão não padrão para uma linguagem suportada — digamos .dota_lua para Lua, ou .tpl para PHP — esses arquivos são ignorados por padrão, porque a extensão não é uma que o CodeGraph reconhece. Mapeie-os com um codegraph.json opcional na raiz do seu projeto:

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

Cada valor é um ID de idioma suportado. Os mapeamentos são mesclados sobre os padrões integrados e vencem em caso de conflito, então você também pode redirecionar um padrão integrado (ex.: ".h": "cpp"). Faça commit do arquivo para compartilhar o mapeamento com sua equipe. Um idioma com erro de digitação ou um arquivo malformado gera um aviso e é ignorado — isso nunca quebra a indexação — e um projeto sem codegraph.json se comporta exatamente como antes. Reindexe (codegraph index) após adicionar ou alterar mapeamentos.

Telemetria

O CodeGraph coleta estatísticas de uso anônimas — quais ferramentas e comandos são usados, quais idiomas são indexados — para orientar onde o suporte a idiomas e agentes é desenvolvido. Nunca envia código, caminhos, nomes de arquivos ou símbolos, consultas ou endereços IP; o uso é agregado localmente em totais diários antes de qualquer envio, e o endpoint de ingestão é código público neste repositório que impõe a lista de campos documentada. O instalador pergunta antecipadamente; desative a qualquer momento:

codegraph telemetry off    # or: CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1

TELEMETRY.md lista todos os campos, com os interruptores de desativação e a história completa do tratamento de dados.

Versões verificadas

Cada artefato é construído e publicado pelo workflow de Release público — nunca de um laptop — e carrega prova criptográfica disso:

• Pacotes npm são publicados via publicação confiável (OIDC — não existem tokens npm de longa duração que possam ser roubados) com atestados de proveniência vinculando cada versão ao commit exato e à execução do workflow que a construiu. Verifique o que está instalado:

  npm audit signatures
  

• Pacotes de Release do GitHub (e SHA256SUMS) carregam atestados de build assinados (SLSA v1.0 Build Level 2). Verifique qualquer pacote baixado:

  gh attestation verify codegraph-darwin-arm64.tar.gz -R colbymchenry/codegraph
  

Releases publicados antes de julho de 2026 são anteriores a este pipeline e não carregam atestados.

Plataformas suportadas

Cada release inclui um build autossuficiente (runtime Node embutido — nada para compilar) para todos os três sistemas operacionais desktop, tanto em Intel/AMD (x64) quanto em ARM (arm64):

Plataforma	Arquiteturas	Instalação
Windows	x64, arm64	Instalador PowerShell ou npm
macOS	x64, arm64	Instalador shell ou npm
Linux	x64, arm64	Instalador shell ou npm

Consulte Começar para os comandos de instalação em uma linha.

Agentes suportados

O instalador interativo detecta e configura automaticamente cada um destes — conectando o servidor MCP (que fornece sua própria orientação de uso, então nenhum arquivo de instruções é gravado):

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro

Idiomas suportados

Idioma	Extensão	Status
TypeScript	.ts, .tsx	Suporte completo
JavaScript	.js, .jsx, .mjs	Suporte completo
ArkTS (HarmonyOS)	.ets	Suporte completo (tudo o que TypeScript tem, mais structs @Component / @ComponentV2 com seus decoradores ArkUI (@State / @Prop / @Link / @Local / @Builder /…), árvores de visualização build() — arestas de componente pai→filho, links de atributos encadeados para funções @Extend / @Styles, ligações de eventos .onClick(this.handler) — pontes de despacho dinâmico para re-renderizações de estado→ build(), pares emit→assinante @ohos.events.emitter (somente chaves de evento estáticas) e URLs literais router.pushUrl → a struct da página de destino; módulos do workspace ohpm resolvem import { X } from "data" puros através de dependências oh-package.json5 file:, respeitando a entrada main de cada módulo)
Python	.py	Suporte completo
Go	.go	Suporte completo
Rust	.rs	Suporte completo
Java	.java	Suporte completo
C#	.cs	Suporte completo
PHP	.php	Suporte completo
Ruby	.rb	Suporte completo
C	.c, .h	Suporte completo
C++	.cpp, .hpp, .cc	Suporte completo
Objective-C	.m, .mm, .h	Suporte parcial (classes, protocolos, métodos, @property, #import, envios de mensagens; .mm ObjC++ pode analisar de forma incompleta)
Metal	.metal	Suporte completo (funções vertex/fragment/kernel, structs, aliases de tipo, arestas de chamada — MSL analisa como C++, com anotações [[attribute]] tratadas)
CUDA	.cu, .cuh	Suporte completo (kernels e funções device/host, structs, classes, arestas de chamada host→kernel através da sintaxe de lançamento <<<grid, block>>> — lançamentos com modelos, lançamentos com ponteiro de função (auto kernel = &fn<...>), configurações dim3{...} e kernels definidos por macro incluídos; especificadores __global__ / __device__ / __launch_bounds__ tratados; CUDA em cabeçalhos .h /.hpp simples reconhecidos por conteúdo)
Swift	.swift	Suporte completo
Kotlin	.kt, .kts	Suporte completo
Scala	.scala, .sc	Suporte completo (classes, traits, métodos, aliases de tipo, enums Scala 3)
Dart	.dart	Suporte completo
Svelte	.svelte	Suporte completo (extração de script, runes Svelte 5, rotas SvelteKit)
Vue	.vue	Suporte completo (extração de script + script-setup, rotas de página/API/middleware Nuxt)
Astro	.astro	Suporte completo (extração de frontmatter + script, referências de componentes/chamadas de template, rotas src/pages/)
Liquid	.liquid	Suporte completo
Pascal / Delphi	.pas, .dpr, .dpk, .lpr	Suporte completo (classes, records, interfaces, enums, arquivos de formulário DFM/FMX)
Lua	.lua	Suporte completo (funções, métodos com receptores, variáveis locais, imports require, arestas de chamada)
R	.R .r	Suporte completo (funções em todas as formas de atribuição, classes S4/R5/R6 com métodos, imports library / require, referências de arquivo source(), arestas de chamada)
Luau	.luau	Suporte completo (tudo em Lua, mais aliases type / export type, assinaturas tipadas e caminhos de instância Roblox require)
CFML	.cfc, .cfm, .cfs	Suporte completo (estilos baseados em tags <cfcomponent> / <cffunction> e script puro component { ... }, extends / implements, delegação embutida <cfscript>, arestas de chamada)
COBOL	.cbl, .cob, .cpy	Suporte completo (programas, seções/parágrafos com arestas de chamada PERFORM/GO TO, chamadas entre programas CALL 'literal', imports COPY copybook — incluindo arquivos .cpy independentes — registros/campos/níveis 88 de DATA DIVISION, alvos EXEC CICS LINK/XCTL e EXEC SQL INCLUDE; formato fixo e livre)
Visual Basic.NET	.vb	Suporte completo (classes, Modules, interfaces, estruturas, enums, propriedades, eventos, P/Invoke Declare, Handles / WithEvents, arestas Inherits / Implements, arestas de chamada através da ambiguidade de parênteses de chamada/índice do VB, instanciação As New, strings interpoladas, LINQ, identificadores Unicode)
Erlang	.erl, .hrl, .escript, .app.src, .app	Suporte completo (funções com agrupamento multi-cláusula/multi-aridade, assinaturas -spec, records com campos, aliases -type / -opaque, macros -define, arestas -include / -include_lib / -import, arestas de chamada locais e remotas mod:fn, referências fun name/arity, arestas de chamada com argumento MFA spawn / apply / proc_lib / timer / rpc, links gen_server:call/cast(?MODULE) → próprios handle_call / handle_cast, links -behaviour, visibilidade baseada em -export)
Solidity	.sol	Suporte completo (contracts, libraries, interfaces, structs, enums, modifiers, events, errors, variáveis de estado, diretivas import / using, chamadas emit / revert)
Terraform / OpenTofu	.tf, .tfvars, .tofu	Suporte completo (resources, data sources, modules, variables, outputs, providers incl. aliases, locals; referências var./ local./ module./resource com o escopo por diretório do Terraform aplicado; chamadas de módulo conectadas através da fronteira — entradas para as variáveis do módulo filho, module.M.out para a saída do filho, source para os arquivos do módulo; conexão entre componentes remote-state cloudposse/atmos quando o componente é nomeado estaticamente; seleções provider = aws.east resolvidas subindo a árvore de módulos; referências de bloco moved / import / removed / check; atribuições .tfvars vinculadas às variáveis que definem)
Nix	.nix	Suporte completo (funções com parâmetros simples/desestruturados/curried, ligações let /attrset, inherit, arestas de arquivo import ./path — ./dir resolvendo através de default.nix — além de listas imports = [ ./x.nix ] de módulos NixOS e arestas de arquivo callPackage ./pkg.nix; arestas de chamada; conexão de opções do sistema de módulos — uma escrita de config como launchd.user.agents.x = { ... } vincula ao módulo que declara options.launchd.user.agents, então os fluxos de opções são rastreados entre módulos)

Cobertura entre arquivos medida

Consultas de impacto e raio de explosão são tão boas quanto o grafo de dependências por trás delas, então a cobertura é medida, não presumida. Cobertura justa = a parcela de arquivos-fonte com símbolos que têm pelo menos um dependente entre arquivos resolvido — algo que os importa, chama, referencia ou (através de uma convenção de framework) roteia para eles — em um repositório de benchmark do mundo real por idioma. O residual é sempre uma fronteira genuína de análise estática (despacho dinâmico em tempo de execução, reflexão / contêineres DI, pontos de entrada por convenção de framework, código de terceiros vendido), nunca escondido manipulando o denominador.

Idioma	Repositório de benchmark	Cobertura
TypeScript / JavaScript	este repositório	95,8%
Python	psf/requests	100%
Go	gin-gonic/gin	96,6%
Rust	BurntSushi/ripgrep	86,7%
Java	google/gson	93,3%
C#	jbogard/MediatR	85,2%
PHP	guzzle/guzzle	100%
Ruby	sidekiq/sidekiq	100%
C	redis/redis	92,2%
C++	google/leveldb	94,8%
Objective-C	SDWebImage	91,6%
Swift	Alamofire	95,3%
Kotlin	square/okhttp	96,2%
Scala	gatling/gatling	91,2%
Dart	flutter/packages	92,4%
Svelte / SvelteKit	sveltejs/realworld	100%
Vue / Nuxt	nuxt/movies	93,5%
Astro	xingwangzhe/stalux	93,0%
Lua	nvim-telescope/telescope.nvim	84,2%
Luau	dphfox/Fusion	92,2%
Liquid	Shopify/dawn	73,8%
Pascal / Delphi	PascalCoin	77,4%

O roteamento de frameworks é validado da mesma forma, em um aplicativo canônico por framework: Express 100%, FastAPI 98%, Flask 100%, NestJS 96,8%, Gin 96,5%, Axum 100%, Rocket 93,8%, Vapor 100%, Laravel 92%, Rails 89,6%, React Router 100% — e os pesados em convenção/reflexão no seu teto honesto de análise estática: ASP.NET 83,9%, Spring 83,3%, Drupal 78,9%, Play 76,3%, Django 74,1%. SvelteKit, Vue/Nuxt e Astro usam roteamento baseado em arquivos, então sua cobertura de páginas/endpoints são as figuras de Svelte/SvelteKit (100%), Vue/Nuxt (93,5%) e Astro (93,0% — cada arquivo src/pages/ mapeia para um nó de rota nos dois repositórios de validação) na tabela acima.

Solução de problemas

"CodeGraph not initialized" — Execute codegraph init no diretório do seu projeto primeiro.

Indexação lenta — Verifique se node_modules e outros diretórios grandes estão excluídos. Use --quiet para reduzir a sobrecarga de saída. MCP hits database is locked — builds atuais não deveriam: o CodeGraph inclui seu próprio runtime Node e usa o node:sqlite nativo do Node no modo WAL, onde leituras concorrentes nunca bloqueiam um escritor. Se você ainda vir isso:

• Você está em uma instalação antiga (pré-0.9). Reinstale para obter o runtime incluído — curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh (macOS/Linux), irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex (Windows) ou npm i -g @colbymchenry/codegraph@latest.
• codegraph status mostra Journal: diferente de wal — o WAL não pôde ser ativado neste sistema de arquivos (comum em compartilhamentos de rede e /mnt do WSL2), então leituras podem bloquear escritas. Mova o projeto (com sua pasta .codegraph/) para um disco local.

Servidor MCP não conectando — Seu agente inicia o servidor por conta própria, então você não o executa manualmente. Certifique-se de que o projeto está inicializado e indexado (codegraph status) e que o caminho na sua configuração MCP está correto. Se ainda assim não conectar, execute novamente codegraph install para reescrever a configuração.

Chamadas de ferramentas MCP falham com Transport closed enquanto codegraph status / sync estão saudáveis — quase sempre WSL2 com o projeto em uma unidade Windows (um caminho /mnt/c ou /mnt/d), onde o socket local que o CodeGraph usa para compartilhar um servidor em segundo plano entre sessões é instável. O CodeGraph agora recorre a servir a sessão no processo em vez de derrubar a conexão, mas se você ainda encontrar isso, defina CODEGRAPH_NO_DAEMON=1 no ambiente do seu servidor MCP para pular o servidor compartilhado completamente (cada sessão roda em seu próprio processo). Mover o projeto para o sistema de arquivos nativo do Linux (por exemplo, sob ~/ em vez de /mnt/) restaura o servidor compartilhado.

Símbolos ausentes — O servidor MCP sincroniza automaticamente ao salvar (aguarde alguns segundos). Execute codegraph sync manualmente se necessário. Verifique se o idioma do arquivo é suportado e se não está dentro de um diretório .gitignore d ou excluído por padrão (por exemplo, node_modules, dist).

Compartilhando um checkout entre Windows e WSL — Não aponte ambos para o mesmo .codegraph/: o bloqueio do servidor em segundo plano e o índice SQLite estão vinculados ao sistema operacional que os escreveu, e o bloqueio SQLite através da fronteira do sistema de arquivos WSL2/Windows é instável. Dê a cada lado seu próprio índice na mesma árvore definindo CODEGRAPH_DIR para um nome distinto em um deles — por exemplo, CODEGRAPH_DIR=.codegraph-win no Windows, deixando o WSL no padrão .codegraph. O CodeGraph ignora qualquer diretório irmão .codegraph-* ao indexar e observar, então os dois nunca se atrapalham.

Licença

MIT

---

Feito para agentes de codificação com IA — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE e Kiro

Reportar Bug · Solicitar Recurso