codegraph-rust

Una implementación de graphRAG para codebase extremadamente rápida, 100% en Rust.

Documentación

CodeGraph

Tu código base, entendido.

CodeGraph transforma todo tu código base en un grafo de conocimiento con búsqueda semántica sobre el que los agentes de IA pueden razonar de verdad, no solo hacer grep.

¿Listo para empezar? Salta a la Guía de instalación para ver las instrucciones de configuración paso a paso.

¿Ya lo tienes configurado? Consulta la Guía de uso para obtener consejos sobre cómo sacar el máximo partido a CodeGraph con tu asistente de IA.

El problema

Los asistentes de IA para programar son potentes, pero vuelan a ciegas. Ven los archivos de uno en uno, hacen grep de patrones y queman tokens intentando entender tu arquitectura. Cada conversación empieza desde cero.

¿Y si tu asistente de IA ya conociera tu código base?

Qué hace CodeGraph de forma diferente

1. Grafo + embeddings = comprensión real

La mayoría de las herramientas de búsqueda semántica crean embeddings y ya está. CodeGraph construye un grafo de conocimiento 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)

Cuando buscas, no solo obtienes "código similar": obtienes código con sus relaciones intactas. La función que coincide con tu consulta, además de lo que la llama, de lo que depende y de dónde encaja en la arquitectura.

El enriquecimiento de la indexación añade:

Nodos de módulo y aristas de importación/contención a nivel de módulo para la navegación entre archivos
Aristas de flujo de datos específicas de Rust (defines, uses, flows_to, returns, mutates) para el análisis de impacto
Nodos de documento/especificación vinculados a símbolos entre comillas invertidas en README.md, docs/**/*.md y schema/**/*.surql
Señales de arquitectura (ciclos de paquetes + violaciones de límites opcionales)

Niveles de indexación (velocidad frente a riqueza)

La indexación está organizada en niveles para que puedas elegir entre velocidad/almacenamiento y riqueza del grafo. El valor predeterminado es rápido.

Nivel	Qué habilita	Uso típico
`fast`	Solo nodos AST + aristas principales (sin LSP ni enriquecimiento)	Indexación rápida, poco almacenamiento
`balanced`	Símbolos LSP + documentación/enriquecimiento + vinculación de módulos	Buenos resultados agénticos sin el coste completo
`full`	Todos los analizadores + definiciones LSP + flujo de datos + arquitectura	Máxima precisión/riqueza

Detalles del comportamiento por nivel:

fast: desactiva el contexto de compilación, LSP, enriquecimiento, vinculación de módulos, flujo de datos, documentación/contratos y arquitectura; filtra las aristas Uses/References.
balanced: activa el contexto de compilación, los símbolos LSP, el enriquecimiento, la vinculación de módulos y la documentación/contratos; filtra las aristas References.
full: activa todos los analizadores y las definiciones LSP; sin filtrado de aristas.

Configura el nivel:

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

Requisitos previos de indexación (niveles con LSP)

Cuando el nivel activa LSP (balanced/full), la indexación falla rápidamente si faltan las herramientas externas necesarias.

Herramientas necesarias por lenguaje:

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

Si la indexación parece detenerse durante la resolución LSP, puedes ajustar el tiempo de espera por solicitud:

CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS (predeterminado 600, mínimo 5)

Si la resolución LSP falla inmediatamente y el error incluye algo como Unknown binary 'rust-analyzer' in official toolchain ..., tu rust-analyzer es un shim de rustup sin un binario instalado. Instala un rust-analyzer ejecutable (por ejemplo, mediante brew install rust-analyzer o cambiando a un toolchain que lo proporcione).

Reglas de límites de arquitectura opcionales

Si quieres que CodeGraph marque dependencias de paquetes prohibidas, añade codegraph.boundaries.toml en la raíz del proyecto:

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

La indexación emitirá aristas violates_boundary cuando una relación depends_on coincida con una regla de denegación.

2. Herramientas agénticas, no solo búsqueda

CodeGraph no devuelve una lista de archivos y te desea suerte. Incluye 4 herramientas agénticas consolidadas que hacen el trabajo de pensar:

Herramienta	Qué hace realmente
`agentic_context`	Recopila el contexto que necesitas: busca código, construye contexto completo, responde preguntas semánticas
`agentic_impact`	Mapea el impacto de los cambios: cadenas de dependencias, flujos de llamadas, qué se rompe si tocas algo
`agentic_architecture`	La visión general: estructura del sistema, superficies de API, patrones arquitectónicos
`agentic_quality`	Evaluación de riesgos: puntos calientes de complejidad, métricas de acoplamiento, prioridades de refactorización

