graphify en práctica: convertir cualquier repositorio de código en un grafo de conocimiento consultable

Dificultad media | ~20 minutos | Aprenderás el flujo completo para usar graphify y transformar cualquier repositorio de código en un grafo de conocimiento consultable, dejando atrás el grep a ciegas y logrando una comprensión estructurada del código con una compresión de tokens de 71,5x.

Descripción del proyecto

graphify es una habilidad (skill) de asistente de codificación con IA, desarrollada por Safi Shamsi. Su repositorio en GitHub está en safishamsi/graphify. Su enfoque es muy simple: comprimir cualquier carpeta (código, notas, artículos, imágenes e incluso vídeos) en un único grafo de conocimiento consultable, para que cada conversación con tu asistente de IA se base en conocimiento estructurado en lugar de hacer búsquedas de texto completas a ciegas.

Sus puntos fuertes se resumen en tres:

• Entrada multimodal: el código (20 lenguajes), documentos, imágenes, PDF y audio/video se admite todo y se unifica en el mismo grafo
• Sin clustering por embeddings: usa el algoritmo de detección de comunidades de Leiden para agrupar directamente en función de la topología del grafo, sin necesidad de una base de vectores ni de ejecutar modelos de embedding por separado
• Confiabilidad honesta: cada arista relacional está etiquetada como EXTRACTED / INFERRED / AMBIGUOUS. Así sabes qué se encontró y qué se infirió

graphify puede usarse con comandos como /graphify en asistentes de codificación populares como Claude Code, OpenClaw, Codex, Cursor, Trae, etc., o llamarse de forma independiente mediante un MCP Server o por CLI.

Público objetivo

Has trabajado al menos en un proyecto de tamaño medio (miles de líneas de código) y usas a diario Claude Code / OpenClaw / Codex o algún otro asistente de codificación con IA. Cuando te enfrentas a un repositorio nuevo, estás acostumbrado a que lo lea directamente—pero a medida que crecen los archivos, se vuelve cada vez más evidente el problema de consumo de tokens y la fragmentación del contexto. Este artículo existe para resolver exactamente eso.

Dependencias clave y entorno

Estructura completa del proyecto

my-project/
├── graphify-out/
│   ├── graph.json          # Grafo de conocimiento persistente, consultable entre sesiones
│   ├── GRAPH_REPORT.md     # Informe de análisis estructurado (god nodes, conexiones inesperadas, preguntas sugeridas)
│   ├── graph.html          # Grafo interactivo (vis.js; abrir directamente en el navegador)
│   ├── cache/              # Directorio de caché SHA256
│   └── transcripts/        # Caché de transcripción de audio/video (solo si instalaste la dependencia de video)
├── .graphifyignore         # Reglas de exclusión (sintaxis igual que .gitignore)
└── .git/hooks/            # Se genera automáticamente tras instalar el hook de graphify

Pasos paso a paso

Paso 1 — Instalar graphify

graphify se compone de dos pasos: primero instalas el paquete de Python y luego instalas la capa de adaptación para tu asistente de codificación con IA.

# Primer paso: instala el paquete de PyPI
pip install graphifyy

# Segundo paso: instala la capa de adaptación para tu plataforma
# Por ejemplo, para Claude Code:
graphify install

# Si usas otra plataforma, reemplaza por el comando correspondiente:
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Si estás en Windows y hay problemas, especifica la plataforma explícitamente:
graphify install --platform windows

Una vez instalado, tu asistente de codificación con IA reconocerá el comando /graphify.

Paso 2 — Primera ejecución: generar el grafo de conocimiento

Entra en cualquier directorio de código que quieras analizar y ejecuta:

# Analiza el directorio actual
/graphify .

# Analiza un directorio específico
/graphify ./src

# Analiza el directorio especificado y habilita un modo de inferencia más agresivo
/graphify ./src --mode deep

# Omite la visualización en HTML; solo genera el informe y JSON (más rápido)
/graphify ./src --no-viz

graphify se ejecuta en tres etapas:

1. Extracción AST (sin LLM) — usa tree-sitter para analizar archivos de código y extraer clases, funciones, relaciones de importación, grafo de llamadas, docstrings y comentarios explicativos
2. Extracción semántica (llamando al LLM) — llama a Claude para extraer conceptos, relaciones y motivaciones de diseño a partir de documentos, artículos, imágenes, etc.
3. Construcción del grafo y clustering — combina todos los resultados de extracción y agrupa con el algoritmo de detección de comunidades de Leiden (basado en la densidad de aristas; no requiere embeddings)

Al finalizar, en el directorio graphify-out/ aparecerán tres entregables:

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

Paso 3 — Cómo usar los tres entregables

graphify-out/graph.json — El grafo persistente (la base del sistema)

Este es el núcleo del sistema. El formato es una exportación JSON estándar de NetworkX:

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

Cada arista tiene una etiqueta confidence:

• EXTRACTED: relación que existe directamente en el código fuente (confianza 1.0)
• INFERRED: inferencia razonable, con confidence_score (0.0–1.0)
• AMBIGUOUS: relación incierta; se marcará en el informe para revisión humana

graphify-out/GRAPH_REPORT.md — Informe de análisis estructurado

Este es un resumen pensado para el asistente de IA e incluye:

• God Nodes: conceptos centrales con mayor grado (por los que pasan todos los demás nodos)
• Surprising Connections: conexiones inesperadas entre archivos y/o tipos, con una explicación del "por qué"
• Suggested Questions: 4–5 preguntas que el grafo puede responder de forma distintiva
• Design Rationale: motivaciones de diseño extraídas de docstrings y comentarios (# NOTE:, # WHY:, # HACK:)

graphify-out/graph.html — Grafo interactivo

Ábrelo directamente en el navegador. Permite hacer clic en nodos, buscar y filtrar por comunidad. Es ideal para explorar la estructura del código “a mano”.

Paso 4 — Consultar el grafo: tres comandos principales

Solo tener el grafo no basta; también necesitas poder consultarlo. graphify incluye tres comandos de consulta:

query — consulta semántica

# El más usado: encontrar nodos y rutas relevantes para la pregunta en el grafo
graphify query "what connects Attention to the optimizer?"

# Limitar el presupuesto de tokens
graphify query "show the auth flow" --budget 1500

# Usar DFS para rastrear una ruta concreta (en lugar de muestreo aleatorio)
graphify query "what connects DigestAuth to Response?" --dfs

# Especificar una ruta de grafo que no sea la predeterminada
graphify query "..." --graph path/to/another-graph.json

La salida incluye etiquetas de nodos, tipo de arista, nivel de confianza, archivo fuente y ubicación. Puedes pegar directamente esta salida al asistente de IA para que responda:

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — encontrar la ruta entre dos nodos

# Rastrear la ruta completa desde el nodo A hasta el nodo B
graphify path "DigestAuth" "Response"

explain — explicar el contexto de un nodo

# Mostrar vecinos, comunidad y aristas relacionadas de un nodo
graphify explain "SwinTransformer"

Paso 5 — Integrar el hook Always-On (configuración recomendada)

Seguir escribiendo manualmente /graphify cada vez es un poco tedioso. graphify puede inyectar automáticamente el conocimiento del grafo en el contexto de la conversación del asistente de IA, para que, en cada pregunta, tenga prioridad de mirar el grafo y no buscar archivos a ciegas.

Claude Code

graphify claude install

Hace dos cosas: escribe una regla en CLAUDE.md (para que Claude lea GRAPH_REPORT.md) y, además, instala un PreToolUse hook en settings.json, para inyectar sugerencias del grafo antes de cada llamada a Glob y Grep:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae y similares

Estas plataformas no soportan tool hooks; usa AGENTS.md en su lugar:

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

Escribe .cursor/rules/graphify.mdc y configura alwaysApply: true. Cursor cargará automáticamente las reglas en cada conversación.

Para desinstalar, usa los comandos de uninstall correspondientes:

graphify claude uninstall
graphify cursor uninstall
# ...

Paso 6 — Actualizaciones incrementales: ya no reconstruirlo todo cada vez

Los repositorios cambian a diario; reconstruir el grafo completo tarda demasiado. graphify ofrece dos mecanismos de actualización incremental:

--update: extracción incremental basada en caché SHA256

# Solo procesa los archivos que han cambiado e intégralos en el grafo existente
/graphify ./src --update

En el directorio cache/, se registra el resultado anterior según un hash del contenido de cada archivo. graphify compara los hashes: solo los archivos que cambiaron vuelven a pasar por el flujo de extracción AST y LLM.

--watch: monitorizar cambios automáticamente

# Ejecutar en segundo plano; al guardar archivos de código, se reconstruye el AST al instante
/graphify ./src --watch

# Tras cambios en documentos o imágenes, te pedirá que ejecutes manualmente --update

La reconstrucción disparada por cambios en el código (--watch) es únicamente AST, por lo que es muy rápida y no necesita llamar al LLM. En cambios de documentos e imágenes, sigue siendo necesario el LLM para reextraer, así que watch te avisará para que ejecutes manualmente una vez --update.

Paso 7 — Hooks de git: reconstruir el grafo en cada commit

¿No quieres ejecutarlo manualmente ni abrir un proceso en segundo plano? Entonces delega la reconstrucción del grafo en el propio git:

graphify hook install

Escribirá dos hooks en .git/hooks/: post-commit y post-checkout. En cada commit o cambio de rama, git disparará automáticamente la reconstrucción del grafo. Si la reconstrucción falla (por ejemplo, error de parseo de AST, timeout del LLM, etc.), el hook terminará con un código de salida no nulo y se interrumpirá la operación de git para evitar fallos silenciosos.

Consultar estado y desinstalar:

graphify hook status
graphify hook uninstall

Paso 8 — Uso avanzado

Servidor MCP: acceso nativo del AI al grafo

Si tu asistente admite el protocolo MCP, expón el grafo como herramientas MCP:

python -m graphify.serve graphify-out/graph.json

La salida es una configuración MCP stdio; solo tienes que pegarla en la configuración MCP de tu asistente. Las herramientas expuestas incluyen:

• query_graph: subgrafo para consultas semánticas
• get_node: obtener detalles de un nodo
• get_neighbors: obtener nodos vecinos
• shortest_path: encontrar la ruta más corta entre dos nodos

Exportación a Neo4j

¿Quieres importar el grafo a Neo4j para hacer análisis de grafos más profesionales?

# Generar un script de Cypher (importación manual)
/graphify ./src --neo4j

# O enviar directamente al Neo4j en ejecución
/graphify ./src --neo4j-push bolt://localhost:7687

Generar una Wiki legible por agentes

# Exportar como wiki Markdown; los agentes de IA pueden navegar leyendo archivos
/graphify ./src --wiki

Se generará graphify-out/wiki/index.md (entrada) + un artículo Markdown para cada comunidad y cada god node.

Resumen de tipos de archivos soportados

Especificar otro proveedor de LLM

graphify usa, por defecto, los modelos incluidos en tu plataforma (Claude Code usa Anthropic; Codex usa OpenAI). Si quieres forzar el uso de otros modelos, puedes especificarlo mediante variables de entorno (consulta el archivo correspondiente de skill.md).

Solución de problemas frecuentes

1. Tras instalar, no se encuentra el comando graphify

Normalmente es un problema de entorno de Python o de PATH:

# Verifica la ubicación de instalación del paquete
pip show graphifyy

# Llamar con python -m (sin depender de PATH)
python -m graphify --help

# O instalar con pipx (recomendado, aislado)
pip install pipx && pipx install graphifyy

2. Hay muy pocos nodos en el grafo o casi ninguno

Comprueba si .graphifyignore excluye por error los archivos objetivo:

# Ver qué archivos está escaneando realmente graphify
/graphify ./src --no-viz  # Con --no-viz solo corre AST (no LLM); es rápido

# Revisa la sintaxis de .graphifyignore (igual que .gitignore)
cat .graphifyignore

También puede ser que el tipo de archivo no esté en la lista soportada: confirma que la extensión de tus archivos de código esté en la tabla de “tipos de archivos soportados” de arriba.

3. La fase de extracción con LLM expira o devuelve error de API

Problemas de red o configuración del API Key:

# Confirma que existe el API Key (en Claude Code suele estar configurado automáticamente)
# Los usuarios de otras plataformas deben revisar la variable de entorno del API Key correspondiente

# Usa --budget para limitar tokens y evitar peticiones demasiado grandes
/graphify ./src --budget 2000

# Si hay timeout, fuerza el salto y continúa con otros archivos (no bloquea toda la ejecución)

4. Inconsistencia tras actualizaciones incrementales por cache

La caché SHA256 está dañada o el archivo fue modificado externamente:

# Limpia la caché para forzar una reconstrucción completa
rm -rf graphify-out/cache
/graphify ./src

# O solo limpia la caché de un archivo específico
rm graphify-out/cache/<hash-correspondiente>.json
/graphify ./src --update

5. El hook PreToolUse de Claude Code no funciona

Normalmente es un problema de ruta o de formato en settings.json:

# Comprueba si los hooks se escribieron correctamente
cat ~/.claude/settings.json | grep graphify

# Si el IDE cambió el formato, añade manualmente la sección del hook de graphify
# Consulta el formato del PreToolUse hook en el skill.md de graphify

6. --watch informa que falta watchdog

watchdog es una dependencia opcional:

pip install graphifyy[watch]

Lecturas adicionales / Direcciones avanzadas

1. Personalizar Extractor: añadir soporte para un nuevo lenguaje

Si tu base de código usa un lenguaje que graphify aún no soporta (por ejemplo, Racket o Nim), puedes añadir en extract.py una nueva función extract_<lang>, basada en el parseo AST con tree-sitter, siguiendo la sección “Adding a new language extractor” de ARCHITECTURE.md. El proceso es claro: escribe la función → registra el sufijo → añade dependencias → escribe pruebas.

2. Pipeline GraphRAG: conectar consultas del grafo con RAG

gel valor central de graphify es que: en cada consulta no necesitas volver a leer los archivos originales, y el consumo de tokens pasa de O(n×tamaño del archivo) a O(tamaño del subgrafo). Al combinar con un RAG Pipeline, se recomienda esta forma de integración:

import json

# 1. Usa GRAPH_REPORT.md para判断 a alto nivel la intención
# 2. Luego usa graphify query para traer el subgrafo relevante
# 3. Alimenta el subgrafo como contexto al LLM

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] y graph["edges"] son el contexto

