Visual Explainer: De arte de terminal a diagramas HTML

Visual Explainer: De arte de terminal a diagramas HTML

Introducción

Muchos desarrolladores todavía imprimen la salida compleja del terminal como texto plano, pero el arte ASCII y las tablas delimitadas por tuberías se vuelven rápidamente ilegibles. Visual Explainer convierte cualquier diagrama de terminal, diferencia de código o revisión de plan en una página HTML pulida y autocontenida—con temática de modo oscuro/claro, gráficos interactivos de Mermaid y presentaciones de diapositivas responsivas.

El Problema

• El arte ASCII de terminal funciona para diagramas de flujo de una sola caja, pero se rompe con diagramas de múltiples cajas.
• Las tablas renderizadas con | y - se ven geniales en el terminal, pero colapsan o se envuelven mal al exportarse o compartirse.
• Preparar presentaciones o documentación a partir de la salida bruta de diferencias lleva tiempo y es propensa a errores.

La Solución

Visual Explainer reemplaza la salida desordenada del terminal con una página lista para el navegador que preserva la estructura, el estilo y la interactividad. Se entrega con varios comandos útiles que detectan automáticamente cuando está volcando datos complejos y renderizan la mejor representación HTML.

Funciones principales

Todos los comandos activan el mismo flujo de trabajo subyacente: la habilidad analiza tu solicitud, elige la plantilla de referencia adecuada, obtiene los datos requeridos del directorio references/ y escribe un archivo HTML en ~/.agent/diagrams/. La página se abre automáticamente en tu navegador predeterminado.

Instalación

Si ya eres usuario de pi, la instalación es una línea:

pi install https://github.com/nicobailon/visual-explainer

Para usuarios de Claude Code u otros agentes, simplemente clona en el directorio de habilidades:

git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer

No se requiere paso de compilación; la herramienta solo necesita un navegador y, opcionalmente, el binario surf-cli para la generación de imágenes.

Uso de la Habilidad

Una rápida demostración:

generate-web-diagram
draw a diagram of our authentication flow

La habilidad renderizará un diagrama Mermaid, aplicará la temática clara/oscura y abrirá el archivo ~/.agent/diagrams/auth-flow.html en tu navegador.

Para revisar una solicitud de extracción reciente:

diff-review #42

Por defecto, /diff-review compara la rama actual con main. También puedes pasar referencias arbitrarias:

diff-review abc123            # single commit
diff-review main..HEAD         # all staged commits
diff-review main..dev-feature # entire branch

Para crear una presentación a partir de tu revisión de diferencias, agrega la bandera --slides:

diff-review --slides

Personalización

• Tema y diseño – edita los archivos CSS en references/css-patterns.md para elegir paletas o ajustar animaciones.
• Plantilla – reemplaza cualquiera de las cuatro plantillas en templates/ (por ejemplo, architecture.html, data-table.html) o escribe la tuya.
• Directorio de salida y navegador – modifica las variables en SKILL.md para cambiar dónde se escriben los archivos o cómo se lanzan.

Debido a que la habilidad recarga las plantillas en cada ejecución, puedes iterar rápidamente sin reiniciar el agente.

Limitaciones y compensaciones

• Sin renderizado inline en el terminal – los resultados se abren en un navegador; no puedes verlos dentro del terminal.
• El cambio de tema requiere refrescar la página – los SVG de Mermaid no se adaptan automáticamente a los cambios de tema del sistema.
• Calidad dependiente del modelo – la salida visual depende de la capacidad del LLM subyacente para producir código Mermaid o CSS.

A pesar de estas advertencias, Visual Explainer reduce significativamente la fricción al convertir texto sin procesar en arte visual significativo.

Comunidad y Soporte

El repositorio se mantiene activamente y cuenta con actualizaciones regulares, como las guarderas anti-slop (v0.3.0). Se aceptan issues, peticiones de función y pull requests en GitHub. Las 3.3 k estrellas reflejan una comunidad de desarrolladores en crecimiento que utilizan la herramienta para todo, desde diagramas ad‑hoc hasta documentación formal.

Conclusión

Visual Explainer es una herramienta ligera de código abierto para desarrolladores que transforma la salida ruidosa del terminal en páginas HTML pulidas o presentaciones de diapositivas. Con un puñado de comandos slash, puedes generar automáticamente diagramas de arquitectura, revisiones de diferencias, auditorías de planes o presentaciones, todo mientras mantienes tu flujo de trabajo dentro del entorno del agente. Pruébalo y recobra la claridad visual que mereces de tu base de código.