Saltar al contenido principal

graphify

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.

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.

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

# Git hooks — rebuild tras cada commit y branch switch
graphify hook install

# 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​