codegraph-rust

CodeGraph

Seu código-fonte, compreendido.

O CodeGraph transforma todo o seu código-fonte em um grafo de conhecimento semanticamente pesquisável sobre o qual agentes de IA podem realmente raciocinar—não apenas fazer buscas com grep.

Pronto para começar? Vá para o Guia de Instalação para instruções de configuração passo a passo.

Já configurou? Veja o Guia de Uso para dicas de como aproveitar ao máximo o CodeGraph com seu assistente de IA.

---

O Problema

Assistentes de codificação com IA são poderosos, mas estão voando às cegas. Eles veem arquivos um de cada vez, fazem grep por padrões e gastam tokens tentando entender sua arquitetura. Toda conversa começa do zero.

E se o seu assistente de IA já conhecesse seu código-fonte?

---

O Que o CodeGraph Faz de Diferente

1. Grafo + Embeddings = Compreensão Real

A maioria das ferramentas de busca semântica cria embeddings e pronto. O CodeGraph constrói um grafo de conhecimento real:

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
              ↓               ↓              ↓              ↓              ↓         ↓
          Packages        Nodes/edges    Type-aware     API surface      Graph    Semantic
          Features        Fast patterns  linking        Module graph   traversal   search
          Targets         Spans          Definitions    Dataflow/Docs             (hybrid)

Quando você pesquisa, não obtém apenas "código semelhante"—você obtém código com suas relações intactas. A função que corresponde à sua consulta, além do que a chama, do que ela depende e de onde ela se encaixa na arquitetura.

O enriquecimento da indexação adiciona:

• Nós de módulos e arestas de importação/contêiner em nível de módulo para navegação entre arquivos
• Arestas de fluxo de dados específicas do Rust (defines, uses, flows_to, returns, mutates) para análise de impacto
• Nós de documentos/especificações vinculados a símbolos entre crases em README.md, docs/**/*.md e schema/**/*.surql
• Sinais de arquitetura (ciclos de pacotes + violações opcionais de limites)

Níveis de indexação (velocidade vs riqueza)

A indexação é dividida em níveis para que você possa escolher entre velocidade/armazenamento e riqueza do grafo. O padrão é rápido.

Nível	O que ele habilita	Uso típico
fast	Apenas nós AST + arestas principais (sem LSP ou enriquecimento)	Indexação rápida, baixo armazenamento
balanced	Símbolos LSP + docs/enriquecimento + vinculação de módulos	Bons resultados agênticos sem custo total
full	Todos os analisadores + definições LSP + fluxo de dados + arquitetura	Máxima precisão/riqueza

Detalhes do comportamento dos níveis:

• fast: desativa contexto de build, LSP, enriquecimento, vinculação de módulos, fluxo de dados, docs/contratos e arquitetura; filtra arestas Uses/References.
• balanced: habilita contexto de build, símbolos LSP, enriquecimento, vinculação de módulos e docs/contratos; filtra arestas References.
• full: habilita todos os analisadores e definições LSP; sem filtragem de arestas.

Configure o nível:

• CLI: codegraph index --index-tier balanced
• Env: CODEGRAPH_INDEX_TIER=balanced
• Config: [indexing] tier = "balanced"

Pré-requisitos de indexação (níveis com LSP)

Quando o nível habilita LSP (balanced/full), a indexação falha rapidamente se as ferramentas externas necessárias estiverem ausentes.

Ferramentas necessárias por linguagem:

• Rust: rust-analyzer
• TypeScript/JavaScript: node e typescript-language-server
• Python: node e pyright-langserver
• Go: gopls
• Java: jdtls
• C/C++: clangd

Se a indexação parecer travar durante a resolução LSP, você pode ajustar o tempo limite por solicitação:

• CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS (padrão 600, mínimo 5)

Se a resolução LSP falhar imediatamente e o erro incluir algo como Unknown binary 'rust-analyzer' in official toolchain ..., seu rust-analyzer é um shim do rustup sem um binário instalado. Instale um rust-analyzer executável (por exemplo, via brew install rust-analyzer ou alternando para uma toolchain que o forneça).

Regras opcionais de limites de arquitetura

Se você quiser que o CodeGraph sinalize dependências de pacotes proibidas, adicione codegraph.boundaries.toml na raiz do projeto:

[[deny]]
from = "your_crate"
to = "forbidden_crate"
reason = "explain the boundary"

A indexação emitirá arestas violates_boundary quando uma relação depends_on corresponder a uma regra de negação.

