Saltar al contenido principal

graphify

🚫 Deprecado — reemplazado por codebase-memory-mcp (decisión 2026-07-15). Wiedii ya no recomienda graphify para proyectos nuevos: codebase-memory-mcp es más simple de mantener — extracción determinista vía tree-sitter (sin LLM, sin costo de tokens en cada commit) y el índice vive fuera del repo. Esta página queda como referencia para repos que aún no migraron.

⚠️ Verificar versiones antes de usar — la versión de graphify documentada aquí puede estar desactualizada. Consultar uv tool list o PyPI: graphifyy para la versión más reciente. Verificar también el requisito mínimo de Python en el repositorio oficial. Ver politicas-core.

🧭 En una frase. graphify lee un proyecto entero (código, documentos, imágenes…) y arma un mapa navegable de cómo se conecta todo, para que la IA lo entienda rápido sin leer archivo por archivo. El dev normal no lo instala a mano: viene ya configurado en los proyectos que lo usan — esta página es material de referencia, no un paso obligatorio de tu día a día.

AI coding assistant skill que convierte cualquier carpeta de código, documentos, PDFs, imágenes o videos en un knowledge graph consultable. Diseñado para Claude Code, Cursor, Gemini CLI y otros asistentes de código.

Qué es​

graphify analiza un repositorio en tres pasadas:

  1. Pasada AST determinista — extrae clases, funciones, imports, call graphs y comentarios de rationale sin llamar a ningún LLM. Soporta 20 lenguajes vía tree-sitter (Python, JS/TS, Go, Rust, Java, C/C++, etc.).
  2. Pasada de transcripción local — los archivos de video y audio se transcriben con faster-whisper. El audio nunca sale de la máquina.
  3. Pasada semántica con Claude — docs, papers e imágenes se procesan con subagentes paralelos para extraer conceptos, relaciones y rationale de diseño.

El resultado se fusiona en un grafo NetworkX, se clusteriza con detección de comunidades Leiden y se exporta como HTML interactivo, JSON consultable y un reporte en lenguaje natural.

Por qué la usamos en Wiedii​

  • 71x menos tokens por consulta vs leer archivos raw en proyectos grandes.
  • Permite a Claude navegar por estructura en lugar de hacer grep por cada archivo.
  • El grafo persiste entre sesiones — se construye una vez, se consulta indefinidamente.
  • Cache SHA256: los re-runs solo procesan archivos modificados.
  • Cada relación está etiquetada EXTRACTED (encontrada en el código), INFERRED (inferencia con score de confianza) o AMBIGUOUS (marcada para revisión).

Instalación​

# Requiere Python 3.10+
uv tool install graphifyy   # PyPI: graphifyy (doble y), CLI: graphify

# Verificar PATH
which graphify
# → /Users/<user>/.local/bin/graphify

# Instalar la skill globalmente en Claude Code
graphify install

Nota importante: el paquete PyPI se llama graphifyy (con doble y), pero el CLI y el comando de skill son graphify (una sola y). Otros paquetes graphify* en PyPI no son afiliados.

PATH en macOS​

uv tool install pone el binario en ~/.local/bin. Asegurarse de que esté en el PATH del zshrc:

export PATH="$HOME/.local/bin:$PATH"

Si el PATH no estaba configurado, correr uv tool update-shell para que uv lo agregue automáticamente.

Para que graphify funcione correctamente (checklist del developer)​

  1. Instalar el binario (una vez por máquina): uv tool install graphifyy (Python 3.10+); ~/.local/bin en el PATH (uv tool update-shell si falta).
  2. Registrar la skill (una vez): graphify install (o graphify install --platform claude) → habilita /graphify en Claude Code.
  3. Construir el grafo del repo: graphify . → genera graphify-out/.
  4. Activar el "consultar primero": graphify claude install → escribe en el CLAUDE.md del proyecto la instrucción de leer el grafo antes de preguntas de arquitectura + un hook PreToolUse que navega el grafo antes de Glob/Grep.
  5. Mantenerlo al día: hook post-commit de lefthook (graphify . --update, ver abajo). No uses graphify hook install — escribe sus propios git hooks y choca con lefthook, que es el gestor de hooks de Wiedii.
  6. graphify-out/ va git-ignorado (ya es regla — ver cross-platform).

Si el binario no está instalado, la skill simplemente no actúa (no rompe nada). Por eso en la auditoría de proyectos es una recomendación, no un fallo.

Flujo de uso por proyecto​

cd ~/Docker/<repo>

# 1. Construir el knowledge graph del proyecto
graphify .

# 2. Instalar el always-on hook para Claude Code
graphify claude install