Cada herramienta acepta un parámetro opcional focus para precisión cuando sea necesario:

Herramienta	Valores de enfoque	Comportamiento predeterminado
`agentic_context`	`"search"`, `"builder"`, `"question"`	Selección automática según la consulta
`agentic_impact`	`"dependencies"`, `"call_chain"`	Analiza ambos
`agentic_architecture`	`"structure"`, `"api_surface"`	Proporciona ambos
`agentic_quality`	`"complexity"`, `"coupling"`, `"hotspots"`	Evaluación exhaustiva

Cada herramienta ejecuta un agente de razonamiento que planifica, busca, analiza las relaciones del grafo y sintetiza una respuesta. No es un resultado de búsqueda: es una respuesta.

Ver el flujo de recopilación de contexto del agente - Diagrama interactivo que muestra cómo los agentes usan las herramientas del grafo para recopilar contexto.

AgenticArchitectures

Arquitecturas de agentes

CodeGraph implementa agentes usando Rig, la opción predeterminada y recomendada (los react y lats heredados implementados con autoagents siguen funcionando). Seleccionable en tiempo de ejecución mediante CODEGRAPH_AGENT_ARCHITECTURE=rig:

Por qué Rig es el predeterminado: El backend basado en Rig ofrece el mejor rendimiento con los modelos de razonamiento y pensamiento modernos. Es una implementación nativa en Rust que admite subarquitecturas internas y proporciona funciones como True Token Streaming y Automatic Recovery.

Subarquitecturas internas de Rig: Al usar el backend rig, el sistema asigna automáticamente las herramientas agénticas consolidadas a la estrategia de razonamiento más eficaz:

LATS (búsqueda en árbol): exploración profunda de múltiples rutas para tareas complejas y no lineales.
- Se usa automáticamente para: agentic_architecture (estructura), agentic_quality y agentic_context (pregunta).
ReAct (lineal): razonamiento rápido y centrado para consultas directas de datos.
- Se usa automáticamente para: agentic_context (búsqueda/constructor), agentic_impact y agentic_architecture (superficie de API).
Reflexion (recuperación automática): un mecanismo de respaldo autocorrectivo que se activa automáticamente si la estrategia principal no encuentra una respuesta. Analiza el fallo y reintenta con un plan refinado.

Contexto de arranque del agente

Los agentes pueden empezar con un contexto ligero del proyecto para que sus primeras llamadas a herramientas no sean a ciegas. Actívalo mediante variables de entorno:

CODEGRAPH_ARCH_BOOTSTRAP=true — incluye un breve resumen de arranque de directorio/estructura + el contenido de README.md y CLAUDE.md+AGENTS.md o GEMINI.md (si existen) en el contexto inicial del agente.
CODEGRAPH_ARCH_PRIMER="<primer text>" — imprimación personalizada opcional inyectada en las instrucciones de inicio (por ejemplo, áreas en las que centrarse).

¿Por qué? Primeros pasos más rápidos y relevantes, menos consultas de grafo/semántica desperdiciadas y mejores respuestas de arquitectura en repositorios grandes.

Notas:

El arranque es pequeño (resumen de directorios principales), no sustituye a las consultas del grafo.
Usa la misma selección de proyecto que la indexación (CODEGRAPH_PROJECT_ID o el directorio de trabajo actual).

# 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 las arquitecturas usan las mismas 4 herramientas agénticas consolidadas (respaldadas por 6 herramientas internas de análisis del grafo) y prompts conscientes del nivel: solo cambia la estrategia de razonamiento.

3. Inteligencia consciente del nivel

Aquí hay algo ingenioso: CodeGraph ajusta automáticamente su comportamiento según la ventana de contexto del LLM que hayas configurado para el agente de codegraph.

¿Usas un modelo local pequeño? Obtén consultas centradas y eficientes.

¿Usas GPT-5.1 o Claude con 200K de contexto? Obtén un análisis exhaustivo y exploratorio.

¿Usas grok-4-1-fast-reasoning con 2M de contexto? Obtén un análisis detallado con gestión inteligente de resultados.

El agente solo usa la cantidad de pasos que necesita para producir la respuesta, por lo que los tiempos de ejecución de las herramientas varían según la consulta y la cantidad de datos indexados en la base de datos.

Durante el desarrollo, el agente usó una media de 3-6 pasos para producir respuestas en los escenarios de prueba.