2. Ferramentas Agênticas, Não Apenas Busca

O CodeGraph não retorna uma lista de arquivos e deseja boa sorte. Ele fornece 4 ferramentas agênticas consolidadas que fazem o raciocínio:

Ferramenta	O Que Ela Realmente Faz
agentic_context	Reúne o contexto que você precisa—busca código, constrói contexto abrangente, responde perguntas semânticas
agentic_impact	Mapeia o impacto de mudanças—cadeias de dependência, fluxos de chamadas, o que quebra se você tocar em algo
agentic_architecture	O panorama geral—estrutura do sistema, superfícies de API, padrões arquitetônicos
agentic_quality	Avaliação de risco—pontos de complexidade, métricas de acoplamento, prioridades de refatoração

Cada ferramenta aceita um parâmetro opcional focus para precisão quando necessário:

Ferramenta	Valores de Foco	Comportamento Padrão
agentic_context	"search", "builder", "question"	Seleção automática com base na consulta
agentic_impact	"dependencies", "call_chain"	Analisa ambos
agentic_architecture	"structure", "api_surface"	Fornece ambos
agentic_quality	"complexity", "coupling", "hotspots"	Avaliação abrangente

Cada ferramenta executa um agente de raciocínio que planeja, busca, analisa relações no grafo e sintetiza uma resposta. Não é um resultado de busca—é uma resposta.

Ver Fluxo de Coleta de Contexto do Agente - Diagrama interativo mostrando como os agentes usam as ferramentas do grafo para coletar contexto.

Arquiteturas de Agentes

O CodeGraph implementa agentes usando Rig, a escolha padrão e recomendada (os legados react e lats implementados com autoagents ainda funcionam). Selecionável em tempo de execução via CODEGRAPH_AGENT_ARCHITECTURE=rig:

Por que o Rig é o Padrão: O backend baseado em Rig entrega o melhor desempenho com modelos modernos de pensamento e raciocínio. É uma implementação nativa em Rust que suporta sub-arquiteturas internas e fornece recursos como True Token Streaming e Recuperação Automática.

Sub-Arquiteturas Internas do Rig: Ao usar o backend rig, o sistema mapeia automaticamente as ferramentas agênticas consolidadas para a estratégia de raciocínio mais eficaz:

• LATS (Busca em Árvore): Exploração profunda de múltiplos caminhos para tarefas complexas e não lineares.
  • Usado automaticamente para: agentic_architecture (estrutura), agentic_quality e agentic_context (pergunta).
• ReAct (Linear): Raciocínio focado e de alta velocidade para consultas diretas de dados.
  • Usado automaticamente para: agentic_context (busca/construtor), agentic_impact e agentic_architecture (superfície de API).
• Reflexion (Recuperação Automática): Um fallback autocorretivo que entra em ação automaticamente se a estratégia primária falhar ao encontrar uma resposta. Ele analisa a falha e tenta novamente com um plano refinado.

Contexto de Inicialização do Agente

Os agentes podem começar com contexto leve do projeto para que suas primeiras chamadas de ferramenta não sejam às cegas. Ative via env:

• CODEGRAPH_ARCH_BOOTSTRAP=true — inclui um breve resumo de diretório/estrutura + conteúdo de README.md e CLAUDE.md+AGENTS.md ou GEMINI.md (se presentes) no contexto inicial do agente.
• CODEGRAPH_ARCH_PRIMER="<primer text>" — primer personalizado opcional injetado nas instruções de inicialização (por exemplo, áreas para focar).

Por quê? Primeiros passos mais rápidos e relevantes, menos consultas de grafo/semânticas desperdiçadas e melhores respostas de arquitetura em repositórios grandes.

Observações:

• O bootstrap é pequeno (resumo dos diretórios principais), não substitui consultas ao grafo.
• Usa a mesma seleção de projeto da indexação (CODEGRAPH_PROJECT_ID ou diretório de trabalho atual).

# Use Rig for best performance with thinking and reasoning models (recommended)
CODEGRAPH_AGENT_ARCHITECTURE=rig ./codegraph start stdio

# Use default ReAct for traditional instruction models
./codegraph start stdio

# Use LATS for complex analysis
CODEGRAPH_AGENT_ARCHITECTURE=lats ./codegraph start stdio

Todas as arquiteturas usam as mesmas 4 ferramentas agênticas consolidadas (suportadas por 6 ferramentas internas de análise de grafo) e prompting ciente do nível—apenas a estratégia de raciocínio difere.

