Como usar o CodeGraph em um projeto iOS com React Native e Expo?

Fala aí, beleza? Existe um tipo de referência que simplesmente evapora no meio do caminho: aquela que sai de um método Swift, passa pelo Objective-C e vai parar num arquivo TypeScript do outro lado do bridge

Você procura pelo nome do método no projeto inteiro e acha… o próprio método. Só ele. O consumidor em JS não aparece, porque textualmente não existe nada ligando as duas pontas

É exatamente esse buraco que o CodeGraph mantido por colbymchenry (distribuído no npm como @colbymchenry/codegraph) resolve com o suporte a bridging misto. Aqui a gente recorta o cenário mais chato de todos: um app iOS com React Native e Expo, onde o código nativo e o JavaScript vivem no mesmo repositório e conversam por caminhos que nenhum parser lê de forma direta

Um aviso antes de qualquer coisa: existem outros projetos chamados CodeGraph no GitHub (codegraph-ai/CodeGraph e anvanster/codegraph, por exemplo) e eles são ferramentas DIFERENTES. Confere o repo e o pacote antes de instalar, senão você vai passar a tarde debugando a coisa errada 😀

Formação Recomendada

Formação Claude Code

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

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Por que a busca por arquivo é cega no bridging entre nativo e JavaScript

A busca textual é ótima quando o problema mora dentro de um arquivo só

Se o seu drama é um erro de import do react-router-dom, o grep te entrega a resposta em dois segundos, o símbolo está ali, escrito, no arquivo

O bridging não funciona assim

A documentação oficial é bem direta sobre isso: o parsing estático QUEBRA em dynamic dispatch. Quando a chamada é resolvida em tempo de execução, não sobra rastro textual pra ferramenta seguir. E o CodeGraph usa sintetizadores pra atravessar essas fronteiras (callbacks, observers, re run do React, children de JSX), o que está descrito na página Resolution & Frameworks da doc

Que fronteiras exatamente?

Essa é a pergunta que interessa pra quem trabalha com mobile. Os boundaries cobertos por sintetizador em projetos mistos de iOS, React Native e Expo são:

• auto bridging de Swift para Objective-C
• bridge legado do React Native
• TurboModules
• canais de evento de nativo para JS
• Expo Modules
• componentes de view Fabric/Codegen

Ou seja: é justamente a lista de caminhos por onde a sua feature passa todo dia e some do resultado da busca

E não sou só eu achando que isso é dúvida de todo mundo, não. Tem uma issue pública no repositório, a issue #401, perguntando explicitamente sobre suporte a Objective-C e projetos mistos Swift/Objective-C. Stack mista é assunto recorrente na comunidade, beleza?

O que você precisa antes de indexar o projeto

Pouca coisa, sério. Nada de PC da Nasa aqui

• Node com npx disponível, porque o caminho rápido de instalação passa por ele
• O repositório do app iOS com React Native e Expo clonado na sua máquina
• Um agente compatível já instalado: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE ou Kiro

Sobre cobertura de linguagem, que é a preocupação número um de quem tem base mista: o parsing nativo em Rust cobre Swift, TypeScript e JavaScript (com TSX/JSX), além de Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Kotlin, Scala, Dart, R, Lua e Luau

E o Objective C? Está listado na página Languages da documentação oficial, junto com Metal

A versão atual publicada no npm é a 1.5.0

Ah, e um detalhe que muita gente esquece de perguntar: roda 100% local, sem embeddings, sem vector store e sem chave de API. Nada do seu código sai da máquina

Passo a passo: instalar, indexar e consultar o grafo

1. Instale o CodeGraph pelo instalador oficial

O caminho rápido é o npx, que detecta e configura os agentes automaticamente:

   npx @colbymchenry/codegraph

Se preferir ter o binário global antes de configurar o agente:

   npm i -g @colbymchenry/codegraph

O erro comum deste passo: instalar um homônimo. Tem mais de um projeto chamado CodeGraph por aí, e o pacote certo é @colbymchenry/codegraph, do repo colbymchenry/codegraph. Confere o escopo do pacote, sempre

2. Confira o que o instalador escreveu

Ele faz duas coisas: escreve a configuração do MCP server de cada agente que você escolheu, e injeta uma seção do CodeGraph delimitada por marcadores no arquivo de instruções do agente (CLAUDE.md, AGENTS.md ou GEMINI.md, conforme o caso)

Vale dar aquela olhada no diff antes de commitar, porque essa seção vive dentro do repositório. É o mesmo raciocínio de quando você para pra decidir se uma configuração vale em vários repositórios ou tem que ser refeita em cada um

O erro comum deste passo: assumir que não mexeu em nada e subir o arquivo de instruções sem revisar

3. Configure o MCP na mão, se precisar

No Claude Code, a configuração manual mora em ~/.claude.json apontando pro binário do codegraph:

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

