Tu captura del portapapeles como entrada de Hermes: el comando hermes clipboard image


Hiciste una captura de pantalla y quieres hacerle una sola pregunta: «¿de qué etapa viene este error?». En una terminal lo natural es Ctrl+V. Ese gesto no existe dentro de un script, porque los scripts ejecutan comandos y no pulsan teclas. Así que escribiste tres líneas de shell alrededor de xclip, descubriste que en Windows no hacen nada, necesitaste otro juego distinto en macOS y acabaste guardando el archivo a mano.

El cambio fusionado el 6 de noviembre traslada eso a Hermes. hermes clipboard image escribe en un archivo la imagen del portapapeles de la máquina: imprime la ruta si todo va bien y, con --json, devuelve una respuesta JSON estable y un conjunto de códigos de salida diferenciados. Lee solo el portapapeles de la máquina donde se ejecuta: sin gateway, sin almacén de sesiones, sin archivo de perfil.

La vieja forma: ejecutar el script privado de la TUI

Hermes lleva tiempo pudiendo pegar imágenes en la terminal, y la implementación en hermes_cli/clipboard.py hace bastante trabajo específico de plataforma. Pero el único punto de entrada expuesto era un script interno: ui-tui/scripts/clipboard_image.py. Un cliente de terceros que quisiera imágenes del portapapeles tenía que apuntar PYTHONPATH al árbol de fuentes de Hermes y llamar a ese script.

Funcionaba, y era frágil en tres sitios a la vez: la ruta podía moverse, los argumentos podían cambiar y hasta su respuesta true/false podía cambiar. El problema de fondo era «¿dónde está el árbol de fuentes?»: ¿por qué iba un cliente a saber dónde instaló el usuario Hermes?

El comando nuevo envuelve el mismo extractor (hermes_cli.clipboard.save_clipboard_image) en un comando documentado con códigos de salida y JSON.

Un comando, un archivo en disco

hermes clipboard image --out /tmp/shot.png

Si va bien, imprime la ruta. --out se crea o se sobrescribe, y su directorio se crea si hace falta. En scripts normalmente querrás la forma JSON:

hermes clipboard image --out /tmp/shot.png --json
{"ok": true, "path": "/tmp/shot.png", "mime": "image/png", "bytes": 248193}

mime no se adivina por la extensión: se lee de los magic bytes del archivo, así que se identifican PNG, JPEG, GIF, BMP, TIFF y WebP. Lo normal es que la salida sea siempre PNG, porque el extractor convierte; la única excepción es cuando copiaste un archivo de imagen (un arrastre de archivo de Windows/WSL), que se copia byte a byte y puede ser un jpg o un webp.

Cada desenlace tiene su código de salida

En automatización, el peor modo de fallo no es fallar: es fallar sin decir por qué. Este comando separa los desenlaces:

Situación reason en el JSON Código de salida
Se escribió una imagen ninguno, ok: true 0
El portapapeles no tiene imagen (solo texto) no_image 1
No hay instalada ninguna herramienta de portapapeles utilizable no_tool, más las herramientas que buscó 3
No se puede escribir en --out write_failed 4
Argumentos incorrectos sin JSON, error de uso de argparse 2

Mantener no_image separado de no_tool importa: uno significa que no hiciste una captura, el otro que esta máquina no puede leer un portapapeles en absoluto. Necesitan arreglos distintos. Ejecútalo en un servidor sin sesión gráfica y recibes no_tool, no un fallo vago.

Por qué esto merece su propio comando

Porque zanja una cuestión de ingeniería concreta: leer un portapapeles tiene que ser local.

Piensa en cómo se despliegan los gateways. El gateway de Hermes de un usuario puede correr en una máquina remota o en un contenedor, mientras que la persona y su portapapeles están en un portátil. Si «leer el portapapeles» fuera una RPC del gateway, leería el portapapeles de la máquina remota: inútil, normalmente vacío. Por eso el comando es deliberadamente local al dispositivo: sin conexión al gateway, sin almacén de sesiones, sin archivo de perfil, estrictamente «escribe la imagen del portapapeles de esta máquina en esta ruta».

La mitad de escritura también es cuidadosa. Extrae a un directorio temporal privado junto al destino y renombra el archivo terminado sobre --out, de modo que ante cualquier fallo el archivo existente queda exactamente como estaba, sin imágenes a medias. Sobrescribir un archivo existente conserva sus bits de permisos, así que un archivo temporal 0600 no los amplía en silencio.

Enchufarlo a Hermes

Una vez tienes una ruta, el resto es rutina. hermes chat ya acepta --image, así que una captura puede viajar junto a una pregunta:

hermes clipboard image --out /tmp/shot.png --json > /tmp/shot.json
hermes chat -q "Which stage is this error from? One conclusion and one command to check it." --image /tmp/shot.png --oneshot

Saltarse el archivo intermedio es fácil con jq:

SHOT=$(hermes clipboard image --out /tmp/shot.png --json | jq -r .path) && hermes chat -q "What is misaligned in this UI?" --image "$SHOT" --oneshot

Si quitas --oneshot, hermes chat se queda interactivo con la imagen adjunta a esa pregunta, que es el bucle del día a día: captura, pregunta y sigue hablando.

Los detalles de plataforma que vas a encontrarte de verdad

  • macOS: primero pngpaste (rápido, más formatos); después osascript como alternativa siempre presente.
  • Windows: primero powershell; después pwsh.
  • Linux: en WSL prueba powershell.exe primero; en Wayland, wl-paste; en X11, xclip. Un sondeo de WSL fallido da paso al siguiente, porque WSLg puede tener igualmente un wl-paste o un xclip que funcionen.
  • Modo contenedor de NixOS: cada subcomando de hermes se ejecuta dentro del contenedor gestionado, este incluido, así que no puede ver el portapapeles del host y --out es una ruta dentro del contenedor. Eso es un límite del modo contenedor, no un bug.

Una cosa que esto no hace: dibujar la imagen. Imágenes en línea en la CLI y la TUI cubre cómo aparecen los adjuntos y las imágenes producidas por herramientas en el transcript. Este comando va en la otra dirección, la de cómo llega una imagen del portapapeles al disco, y lo habitual es usar los dos juntos.

¿Puedes usarlo hoy?

El comando está en main (6 de noviembre, PR #150285) y no está en la etiqueta v0.23.0. Comprobarlo es trivial: si hermes clipboard --help imprime algo, tu build lo tiene; «invalid choice» significa que no. Está documentado en la sección hermes clipboard de la referencia de CLI, así que en cuanto actualices la página coincidirá con lo que tienes instalado.

Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.

Y si quieres saber si esta máquina puede leer un portapapeles, el comando lo responde solo: cuando no hay imagen disponible distingue «no hay imagen» de «no hay herramienta», y en el segundo caso lista los nombres de herramienta que buscó, que viene a ser tu inventario de instalación.

La versión corta

hermes clipboard image es un comando pequeño que arregla una frontera de interfaz: convierte «leer el portapapeles local» de detalle de implementación de la TUI en un punto de entrada documentado con JSON y códigos de salida, y deja escrita la regla de que es local al dispositivo. Para quien escriba scripts contra él, lo más útil no es el comando sino los cuatro códigos de salida: un case separa ahora «no hay captura», «no hay herramienta», «no se puede escribir» y «hecho», en lugar de hacer grep sobre el texto de error.