3. Inteligência Ciente do Nível

Aqui está algo inteligente: o CodeGraph ajusta automaticamente seu comportamento com base na janela de contexto do LLM que você configurou para o agente codegraph.

Usando um modelo local pequeno? Obtenha consultas focadas e eficientes.

Usando GPT-5.1 ou Claude com contexto de 200K? Obtenha análise abrangente e exploratória.

Usando grok-4-1-fast-reasoning com contexto de 2M? Obtenha análise detalhada com gerenciamento inteligente de resultados.

O agente usa apenas a quantidade de etapas necessárias para produzir a resposta, então os tempos de execução das ferramentas variam com base na consulta e na quantidade de dados indexados no banco de dados.

Durante o desenvolvimento, o agente usou em média 3-6 etapas para produzir respostas para cenários de teste.

O agente é sem estado—ele só tem memória conversacional durante a execução das ferramentas; ele não acumula contexto/memória em múltiplas chamadas encadeadas de ferramentas. Isso já é tratado pelo seu cliente de escolha, que acumula esse contexto, então o codegraph só precisa fornecer respostas.

Seu Modelo	Comportamento do CodeGraph
< 50K tokens	Prompts concisos, máx. 3 etapas
50K-150K	Análise equilibrada, máx. 5 etapas
150K-500K	Exploração detalhada, máx. 6 etapas
> 500K (Grok, etc.)	Análise abrangente, máx. 8 etapas

Limite rígido: Máximo de 8 etapas independentemente do nível (10 com override de env). Isso evita custos descontrolados e estouro de contexto, permitindo ainda uma análise completa.

Mesma ferramenta, automaticamente otimizada para sua configuração.

4. Proteção Contra Estouro de Contexto

O CodeGraph inclui proteção em múltiplas camadas contra estouro de contexto—evitando falhas caras quando os resultados das ferramentas excedem os limites do seu modelo.

Truncamento de Resultados por Ferramenta:

• Cada resultado de ferramenta é limitado com base na janela de contexto configurada
• Resultados grandes (por exemplo, árvores de dependência com 1000+ nós) são truncados de forma inteligente
• Resultados truncados incluem metadados _truncated: true para que o agente saiba que os dados foram cortados
• Resultados de arrays mantêm os itens mais relevantes que cabem nos limites

Guarda de Acúmulo de Contexto:

• Monitora o contexto total acumulado durante o raciocínio em múltiplas etapas
• Falha rapidamente com mensagem de erro clara se os resultados acumulados das ferramentas excederem o limite seguro
• Limite: 80% da janela de contexto × 4 (estimativa conservadora para overhead de tokens)

Configure via ambiente:

# CRITICAL: Set this to match your agent's LLM context window
CODEGRAPH_CONTEXT_WINDOW=128000  # Default: 128K

# Per-tool result limit derived automatically: context_window × 2 bytes
# Accumulation limit derived automatically: context_window × 4 × 0.8 bytes

Por que isso importa: Sem essas proteções, uma única consulta agentic_impact em um código grande poderia retornar 6M+ tokens—excedendo em muito os limites da maioria dos modelos e causando falhas caras.

5. Busca Híbrida Que Realmente Funciona

Não escolhemos lados no debate "embeddings vs palavras-chave". O CodeGraph combina:

• 70% similaridade vetorial (compreensão semântica)
• 30% busca lexical (correspondências exatas importam)
• Travessia de grafo (relações e contexto)
• Reordenação opcional (precisão de cross-encoder)

O resultado? Você encontra handleUserAuth ao pesquisar por "lógica de login"—mas também ao pesquisar por "handleUserAuth".

---

Por Que Isso Importa para Codificação com IA

Quando você conecta o CodeGraph ao Claude Code, Cursor ou qualquer agente compatível com MCP:

Antes: Sua IA lê arquivos um por um, fazendo grep, gastando tokens na coleta de contexto.

Depois: Sua IA chama agentic_impact({"query": "UserService"}) e instantaneamente sabe o que quebra se você refatorar.

Isso não é uma melhoria incremental. É a diferença entre uma IA que busca no seu código e uma que o compreende.

Por que isso é poderoso para agentes de código

O CodeGraph transfere a carga cognitiva (busca + relevância + raciocínio de dependências) para as ferramentas agênticas do CodeGraph, para que seu agente de código possa gastar seu orçamento de contexto em fazer a mudança, não em descobrir o que mudar.

O que uma ferramenta agêntica retorna (exemplo)