Esse bloco é o plano B quando a detecção automática não pegou o seu setup

4. Rode a inicialização na raiz do projeto

   codegraph init

Esse comando cria a pasta .codegraph/ na raiz e constrói o grafo completo no mesmo passo, você não precisa disparar um build separado depois

O erro comum deste passo: rodar fora da raiz do repositório. Se você estiver dentro de ios/ ou de app/, o grafo nasce torto e metade do projeto fica de fora. Tome cuidado!

5. Consulte pelo agente

Rodando como MCP server, o CodeGraph expõe UMA ferramenta só ao agente: codegraph_explore

Ela devolve três coisas: o código fonte verbatim dos símbolos relevantes agrupado por arquivo, os caminhos de chamada entre eles (incluindo os saltos de dynamic dispatch, que é o pulo do gato aqui) e um resumo de blast radius do que uma mudança afetaria

Repara que você não precisa decorar dez comandos. É uma ferramenta, o agente decide quando chamar

6. Deixe o grafo vivo

Depois do init, o grafo é mantido atualizado por um file watcher nativo do sistema operacional, com debounce e sync incremental a cada save. O armazenamento é SQLite local com busca full text FTS5

Na prática: você salva o arquivo, o grafo acompanha. Sem ritual de reindexação manual toda vez que mexe no código 🙂

Onde o grafo entrega mais em um app iOS com React Native e Expo

Rastrear um método nativo até o consumo em JS. Aquele método que você mexeu no Swift, quem chama do lado JavaScript? Com os sintetizadores de TurboModules e do bridge legado, o caminho de chamada aparece inteiro, em vez de morrer na borda do arquivo nativo

Entender um canal de evento de nativo para JS. Evento emitido lá embaixo e escutado lá em cima é o caso clássico de referência invisível pro grep. Esse boundary tem sintetizador dedicado

Medir blast radius antes de tocar um Expo Module ou uma view Fabric/Codegen. Antes de mudar assinatura de um módulo, você pergunta ao agente o que quebra. O codegraph_explore já devolve esse resumo junto com os caminhos de chamada, então a decisão vem com contexto e não com fé

Sobreviver na base Objective C legada. A indexação cobre arquivos .m, .mm e .h identificados por content sniffing, com extração estrutural completa: seletores multi parte completos, properties, imports e relações de superclasse/protocolo. É isso que faz trace, callers e callees funcionarem de verdade em base iOS, em vez de retornar meia dúzia de matches soltos

Problemas comuns na primeira indexação (e como evitar)

Sintoma: o comando instalou, mas não é isso que você queria

Causa: homônimo. Você pegou um dos outros projetos chamados CodeGraph no GitHub

Solução: valide a origem. O repo é colbymchenry/codegraph e o pacote é @colbymchenry/codegraph. Se o nome do pacote está sem o escopo, é outra ferramenta

Sintoma: o agente não enxerga a ferramenta codegraph_explore

Causa: o MCP server não foi configurado pro seu agente

Solução: rode o instalador de novo (npx @colbymchenry/codegraph), que ele escreve a configuração do MCP server dos agentes detectados. No Claude Code, dá pra aplicar o bloco manual em ~/.claude.json com codegraph serve --mcp, como no passo 3

Sintoma: a seção do CodeGraph no arquivo de instruções virou uma bagunça

Causa: alguém editou o conteúdo por fora dos marcadores que o instalador escreveu, ou misturou instrução própria dentro do bloco gerado

Solução: mantenha o que é seu FORA dos marcadores. O bloco delimitado é território do instalador em CLAUDE.md, AGENTS.md ou GEMINI.md, e o resto do arquivo é seu

Como prevenir os três de uma vez? Trate o dia da instalação como um commit revisado: confere o pacote, confere o diff do arquivo de instruções, confere se o init rodou na raiz. Cinco minutos ali economizam a tarde inteira depois

Conclusão

O diferencial pra time mobile é bem específico: o grafo atravessa exatamente a fronteira que a busca textual perde, aquela entre nativo e JavaScript, e cobre os boundaries que o React Native e o Expo usam de verdade

E não é lento. A v1.5.0, lançada em 21/07/2026, reconstruiu o motor de parsing como um kernel nativo em Rust e deixou a sincronização praticamente instantânea: um save chega ao grafo em bem menos de um segundo, mesmo num repositório de 27.000 arquivos. Isso é muito massa pra quem trabalha em monorepo mobile

Próximo passo, bem objetivo: roda npx @colbymchenry/codegraph, depois codegraph init na raiz do app, e pede pro seu agente o blast radius do primeiro módulo nativo que você for tocar. Aí você vê na prática se o caminho de chamada aparece inteiro ou não

O projeto vem acumulando tração forte (66,7 mil stars) e figura entre os mais estrelados do GitHub, então é daqueles que vale manter no radar…

até o próximo post! 😀