3. Penpax: visión de gemelo digital en el dispositivo impulsada por graphify

gel plan a largo plazo de graphify es Penpax: un proyecto de gemelo digital en el dispositivo que conecta actas de reuniones, historial del navegador, archivos, correos y código en un grafo de conocimiento que se actualiza continuamente; no sube a la nube y no requiere entrenar modelos con tus datos.

4. Extensión multimodal: convertir cursos de vídeo en un grafo

Si tienes charlas técnicas, vídeos de conferencias o audios tipo podcast, puedes usar la dependencia --video para incorporarlos al grafo de conocimiento:

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper se ejecuta localmente y el audio no sale de tu máquina. Los resultados de transcripción se guardan en graphify-out/transcripts/ y las ejecuciones repetidas leen la caché.

5. Colaboración del grafo: compartir la estructura de conocimiento en el equipo

Los entregables de graphify (graph.json, GRAPH_REPORT.md) son texto puro, por lo que puedes commitearlos en git. Después de que los miembros del equipo hagan pull, graphify hook install reutilizará automáticamente la misma versión del grafo. Esto significa que el conocimiento arquitectónico puede versionarse; durante el code review se pueden citar nodos del grafo y en la descripción de PR se pueden citar directamente los god nodes. Desde entonces, el entendimiento del equipo ya no depende de “quién le pregunta a quién”.