Graphify resuelve la mayor limitación de Claude Code: convertir un codebase en un grafo consultable por IA

Thu, 21 May 2026 08:02:32 +0800

safishamsi/graphify es una herramienta de grafo de conocimiento para asistentes de programación con IA. Su objetivo es directo: tomar el código, documentación, SQL schemas, scripts, papers, imágenes, video y audio dentro de una carpeta de proyecto, convertirlos en un grafo consultable y evitar que los asistentes de IA dependan solo de grep, lectura completa de archivos o búsquedas improvisadas para entender el proyecto.

Proyecto: safishamsi/graphify

En el momento de preparar este artículo, la página de GitHub muestra unas 50.2k stars y 5.4k forks, con licencia MIT. El README lo describe así: escribe /graphify en tu asistente de programación con IA y mapeará todo el proyecto como un grafo de conocimiento consultable.

El problema central que resuelve

Los asistentes de programación con IA son cada vez más potentes, pero en codebases reales todavía encuentran varios problemas:

No saben cómo se conectan los módulos clave.
Leen muchos archivos, pero no forman un mapa general de arquitectura.
La búsqueda encuentra texto, pero no dependencias aguas arriba y aguas abajo.
Código, database schema, documentación e infraestructura están dispersos.
En colaboración de equipo, cada persona puede tener un modelo mental distinto de la estructura del proyecto.

Graphify intenta añadir una “capa de memoria” al proyecto. Conecta entidades de código, conceptos documentales, tablas de base de datos, configuración, notas de diseño y relaciones entre archivos para que el asistente de IA pueda consultar el grafo en lugar de escanear archivos desde cero cada vez.

Uso mínimo

El uso mínimo de Graphify es muy simple. Tras instalarlo, escribe esto en tu asistente de programación con IA:

`1`	`/graphify .`

En PowerShell, el / inicial se interpreta como separador de ruta, así que en Windows PowerShell usa:

`1`	`graphify .`

Después de ejecutarlo, genera el directorio graphify-out/ con tres archivos principales:

graphify-out/
├── graph.html
├── GRAPH_REPORT.md
└── graph.json

Cada archivo cumple una función:

graph.html: grafo interactivo que se abre en el navegador, con nodos clicables, filtros y búsqueda.
GRAPH_REPORT.md: puntos destacados del proyecto, conceptos clave, conexiones inesperadas y preguntas sugeridas.
graph.json: grafo completo, consultable después sin volver a leer todos los archivos.

Para generar una página de arquitectura más legible con diagramas Mermaid de flujo de llamadas, ejecuta:

`1`	`graphify export callflow-html`

Instalación y soporte de plataformas

El paquete de Graphify en PyPI se llama graphifyy, con doble y. El README advierte que otros paquetes graphify* en PyPI no están afiliados al proyecto, aunque el comando CLI sigue siendo graphify.

La instalación recomendada es:

`1`	`uv tool install graphifyy`

También puedes usar:

1
2

pipx install graphifyy
pip install graphifyy

Después, regístralo con tu asistente de IA:

`1`	`graphify install`

El proyecto soporta muchas plataformas, incluidas Claude Code, Codex, OpenCode, GitHub Copilot CLI, VS Code Copilot Chat, Aider, Cursor, Gemini CLI, Kimi Code, Kiro y Google Antigravity. Cada plataforma puede usar comandos distintos, por ejemplo:

graphify install --platform codex
graphify install --platform gemini
graphify cursor install
graphify antigravity install

Los usuarios de Codex también deben añadir esto bajo [features] en ~/.codex/config.toml:

`1`	`multi_agent = true`

El README también indica que Codex usa $graphify, no /graphify.

Qué archivos puede procesar

Graphify cubre muchos tipos de entrada.

En código, soporta 31 lenguajes, incluidos Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, SQL, Shell, JSON y más.

En documentación, soporta:

.md
.mdx
.qmd
.html
.txt
.rst
.yaml
.yml

También puede ampliarse con dependencias opcionales:

pip install "graphifyy[pdf]"
pip install "graphifyy[office]"
pip install "graphifyy[video]"
pip install "graphifyy[mcp]"
pip install "graphifyy[neo4j]"
pip install "graphifyy[sql]"
pip install "graphifyy[all]"

pdf sirve para extracción PDF, office para .docx y .xlsx, video para transcripción de video y audio, mcp para MCP stdio server, neo4j para enviar a Neo4j, y sql para extracción de SQL schema.

Qué valor tiene el informe generado

GRAPH_REPORT.md no es un resumen normal. Selecciona relaciones del proyecto que son especialmente útiles para asistentes de IA.