El agente no tiene estado: solo tiene memoria conversacional durante la ejecución de la herramienta. No acumula contexto/memoria a lo largo de múltiples llamadas encadenadas de herramientas; eso ya lo gestiona el cliente que elijas, que acumula ese contexto, así que codegraph solo necesita proporcionar respuestas.

Tu modelo	Comportamiento de CodeGraph
< 50K tokens	Prompts concisos, máx. 3 pasos
50K-150K	Análisis equilibrado, máx. 5 pasos
150K-500K	Exploración detallada, máx. 6 pasos
> 500K (Grok, etc.)	Análisis exhaustivo, máx. 8 pasos

Límite máximo: Máximo 8 pasos independientemente del nivel (10 con anulación por variable de entorno). Esto evita costes descontrolados y desbordamiento de contexto, al tiempo que permite un análisis exhaustivo.

La misma herramienta, optimizada automáticamente para tu configuración.

4. Protección contra el desbordamiento de contexto

CodeGraph incluye protección multicapa contra el desbordamiento de contexto, lo que evita fallos costosos cuando los resultados de las herramientas superan los límites de tu modelo.

Truncamiento de resultados por herramienta:

Cada resultado de herramienta se limita según la ventana de contexto configurada
Los resultados grandes (por ejemplo, árboles de dependencias con más de 1000 nodos) se truncan de forma inteligente
Los resultados truncados incluyen metadatos _truncated: true para que el agente sepa que se recortaron datos
Los resultados de arrays conservan los elementos más relevantes que caben dentro de los límites

Protección de acumulación de contexto:

Supervisa el contexto total acumulado durante el razonamiento de varios pasos
Falla rápidamente con un mensaje de error claro si los resultados acumulados de las herramientas superan el umbral seguro
Umbral: 80% de la ventana de contexto × 4 (estimación conservadora del overhead de tokens)

Configuración mediante variables de entorno:

# 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 qué es importante: Sin estas protecciones, una sola consulta agentic_impact en un código base grande podría devolver más de 6M de tokens, superando con creces los límites de la mayoría de los modelos y provocando fallos costosos.

5. Búsqueda híbrida que funciona de verdad

No elegimos bando en el debate "embeddings vs palabras clave". CodeGraph combina:

70% similitud vectorial (comprensión semántica)
30% búsqueda léxica (las coincidencias exactas importan)
Recorrido del grafo (relaciones y contexto)
Reordenación opcional (precisión con cross-encoder)

¿El resultado? Encuentras handleUserAuth cuando buscas "login logic", pero también cuando buscas "handleUserAuth".

Intelligence

Por qué esto importa para la programación con IA

Cuando conectas CodeGraph a Claude Code, Cursor o cualquier agente compatible con MCP:

Antes: Tu IA lee los archivos uno a uno, hace grep por ahí y quema tokens recopilando contexto.

Después: Tu IA llama a agentic_impact({"query": "UserService"}) y sabe al instante qué se rompe si refactorizas.

Esto no es una mejora incremental. Es la diferencia entre una IA que busca en tu código y una que lo entiende.

Por qué esto es potente para los agentes de código

CodeGraph traslada la carga cognitiva (búsqueda + relevancia + razonamiento de dependencias) a las herramientas agénticas de CodeGraph, para que tu agente de código pueda gastar su presupuesto de contexto en hacer el cambio, no en descubrir qué cambiar.

Qué devuelve una herramienta agéntica (ejemplo)

agentic_impact devuelve una salida estructurada (rutas de archivo, números de línea y fragmentos/resúmenes acotados) además del análisis:

{
  "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
}

Qué tendría que hacer un agente de código sin esto

Sin las herramientas agénticas de CodeGraph, un agente de código normalmente necesita múltiples llamadas de "un solo propósito" para alcanzar la misma confianza:

buscar el símbolo (a menudo con varias estrategias: texto + semántica + búsqueda estilo ripgrep)
abrir y leer varios archivos (definición + usos + llamadores + módulos relacionados)
reconstruir mentalmente los grafos de dependencias/llamadas a partir de evidencia parcial
repetir cuando una suposición es incorrecta (más lecturas, más tokens) Esto consume contexto rápidamente: leer “solo” un puñado de archivos de tamaño mediano más el contexto circundante puede consumir fácilmente decenas de miles de tokens, y repos más grandes pueden llegar a cientos de miles dependiendo de cuánto código se incorpore al contexto.

