🧰 Requisitos previos e instalación
Este es el módulo más práctico de la trilha: verificas Python, instalas el uv, pon la CLI graphifyy en la terminal, registra la skill en Claude Code y deja Obsidian listo. Cada comando viene en un recuadro copiar y ejecutar, con objetivo y cómo verificar.
🐍 Comprobar Python e instalar uv
O Graphify está escrito en Python y pide la versión 3.10 o más reciente. Antes de instalar nada, comprueba qué tienes ya con python --version. Si aparece 3.10, 3.11, 3.12 o superior, ya estás listo. Luego instalamos el uv, la forma recomendada de instalar la CLI.
🔰 ¿Eres nuevo aquí? Qué es «uv»
O uv es un instalador de paquetes y herramientas de Python: rápido y moderno, creado por Astral. Piensa en él como una tienda de aplicaciones del mundo Python: pides una herramienta y la deja disponible como comando en la terminal. Es la forma más limpia de instalar Graphify sin desordenar tu Python.
Objetivo: confirma que Python sea 3.10+ e instala el uv.
# 1) checar a versão do Python (precisa ser 3.10+) python --version # 2) instalar o uv (instalador oficial da Astral) curl -LsSf https://astral.sh/uv/install.sh | sh
Cómo verificar: el primer comando imprime algo como Python 3.11.x; el instalador de uv termina con un mensaje de éxito. Cierra y vuelve a abrir la terminal para que el comando uv empezar a responder.
🔑 Conceptos clave
📦 Instalar la CLI graphifyy
El paquete en PyPI se llama graphifyy — con dos «y». Instala el binario graphify (una «y»), que es el comando que vas a ejecutar. Un detalle de escritura que evita el error más común: lo que instala tiene dos y; la que tú ejecuta tiene uno.
🔰 ¿Eres nuevo aquí? Qué es una «CLI»
Una CLI (Command Line Interface) es un programa que usas mediante comandos de texto en la terminal, en lugar de hacer clic. PyPI es el repositorio oficial de paquetes de Python: el «estante» de donde el uv/pip descarga el graphifyy.
Objetivo: dejar el comando graphify disponible en la terminal.
# recomendado (com uv) uv tool install graphifyy # alternativas, se você não usa uv pipx install graphifyy pip install graphifyy # se o comando "graphify" não for encontrado depois: uv tool update-shell
Cómo verificar: abrir una terminal nueva y escribir graphify debe responder (la verificación completa está en el tema 6). Si "comando no encontrado" persiste, ejecuta uv tool update-shell y vuelve a abrir la terminal.
✓ La forma recomendada
- ✓
uv tool install graphifyyaísla la herramienta. - ✓No se mezcla con el Python del sistema.
- ✓Actualizar y eliminar es sencillo después.
✗ Errores comunes
- ✗Escribir
graphify(un sí) en el install. - ✗Olvidar volver a abrir la terminal.
- ✗Confundir el paquete con la skill.
🔑 Conceptos clave
🔌 Registrar la skill (graphify install)
Tener la CLI no basta: para usar Graphify dentro de Claude Code necesitas registrar la skill. El comando graphify install escribe un archivo SKILL.md en el lugar donde Claude Code busca sus skills — y eso es lo que conecta el slash command /graphify.
🔰 ¿Eres nuevo aquí? Qué es una «skill» y el SKILL.md
Una skill es una habilidad que le enseñas a Claude Code: un archivo SKILL.md que describe lo que hace y cómo activarla. Cuando este archivo existe en ~/.claude/skills/, el comando /graphify aparece dentro de la sesión.
Objetivo: activar el comando /graphify en Claude Code.
# registra a skill para todos os projetos (escreve ~/.claude/skills/graphify/SKILL.md) graphify install # versão por-projeto (grava .claude/skills/graphify/ no repo atual, dá pra commitar) graphify install --project
Cómo verificar: confirma que el archivo exista con ls ~/.claude/skills/graphify/SKILL.md. En una sesión nueva de Claude Code, escribe /graphify debe mostrar la skill.
↑ La instalación tiene dos pasos distintos: instalar la CLI (tema 2) y registrar la skill (este). El SKILL.md es el puente que hace que el /graphify existir dentro de Claude Code.
🔑 Conceptos clave
🔮 Instalar y abrir Obsidian
O Obsidian es donde vivirá y se navegará el mapa generado. Descárgalo en obsidian.md, instálalo y ábrelo: es gratis y funciona en el escritorio (Windows, macOS, Linux). Aquí no hay ningún comando de terminal: solo hay que hacer clic, descargar e instalar como cualquier aplicación. Todavía no necesitas crear nada; solo déjalo listo para cuando llegue el markdown (módulo 2.4).
🔰 ¿Eres nuevo aquí? Qué son «Obsidian» y «vault»
O Obsidian es una aplicación de notas en markdown con enlaces entre páginas (PKM — gestión personal del conocimiento). Un vault es simplemente una carpeta de notas que abre; nada más que archivos .md en una carpeta. Graphify generará exactamente esos archivos.
✓ Hazlo ahora
- ✓Descargar en
obsidian.mde instalar. - ✓Abrir la app al menos una vez.
- ✓Verifica que sea la versión de escritorio, gratis.
○ Todavía no hace falta
- ○Crea un vault (Graphify lo genera después).
- ○No instales plugins ni pagues nada.
- ○Configura la sincronización en la nube.
🔑 Conceptos clave
🔑 API keys: cuándo las necesitas (y cuándo no)
Esta es la duda que más bloquea a la gente. La regla breve: al ejecutarlo mediante /graphify dentro de Claude Code, tú no necesitas una clave — la propia sesión proporciona el modelo. Solo el modo headless (terminal pura, sobre documentos) pide el ANTHROPIC_API_KEY. Y extracción de código no usa ninguna clave: está hecha con el AST, sin LLM.
🔰 ¿Eres nuevo aquí? «API key», «headless» y «AST»
Una API key es una contraseña que autoriza a un programa a llamar al modelo y cobrarlo a tu cuenta. Headless es ejecutarlo sin interfaz, directamente en la terminal. AST (árbol sintáctico) es la lectura estructural del código: Graphify usa la biblioteca tree-sitter para eso, así que el código se convierte en un grafo sin llamar a un LLM.
↑ Dos de los tres caminos no piden clave. Solo necesitas exportar la ANTHROPIC_API_KEY cuando ejecutas Graphify sin interfaz sobre documentos.
Objetivo: solo para el caso headless — proporcionar la clave en la terminal. Cambia <sua-chave> por la tuya.
# só no modo headless sobre documentos (NÃO precisa dentro do /graphify) export ANTHROPIC_API_KEY=<sua-chave>
Cómo verificar: con la variable exportada, Graphify headless deja de quejarse por la clave faltante y procesa los documentos. Dentro de Claude Code puedes saltarte todo este paso.
🔑 Conceptos clave
✅ Verificar que todo funciona
Antes de pasar al módulo 2.2, haz el sanity check: dos comandos confirman que la CLI responde y que la skill está registrada. Detectar un problema ahora cuesta segundos; descubrirlo en medio de una extracción cuesta mucho más.
Objetivo: confirma la CLI + skill antes de extraer cualquier grafo.
# a CLI responde e lista os subcomandos? graphify --help # a skill foi registrada no lugar certo? ls ~/.claude/skills/graphify/SKILL.md
Cómo verificar: el primer comando imprime la lista de subcomandos; el segundo imprime la ruta del SKILL.md (y no «archivo no encontrado»). Si ambos responden, el entorno está listo.
✅ Lista de verificación del entorno
- ✓
python --versionmuestra 3.10+. - ✓
graphify --helplista los subcomandos. - ✓
~/.claude/skills/graphify/SKILL.mdexiste. - ✓Obsidian instalado y abierto al menos una vez.
🔑 Conceptos clave
✋ Autorrecuperación (opcional, no bloquea): vas a ejecutar /graphify dentro de Claude Code. Necesitas exportar la ANTHROPIC_API_KEY?
📌 Resumen del módulo
python --version e o uv instalado.uv tool install graphifyy (dos y) deja el comando graphify en la terminal.graphify install escribe el SKILL.md y conecta el /graphify.obsidian.md y abierto, esperando el vault.Siguiente módulo
2.2 · Elegir y preparar la fuente — decidir entre código y documentos, descargar el corpus y organizar la carpeta que Graphify va a leer.