El README menciona contenidos como:

God nodes: los conceptos centrales más conectados del proyecto.
Surprising connections: enlaces inesperados entre archivos o módulos.
The why: razones de diseño extraídas de comentarios, docstrings y documentos de diseño.
Suggested questions: preguntas que el grafo está especialmente preparado para responder.
Confidence tags: cada relación se marca como EXTRACTED, INFERRED o AMBIGUOUS.

Esto es importante. Una búsqueda normal solo dice “dónde aparece esta palabra”. Un grafo puede responder “con qué módulos, configuraciones, tablas y documentos se conecta este concepto”. En codebases grandes, eso se acerca más a entender la arquitectura que una simple búsqueda de texto completo.

Comandos comunes

Comandos comunes de Graphify:

/graphify .
/graphify ./docs --update
/graphify . --cluster-only
/graphify . --no-viz
/graphify . --wiki
graphify export callflow-html
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

También puedes añadir un paper o video al grafo:

1
2

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>

Para análisis asistido de PR:

graphify prs
graphify prs 42
graphify prs --triage
graphify prs --conflicts

Estos comandos encajan con revisiones de código: ver qué comunidades del grafo afecta un PR, si hay riesgo de conflicto con otros PRs y qué review queue conviene priorizar.

Relación con MCP, Neo4j y CI

Graphify no solo genera un grafo HTML. También puede exponer el grafo a asistentes de IA para uso repetido.

Por ejemplo, puedes iniciar un MCP server:

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

El MCP server ofrece capacidades como query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact y triage_prs.

También soporta exportación o push a Neo4j:

1
2

/graphify ./raw --neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687

Para trabajo en equipo, el README recomienda poder commitear graphify-out/, de modo que todos empiecen con el mismo mapa del proyecto. También puedes ejecutar:

`1`	`graphify hook install`

Así el grafo se reconstruye automáticamente después de cada git commit y se configura un merge driver para evitar que graph.json quede con marcadores de conflicto cuando varias personas commitean en paralelo.

Privacidad y coste

El README de Graphify explica bastante bien los límites de privacidad.

Los archivos de código se parsean localmente con tree-sitter y no generan llamadas API. Video y audio pueden transcribirse localmente con faster-whisper. Docs, PDFs e imágenes para extracción semántica pasan por la API del modelo usado por tu asistente de IA.

Si usas headless graphify extract, puede que necesites estas variables de entorno:

ANTHROPIC_API_KEY
GEMINI_API_KEY
GOOGLE_API_KEY
OPENAI_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
OLLAMA_BASE_URL

También pueden usarse backends como Ollama local, AWS Bedrock o Claude Code CLI. El README indica además que el proyecto no tiene telemetry, usage tracking ni analytics.

En la práctica, conviene recordar que parsear código localmente no significa que todo se quede offline. Si intervienen docs, PDFs, imágenes o modelos cloud, hay que revisar backend, API keys, cumplimiento empresarial y límites de datos.

Escenarios adecuados

Graphify encaja con varios tipos de usuarios:

Desarrolladores que quieren que Claude Code, Codex, Cursor y Gemini CLI entiendan mejor la estructura del proyecto.
Personas que necesitan comprender rápido un codebase grande y desconocido.
Equipos que quieren analizar juntos código, SQL schema, documentación y configuración.
Personas que hacen revisión de arquitectura, PR review o análisis de impacto de refactors.
Equipos que quieren exponer conocimiento del proyecto como herramienta MCP para Agents.
Líderes técnicos que quieren conservar un “mapa del proyecto” para el equipo.

No es necesario para todos los proyectos. En scripts pequeños, demos puntuales o repositorios muy simples, una búsqueda normal y el README quizá basten. El valor de Graphify aparece con más claridad en proyectos con muchos módulos, mucha documentación, mucha colaboración y uso frecuente de asistentes de IA.

Resumen

Graphify importa porque mueve el contexto de los asistentes de programación con IA desde “leer archivos temporalmente” hacia “un grafo de conocimiento del proyecto consultable y persistente”.

Para desarrolladores, no reemplaza el IDE, la búsqueda o el LSP. Añade una capa de memoria estructurada para asistentes de IA: qué módulos importan, qué conceptos están muy conectados, qué documentos explican decisiones de diseño y qué comunidades puede afectar un PR. A medida que herramientas Agent como Codex, Claude Code, Gemini CLI y Antigravity se vuelvan más comunes, esta capa de grafo del proyecto será cada vez más útil.

Referencias:

GitHub: safishamsi/graphify

Knowledge Graph on KnightLi Blog