Los asistentes de programación con IA han mejorado mucho leyendo archivos, buscando símbolos y explicando fragmentos de código. Pero siguen teniendo un problema conocido: cuando un proyecto crece, el contexto se fragmenta. El modelo puede entender una función, una clase o un módulo concreto, pero le cuesta reconstruir la arquitectura completa, las decisiones de diseño, la relación entre documentación y código, o el motivo por el que una pieza existe.
Graphify intenta resolver justo esa limitación. El proyecto, publicado en GitHub por Safi Shamsi, se presenta como una skill para asistentes de código IA capaz de convertir una carpeta de trabajo en un grafo de conocimiento consultable. No solo procesa código: también puede incorporar esquemas SQL, scripts, documentación, papers, imágenes, vídeos y audio para construir una representación conectada del proyecto. La idea es que Claude Code, Codex, Cursor, Gemini CLI, OpenCode u otros asistentes dejen de navegar solo con búsquedas sueltas y empiecen a moverse por una estructura persistente.
Su uso más interesante está dentro de Claude Code. Una vez instalado, el desarrollador puede escribir /graphify . en el chat del asistente y pedirle que construya un grafo del directorio actual. A partir de ahí, el modelo no tiene que releer todo el repositorio en cada pregunta: puede consultar graph.json, revisar GRAPH_REPORT.md, abrir una visualización HTML o buscar caminos concretos entre conceptos, clases, servicios y documentos.
Del repositorio plano al grafo de conocimiento
Graphify parte de una idea sencilla: un proyecto real no es una colección de archivos aislados. Es una red de relaciones. Una clase llama a otra, un servicio depende de una tabla, una migración cambia un modelo, una decisión de arquitectura aparece en un comentario, un README explica una limitación, un paper justifica una técnica y un diagrama muestra una dependencia que no siempre está explícita en el código.
La herramienta procesa ese material en varias pasadas. Primero analiza los archivos de código de forma determinista con tree-sitter, sin usar un LLM. Extrae clases, funciones, imports, llamadas, docstrings, comentarios y, en SQL, tablas, vistas, claves foráneas y relaciones de JOIN. Esa parte se ejecuta localmente y, según la documentación, los archivos de código no se envían al extractor semántico del modelo en el flujo normal.
Después puede transcribir vídeos y audios de forma local con faster-whisper. Para mejorar la transcripción, usa como orientación los conceptos más conectados del grafo generado hasta ese momento. Por último, los documentos, papers, imágenes y transcripciones pasan por subagentes de Claude, que extraen conceptos, relaciones y justificaciones en fragmentos JSON. Todo se fusiona en un grafo NetworkX, se agrupa mediante Leiden y se exporta en varios formatos.
Ese detalle es importante porque diferencia a Graphify de una búsqueda por embeddings o de un RAG clásico. El clustering no se basa en una base vectorial aparte, sino en la topología del grafo. Las comunidades se forman según densidad de relaciones; si Claude detecta una similitud semántica, esa relación ya queda como una arista dentro del grafo. La estructura del proyecto pasa a ser la señal de navegación.
| Elemento | Qué genera Graphify |
|---|---|
| Código | Clases, funciones, llamadas, imports, comentarios y relaciones |
| SQL | Tablas, vistas, claves foráneas y relaciones de consulta |
| Documentación | Conceptos, referencias, decisiones y enlaces entre documentos |
| Imágenes y diagramas | Entidades y relaciones visuales extraídas por el modelo |
| Audio y vídeo | Transcripción local y conceptos conectados al grafo |
| Resultado | graph.html, GRAPH_REPORT.md, graph.json y caché incremental |
El resultado aparece en una carpeta graphify-out/. El archivo graph.html permite explorar el grafo en el navegador; GRAPH_REPORT.md resume nodos centrales, conexiones inesperadas y preguntas sugeridas; graph.json conserva el grafo completo para consultas futuras; y la caché evita reprocesar archivos que no han cambiado.
Cómo se usa dentro de Claude Code
La instalación recomendada se hace con uv o pipx, porque el paquete oficial de PyPI se llama graphifyy, aunque el comando de consola es graphify. Tras instalarlo, graphify install registra la skill en el asistente compatible. En Claude Code, el flujo básico es instalar y escribir /graphify . desde el chat del proyecto.
uv tool install graphifyy
graphify installDentro de Claude Code:
/graphify .Ese comando construye el grafo del directorio actual. También puede apuntar a una carpeta concreta, por ejemplo /graphify ./docs o /graphify ./raw, si se quiere indexar documentación, notas, papers o un subconjunto del repositorio.
La integración más potente llega con el modo “always-on”. Después de construir el grafo, se puede ejecutar:
graphify claude installEste comando añade instrucciones en CLAUDE.md y configura un hook PreToolUse para Claude Code. Según la documentación, ese hook se dispara antes de llamadas de búsqueda o lectura de archivos y empuja al asistente a consultar primero el grafo, en lugar de empezar por grep, Glob o lectura manual de ficheros. En la práctica, Claude recibe una indicación para revisar GRAPH_REPORT.md y orientarse por nodos centrales, comunidades y conexiones antes de recorrer el repositorio de forma plana.
Esto cambia bastante la experiencia. En lugar de pedirle a Claude “búscame dónde se gestiona la autenticación” y esperar que lea varios archivos, se le puede pedir que consulte el grafo. Graphify ofrece comandos específicos para preguntas, caminos y explicaciones:
/graphify query "qué conecta la autenticación con la base de datos"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"Lenguaje del código: JavaScript (javascript)query sirve para preguntas abiertas sobre el grafo. path busca el camino entre dos nodos concretos. explain devuelve todo lo que Graphify sabe sobre una entidad. La ventaja es que el asistente puede responder con relaciones, tipos de arista, puntuaciones de confianza y ubicación de origen, no solo con fragmentos encontrados por texto.
Opciones útiles para proyectos reales
Graphify tiene una opción especialmente práctica para repositorios vivos: --update. Permite reextraer solo archivos modificados y fusionar los cambios con el grafo existente. Para equipos, esto importa porque el primer análisis puede costar tiempo y tokens, pero las ejecuciones posteriores se apoyan en caché SHA256.
/graphify . --updateCuando lo que cambia no son los archivos sino la forma de agrupar comunidades, puede usarse --cluster-only:
/graphify . --cluster-only
/graphify . --cluster-only --resolution 1.5La primera variante recalcula comunidades sobre el grafo ya existente. La segunda permite comunidades más granulares. Para grafos grandes, también se puede saltar la visualización HTML con --no-viz, algo útil cuando graph.html empieza a ser pesado para el navegador.
/graphify . --no-vizPara documentación más navegable por humanos o agentes, hay dos salidas interesantes. --wiki genera una wiki en Markdown basada en comunidades del grafo, y --obsidian permite crear un vault de Obsidian. También se puede exportar a SVG, GraphML, Neo4j o FalkorDB en versiones más avanzadas del flujo.
/graphify ./raw --wiki
/graphify ./raw --obsidian
/graphify ./raw --graphml
/graphify ./raw --neo4jLa herramienta también puede añadir fuentes externas. Por ejemplo, un paper de arXiv o un vídeo:
/graphify add https://arxiv.org/abs/1706.03762
/graphify add <video-url>Lenguaje del código: HTML, XML (xml)Esto es útil cuando un equipo trabaja con código y documentación técnica externa a la vez. Un repositorio de machine learning puede conectar código, papers, diagramas de arquitectura y decisiones de implementación en un solo grafo.
Hooks, equipos y MCP
Graphify no está pensado solo para una ejecución puntual. Puede instalar hooks de Git para mantener el grafo actualizado tras commits o cambios de rama:
graphify hook installLa documentación recomienda que una persona del equipo ejecute /graphify . y suba graphify-out/ al repositorio, para que el resto pueda partir del mismo mapa. Después, los hooks permiten reconstrucciones AST tras commits sin coste de API y ayudan a fusionar graph.json cuando varios desarrolladores trabajan en paralelo.
Otra opción más avanzada es servir el grafo mediante MCP. Graphify puede levantar un servidor local o HTTP para que uno o varios asistentes consulten herramientas como query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact o triage_prs. En un entorno de equipo, esto permite que varios clientes apunten al mismo grafo en lugar de mantener copias locales desalineadas.
python -m graphify.serve graphify-out/graph.json
python -m graphify.serve graphify-out/graph.json --transport http --port 8080Si se expone por HTTP fuera de localhost, la propia documentación recomienda usar --api-key. Es un detalle pequeño, pero relevante: un grafo de proyecto puede revelar mucha información sobre arquitectura, nombres internos, dependencias y decisiones técnicas.
Privacidad y límites
Graphify tiene un enfoque razonable de privacidad, aunque no conviene simplificarlo. El código se procesa localmente mediante tree-sitter y un corpus formado solo por código puede extraerse sin API. Los vídeos y audios se transcriben localmente con faster-whisper. Los documentos, PDFs e imágenes sí se envían al modelo configurado en el asistente para la extracción semántica.
Esto significa que un equipo con requisitos estrictos de residencia de datos debe configurar bien el backend. Graphify puede trabajar con Anthropic, OpenAI, Gemini, DeepSeek, Azure OpenAI, Bedrock, Kimi u Ollama, entre otros. Para escenarios sensibles, la documentación recomienda usar --backend ollama si se quiere procesamiento local, o seleccionar de forma explícita el proveedor adecuado.
graphify extract ./docs --backend ollama
graphify extract ./docs --backend claude
graphify extract ./docs --backend bedrockTambién hay que entender que Graphify no convierte al asistente en infalible. La herramienta etiqueta las relaciones como EXTRACTED, INFERRED o AMBIGUOUS. Las primeras proceden directamente de la fuente; las inferidas tienen puntuación de confianza; las ambiguas se marcan para revisión. Esto es una buena práctica porque evita mezclar hallazgos con suposiciones sin avisar.
Para proyectos con secretos, dependencias generadas o carpetas enormes, conviene crear un .graphifyignore, con sintaxis similar a .gitignore, para excluir node_modules, dist, código generado o cualquier material que no deba entrar en el grafo. La herramienta respeta .gitignore y permite reforzar exclusiones con .graphifyignore.
# .graphifyignore
node_modules/
dist/
*.generated.py
.env
secrets/Lenguaje del código: PHP (php)Por qué puede importar a los equipos de desarrollo
El valor de Graphify no está en sustituir a Sourcegraph, a un buscador de código o a una base vectorial. Su punto fuerte es otro: dar a los asistentes de programación una memoria estructural del proyecto. Eso puede ayudar en onboarding, revisión de arquitectura, análisis de deuda técnica, migraciones, auditorías, PRs complejas y explicación de sistemas que han crecido durante años.
Un desarrollador nuevo puede preguntar qué nodos concentran más dependencias. Un arquitecto puede buscar conexiones inesperadas entre módulos. Un equipo de seguridad puede pedir caminos entre entrada de usuario y persistencia. Un responsable técnico puede revisar qué partes del proyecto comparten comunidad con un cambio de PR. Un equipo de datos puede cruzar código, SQL y documentación en una sola representación.
El uso dentro de Claude Code lo vuelve especialmente natural porque no exige salir del chat. El desarrollador construye el grafo, pregunta y deja que el asistente navegue por relaciones en vez de improvisar búsquedas. La diferencia no es solo comodidad; es coste de contexto. La documentación de Graphify cita un benchmark propio con un corpus mixto de repositorios, papers e imágenes en el que las consultas sobre el grafo consumen 71,5 veces menos tokens que leer los archivos en bruto. Es una cifra del propio proyecto y depende del corpus, pero ilustra bien el objetivo: pagar el coste de construir el mapa una vez y reutilizarlo en muchas consultas.
Graphify encaja en una tendencia más amplia: los asistentes de código necesitan memoria persistente, estructura y herramientas especializadas. Leer archivos al vuelo seguirá siendo necesario, pero no basta para entender sistemas grandes. A medida que los agentes programadores ganen autonomía, necesitarán mapas fiables del terreno. Graphify propone uno basado en grafos, etiquetas de confianza y una integración directa con el flujo de trabajo del desarrollador.
No es una herramienta para todos los casos. En un repositorio pequeño puede aportar claridad, pero no grandes ahorros de contexto. En un proyecto sensible hay que revisar qué documentos se envían a modelos externos. En un monorepo enorme hará falta ajustar exclusiones, caché, visualización y backend. Pero para equipos que ya usan Claude Code o asistentes similares a diario, la idea es potente: antes de pedirle al modelo que lea medio proyecto, darle un mapa del proyecto.
Preguntas frecuentes
¿Qué es Graphify?
Graphify es una skill open source para asistentes de programación con IA que convierte carpetas de código, documentación, SQL, imágenes, papers, audio o vídeo en un grafo de conocimiento consultable.
¿Cómo se usa dentro de Claude Code?
Tras instalar el paquete graphifyy y registrar la skill con graphify install, se escribe /graphify . en Claude Code para construir el grafo del proyecto. Después se pueden usar comandos como /graphify query, /graphify path y /graphify explain.
¿Qué hace graphify claude install?
Instala instrucciones en CLAUDE.md y un hook PreToolUse para que Claude Code consulte el grafo antes de buscar o leer archivos de forma directa en preguntas de arquitectura o navegación del código.
¿El código se envía a un modelo externo?
Según la documentación, los archivos de código se procesan localmente con tree-sitter. Los documentos, PDFs e imágenes sí pueden enviarse al modelo configurado para extracción semántica, salvo que se configure un backend local como Ollama.
¿Qué aporta frente a una búsqueda normal en el repositorio?
La búsqueda localiza texto. Graphify intenta representar relaciones: llamadas, imports, dependencias, decisiones, conceptos, comunidades y caminos entre nodos. Eso puede ayudar al asistente a entender la estructura del sistema, no solo a encontrar coincidencias.