agentic_impact retorna saída estruturada (caminhos de arquivo, números de linha e trechos/destaques limitados) além de análise:

{
  "analysis_type": "dependency_analysis",
  "query": "PromptSelector",
  "structured_output": {
    "analysis": "…what depends on PromptSelector and why…",
    "highlights": [
      { "file_path": "crates/codegraph-mcp-server/src/prompt_selector.rs", "line_number": 42, "snippet": "pub struct PromptSelector { … }" }
    ],
    "next_steps": ["…"]
  },
  "steps_taken": "5",
  "tool_use_count": 5
}

O que um agente de código teria que fazer de outra forma

Sem as ferramentas agênticas do CodeGraph, um agente de código normalmente precisa de múltiplas chamadas "de propósito único" para alcançar a mesma confiança:

• buscar o símbolo (frequentemente múltiplas estratégias: texto + semântica + busca estilo ripgrep)
• abrir e ler múltiplos arquivos (definição + usos + chamadores + módulos relacionados)
• reconstruir mentalmente grafos de dependência/chamadas a partir de evidências parciais
• repetir quando uma suposição está errada (mais leituras, mais tokens) Isso queima contexto rapidamente: ler “apenas” um punhado de arquivos de tamanho médio + contexto ao redor pode facilmente consumir dezenas de milhares de tokens, e repositórios maiores podem chegar a centenas de milhares, dependendo de quanto código é puxado para o contexto.

Com o CodeGraph, o agente obtém localizações e relacionamentos precisos (além de contexto limitado) e pode manter muito mais da janela de contexto disponível para planejar e implementar mudanças.

---

Início Rápido

1. Instalação

# Clone and build with all features
git clone https://github.com/yourorg/codegraph-rust
cd codegraph-rust
./install-codegraph-full-features.sh

Builds mais rápidos no macOS (LLVM lld)

Se você desenvolve no macOS, pode optar pelo linker lld do LLVM para uma vinculação mais rápida:

# Install LLVM so ld64.lld is on PATH (Homebrew)
brew install llvm

# Use the repo-provided Makefile targets
make build-llvm
make test-llvm

2. Iniciar SurrealDB

# Local persistent storage
surreal start --bind 0.0.0.0:3004 --user root --pass root file://$HOME/.codegraph/surreal.db

3. Aplicar Esquema

cd schema && ./apply-schema.sh

4. Indexar Seu Código

codegraph index /path/to/project -r -l rust,typescript,python

🔒 Nota de Segurança: A indexação respeita automaticamente o .gitignore e filtra padrões comuns de segredos (.env, credentials.json, *.pem, chaves de API, etc.). Seus segredos não serão incorporados ou expostos ao agente.