Con CodeGraph, el agente obtiene ubicaciones y relaciones precisas (además de contexto acotado) y puede mantener mucho más del contexto disponible para planificar e implementar cambios.

Inicio Rápido

1. Instalación

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

Compilaciones más rápidas en macOS (LLVM lld)

Si desarrollas en macOS, puedes optar por el enlazador lld de LLVM para un enlazado más rápido:

# 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 el Esquema

cd schema && ./apply-schema.sh

4. Indexar Tu Código

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

🔒 Nota de Seguridad: La indexación respeta automáticamente .gitignore y filtra patrones comunes de secretos (.env, credentials.json, *.pem, claves API, etc.). Tus secretos no se incrustarán ni se expondrán al agente.

5. Conectar a Claude Code

Añade a tu configuración de MCP:

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

Eso es todo. Tu IA ahora entiende tu código.

La Arquitectura

Ver Diagrama de Arquitectura Interactivo - Explora la estructura completa del workspace con componentes clicables y filtrado por capas.

┌─────────────────────────────────────────────────────────────────┐
│                         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                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Idea clave: Las herramientas agénticas no solo llaman a una función. Razonan sobre qué operaciones de grafo realizar, las encadenan y sintetizan resultados. Una sola llamada a agentic_impact podría:

Buscar semánticamente el componente objetivo
Obtener sus dependencias directas
Rastrear dependencias transitivas
Verificar dependencias circulares
Calcular métricas de acoplamiento
Identificar nodos centrales que podrían verse afectados
Sintetizar todos los hallazgos en una respuesta accionable

Lenguajes Soportados

CodeGraph usa tree-sitter para el análisis inicial y mejora los resultados con algoritmos FastML, soportando:

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

Flexibilidad de Proveedores

Embeddings

Usa cualquier modelo con dimensiones 384-4096:

Local: Ollama, LM Studio, ONNX Runtime
Nube: OpenAI, Jina AI

LLM (para razonamiento agéntico)

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

Base de Datos

SurrealDB con índice vectorial HNSW (consultas de 2-5ms)
Nivel gratuito en la nube disponible en surrealdb.com/cloud

Configuración

Configuración global en ~/.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"

Consulta INSTALLATION_GUIDE.md para las opciones de configuración completas.

Esquema de grafo experimental (opcional)

CodeGraph puede ejecutarse con un esquema experimental tipo graphdb de SurrealDB (schema/codegraph_graph_experimental.surql) que es interoperable con las herramientas existentes de CodeGraph y el pipeline de indexación.

En comparación con el esquema relacional/estándar (schema/codegraph.surql), el esquema experimental está diseñado para operaciones de consulta de grafo más rápidas y eficientes (recorridos, expansión de vecindarios y análisis de grafos impulsado por herramientas) en bases de código grandes.

Para usarlo:

Carga el esquema en una base de datos dedicada (una vez):

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

Apunta CodeGraph a esa base de datos:

CODEGRAPH_USE_GRAPH_SCHEMA=true
CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental

Notas:

El archivo de esquema define índices HNSW para múltiples dimensiones de embeddings (384–4096) para que puedas cambiar de modelo de embeddings sin rehacer la base de datos.
La carga del esquema no se realiza automáticamente en tiempo de ejecución; debes aplicar el archivo .surql a la base de datos objetivo antes de indexar.
CODEGRAPH_GRAPH_DB_DATABASE controla qué base de datos de Surreal usan la indexación y las herramientas cuando CODEGRAPH_USE_GRAPH_SCHEMA=true.

Modo Daemon

Mantén tu índice actualizado automáticamente:

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

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

Los cambios se detectan, se debouncean y se re-indexan en segundo plano.

Lo Que Viene

Más soporte de lenguajes
Análisis entre repositorios
Esquemas de grafo personalizados
Sistema de plugins para analizadores personalizados

Filosofía

CodeGraph existe porque creemos que los asistentes de codificación con IA deberían ser aumentados, no reemplazados. La mejor colaboración entre IA y humanos ocurre cuando la IA tiene contexto profundo sobre aquello con lo que estás trabajando.

No intentamos reemplazar tu IDE, tu verificador de tipos o tus pruebas. Le damos a tu IA el contexto que necesita para ayudar de verdad.

Tu código es un grafo. Deja que tu IA lo vea así.

Licencia

MIT

Enlaces

Guía de Instalación
SurrealDB Cloud (nivel gratuito)
Jina AI (tokens API gratuitos)
Ollama (modelos locales)

CodeGraph