graphify claude install hace dos cosas:

  • Agrega una sección en CLAUDE.md del proyecto indicando que Claude lea graphify-out/GRAPH_REPORT.md antes de responder preguntas de arquitectura.
  • Instala un hook PreToolUse en settings.json que se dispara antes de cada Glob/Grep: si existe un knowledge graph, Claude navega por él en lugar de buscar archivos raw.

⚠️ Consultar primero, pero verificar contra el código. El grafo es un derivado para orientarte rápido y barato (arquitectura, navegación, "¿dónde está X?"). No es la fuente de verdad: puede ir por detrás de cambios sin commitear (el hook lo refresca en cada commit). Para detalles puntuales o actuales, confirmar en el archivo real. Coherente con conducta-ia (verificar antes de afirmar).

Actualización automática en cada commit (lefthook)​

El grafo debe mantenerse actualizado con el código. La forma preferida en Wiedii es añadir un hook post-commit en lefthook.yaml del proyecto:

post-commit:
  commands:
    graphify-update:
      # Solo corre si el grafo ya fue inicializado (graphify-out/ existe).
      # --update solo re-procesa archivos con SHA-256 diferente — < 5s en cambios incrementales.
      run: '[ -d graphify-out ] && graphify . --update || true'

Esto garantiza que después de cada commit el grafo refleja el estado real del código, sin que el desarrollador tenga que acordarse de actualizarlo manualmente.

La condición [ -d graphify-out ] hace que el hook sea un no-op en clones frescos donde graphify todavía no ha sido inicializado — no falla, no requiere graphify instalado, no bloquea el flujo.

Outputs generados​

graphify-out/
├── graph.html        # grafo interactivo — click en nodos, búsqueda, filtro por comunidad
├── GRAPH_REPORT.md   # god nodes, conexiones sorprendentes, preguntas sugeridas
├── graph.json        # grafo persistente — consultar semanas después sin re-leer
└── cache/            # cache SHA256 — re-runs solo procesan archivos modificados

Comandos clave​

# Construir grafo
graphify .                          # directorio actual
graphify ./src                      # carpeta específica
graphify . --update                 # re-extraer solo archivos modificados
graphify . --mode deep              # extracción INFERRED más agresiva

# Consultar el grafo desde terminal
graphify query "¿qué conecta el módulo de auth con Response?"
graphify query "muestra el flujo de autenticación" --dfs
graphify path "DigestAuth" "Response"
graphify explain "SwinTransformer"

# Watch mode — actualización automática mientras se trabaja
graphify . --watch

# Always-on para Claude Code (por proyecto)
graphify claude install
graphify claude uninstall

.graphifyignore​

Crear un .graphifyignore en la raíz del proyecto para excluir directorios del grafo:

# .graphifyignore — misma sintaxis que .gitignore
node_modules/
dist/
.next/
vendor/
*.generated.ts
graphify-out/

Gitignore recomendado​

Los outputs de graphify no deben commitearse (son derivados regenerables):

# Graphify — knowledge graph generado localmente
graphify-out/

Tipos de archivos soportados​

TipoExtensionesExtracción
Código.py .ts .js .jsx .tsx .go .rs .java .c .cpp .rb .cs .kt .scala .php .swiftAST local (sin LLM)
Docs.md .txt .rstConceptos y relaciones vía Claude
PDFs.pdfCitation mining + extracción de conceptos
Imágenes.png .jpg .webp .gifClaude Vision — diagramas, capturas, cualquier idioma
Video / Audio.mp4 .mov .mp3 .wav .m4aTranscripción local con Whisper (requiere graphifyy[video])

MCP server (opcional)​

graphify puede exponer graph.json como servidor MCP para consultas estructuradas:

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

Herramientas disponibles: query_graph, get_node, get_neighbors, shortest_path.

Privacidad​

  • Código: procesado localmente vía tree-sitter AST. Ningún contenido de código sale de la máquina.
  • Docs, PDFs, imágenes: enviados a la API de Anthropic (Claude) durante la extracción semántica, usando la API key propia del desarrollador.
  • Video/Audio: transcrito localmente con Whisper. El audio nunca sale de la máquina.
  • Sin telemetría ni analytics de ningún tipo.

Troubleshooting rápido​

graphify not found tras uv tool install:

# ~/.local/bin no está en PATH de la sesión actual
export PATH="$HOME/.local/bin:$PATH"
# Para hacerlo permanente:
uv tool update-shell
source ~/.zshrc

El grafo no se actualiza tras modificar archivos:

graphify . --update   # re-procesa solo los archivos con SHA256 diferente

Quiero excluir node_modules del grafo: Crear .graphifyignore en la raíz con node_modules/ (ver sección anterior).

Referencias​