5. Conectar ao Claude Code

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "codegraph": {
      "command": "/full/path/to/codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

É isso. Sua IA agora entende seu código.

---

A Arquitetura

Ver Diagrama Interativo da Arquitetura - Explore a estrutura completa do workspace com componentes clicáveis e filtragem por camadas.

┌─────────────────────────────────────────────────────────────────┐
│                         Claude Code / MCP Client                │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ MCP Protocol
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Agentic Tools Layer                    │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │  Rig    │ │ ReAct   │ │  LATS   │ │ Tool Execution  │  │  │
│  │  │ Agent   │ │ Agent   │ │  Agent  │ │    Pipeline     │  │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘  │  │
│  └───────┼───────────┼───────────┼───────────────┼───────────┘  │
│          └───────────┴───────────┴───────────────┘              │
│                              │                                  │
│  ┌───────────────────────────┼───────────────────────────────┐  │
│  │                  Inner Graph Tools                        │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │ Transitive   │ │    Call      │ │     Coupling     │   │  │
│  │  │ Dependencies │ │   Chains     │ │     Metrics      │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │   Reverse    │ │    Cycle     │ │       Hub        │   │  │
│  │  │    Deps      │ │  Detection   │ │      Nodes       │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  └───────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────┐
│                         SurrealDB                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Nodes     │  │    Edges    │  │   Chunks + Embeddings   │  │
│  │  (AST +     │  │  (calls,    │  │   (HNSW vector index)   │  │
│  │   FastML)   │  │   imports)  │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              SurrealQL Graph Functions                     │ │
│  │   fn::semantic_search_nodes_via_chunks                     │ │
│  │   fn::semantic_search_chunks_with_context                  │ │
│  │   fn::get_transitive_dependencies                          │ │
│  │   fn::trace_call_chain                                     │ │
│  │   fn::calculate_coupling_metrics                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Insight-chave: As ferramentas agênticas não apenas chamam uma função. Elas raciocinam sobre quais operações de grafo realizar, encadeiam-nas e sintetizam resultados. Uma única chamada agentic_impact pode:

1. Buscar semanticamente pelo componente alvo
2. Obter suas dependências diretas
3. Rastrear dependências transitivas
4. Verificar dependências circulares
5. Calcular métricas de acoplamento
6. Identificar nós centrais que podem ser afetados
7. Sintetizar todas as descobertas em uma resposta acionável

---

Linguagens Suportadas

O CodeGraph usa tree-sitter para análise inicial e aprimora os resultados com algoritmos FastML e suporta:

Rust • Python • TypeScript • JavaScript • Go • Java • C++ • C • Swift • Kotlin • C# • Ruby • PHP • Dart

---

Flexibilidade de Provedores

Embeddings

Use qualquer modelo com dimensões de 384 a 4096:

• Local: Ollama, LM Studio, ONNX Runtime
• Nuvem: OpenAI, Jina AI

LLM (para raciocínio agêntico)

• Local: Ollama, LM Studio
• Nuvem: Anthropic Claude, OpenAI, xAI Grok, OpenAI Compliant

Banco de Dados

• SurrealDB com índice vetorial HNSW (consultas de 2 a 5 ms)
• Camada gratuita na nuvem disponível em surrealdb.com/cloud

---

Configuração

Configuração global em ~/.codegraph/config.toml:

[embedding]
provider = "ollama"
model = "qwen3-embedding:0.6b"
dimension = 1024

[llm]
provider = "anthropic"
model = "claude-sonnet-4"

[database.surrealdb]
connection = "ws://localhost:3004"
namespace = "ouroboros"
database = "codegraph"

Consulte INSTALLATION_GUIDE.md para opções completas de configuração.

Esquema de grafo experimental (opcional)

O CodeGraph pode ser executado contra um esquema estilo graphdb experimental do SurrealDB (schema/codegraph_graph_experimental.surql) que é interoperável com as ferramentas existentes do CodeGraph e o pipeline de indexação.

Em comparação com o esquema relacional/vanilla (schema/codegraph.surql), o esquema experimental é projetado para operações de consulta de grafo mais rápidas e eficientes (travessias, expansão de vizinhança e análises de grafo orientadas por ferramentas) em grandes bases de código.

Para usá-lo:

1. Carregue o esquema em um banco de dados dedicado (uma vez):

# Example (SurrealDB CLI)
surreal sql --conn ws://localhost:3004 --ns ouroboros --db codegraph_experimental < schema/codegraph_graph_experimental.surql

2. Aponte o CodeGraph para esse banco de dados:

CODEGRAPH_USE_GRAPH_SCHEMA=true
CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental

Notas:

• O arquivo de esquema define índices HNSW para múltiplas dimensões de embedding (384–4096), para que você possa alternar modelos de embedding sem refazer o banco de dados.
• O carregamento do esquema não é realizado automaticamente em tempo de execução; você deve aplicar o arquivo .surql ao banco de dados de destino antes da indexação.
• CODEGRAPH_GRAPH_DB_DATABASE controla qual banco de dados Surreal a indexação/ferramentas usam quando CODEGRAPH_USE_GRAPH_SCHEMA=true.

---

Modo Daemon

Mantenha seu índice atualizado automaticamente:

# With MCP server (recommended)
codegraph start stdio --watch

# Standalone daemon
codegraph daemon start /path/to/project --languages rust,typescript

As alterações são detectadas, com debounce, e reindexadas em segundo plano.

---

Próximos Passos

• Mais suporte a linguagens
• Análise entre repositórios
• Esquemas de grafo personalizados
• Sistema de plugins para analisadores personalizados

---

Filosofia

O CodeGraph existe porque acreditamos que os assistentes de codificação com IA devem ser aumentados, não substituídos. A melhor colaboração entre IA e humanos acontece quando a IA tem contexto profundo sobre o que você está trabalhando.

Não estamos tentando substituir sua IDE, seu verificador de tipos ou seus testes. Estamos dando à sua IA o contexto necessário para realmente ajudar.

Seu código é um grafo. Deixe sua IA vê-lo dessa forma.

---

Licença

MIT

---

Links

• Guia de Instalação
• SurrealDB Cloud (camada gratuita)
• Jina AI (tokens de API gratuitos)
• Ollama (modelos locais)

---