Dale un compresor de imágenes a tu agente de programación

Pídele a Claude Code o a Codex que «comprima las imágenes de esta carpeta» y mira qué pasa. Se ofrecerá a instalar sharp, escribirá un script de Node de usar y tirar, adivinará los ajustes de calidad y te devolverá una carpeta donde algunos archivos se han hecho más pequeños, uno se ha hecho más grande, y nadie te puede decir cuál.

El agente no es el problema. La compresión de imágenes es una de esas capacidades que parece trivial y no lo es: codificadores específicos por formato, heurísticas de calidad y un resultado que solo puedes juzgar midiéndolo. Ese es el trabajo de una herramienta, no de un script que el agente improvisa cada vez.

La división que hace que funcione

Hay un paso que un agente genuinamente no puede dar: iniciar sesión. pipic login abre un navegador y espera a que tú lo apruebes. Un agente ejecutándose en un sandbox tiene un HOME distinto, ningún navegador y ninguna forma de pulsar el botón.

Así que no se lo pidas. Reparte el trabajo según quién puede hacerlo de verdad:

Tú, una vez. En tu propia terminal:

npm i -g @pipic/cli
pipic login

Las credenciales quedan en ~/.config/pipic/config.json. Cualquier herramienta que se ejecute como tú en esa máquina puede usarlas a partir de ahora — incluido tu agente.

Tu agente, todas las veces siguientes. Pega esto en la conversación:

Use the `pipic` CLI to compress the images in ./assets.
It's already installed and signed in — do not install it or run
`pipic login` yourself.

  pipic ./assets --replace --json

It prints one JSON object per file:
  {"file":"a.png","status":"ok","before":102400,"after":41000,"saved":61400}
status is "ok", "skipped" or "error". "skipped" is not a failure — it
carries an `error` string explaining why (e.g. already small enough).

Exit 0 = all good, 1 = some files failed, 3 = not signed in,
4 = monthly quota exhausted.
Don't retry on exit 2 (usage error), 3 or 4 — on 3, stop and tell the
user to sign in. On exit 1, re-run only the paths whose rows had status
"error": a full re-run re-uploads every file and spends quota again.

Cada línea de ahí previene un fallo concreto, y dos de ellas previenen fallos caros.

Sin el «do not install it or run pipic login yourself», el agente lo intenta de todos modos — y pipic login espera hasta diez minutos una aprobación por navegador que no puede dar. Dentro de Codex o Claude Code eso aparece como una llamada a herramienta que tu framework acaba matando, lo que se lee como si la herramienta se hubiera colgado.

Sin la línea del código de salida 1, un agente que ve dos fallos en una ejecución de cien archivos hace lo obvio y vuelve a ejecutar el directorio entero. No hay ninguna comprobación local de «ya comprimido»: cada archivo se sube otra vez, y la asignación mensual cuenta todas las peticiones que acepta. En el plan gratuito son cien al mes, así que un reintento a ciegas puede gastarlo todo.

El resto son errores más baratos: sin una bandera de destino recibe un error de uso, y sin la nota de que skipped no es un fallo, informa de problemas donde no los hay — las filas omitidas también llevan una cadena error que explica por qué no cambió nada.

Lo que ve el agente

Una sesión ilustrativa — la forma es real, los números son inventados y los tuyos serán distintos:

> compress the images in ./assets

I'll use the pipic CLI.

  $ pipic ./assets --replace --json

  {"file":"assets/hero.png","status":"ok","before":2411233,"after":486201,"saved":1925032}
  {"file":"assets/team.jpg","status":"ok","before":880640,"after":712704,"saved":167936}
  {"file":"assets/icon.svg","status":"skipped","before":0,"after":0,"saved":0,"error":"unsupported file type"}
  {"file":"assets/logo.webp","status":"skipped","before":18944,"after":18944,"saved":0,"error":"not smaller — original kept"}

Done. Two files compressed, saving about 2.0 MB — hero.png did most of
the work, dropping from 2.4 MB to 486 KB. I left logo.webp alone because
compressing it came back larger, and skipped icon.svg since SVG isn't a
raster format.

Ese último párrafo es la parte que merece atención. El agente no está adivinando: está leyendo un contrato. saved es un recuento de bytes, no una proporción. skipped no es error. not smaller — original kept dice exactamente por qué no cambió nada.

Los scripts improvisados no producen eso. Imprimen el console.log que al agente le apeteciera escribir, y el resumen que recibes de vuelta es la impresión que el agente tiene de su propia salida.

Por qué aquí importa lo de «solo si es más pequeño»

Las imágenes ya optimizadas a veces vuelven más grandes. Un script ingenuo las sobrescribe igualmente, y tu repositorio engorda en silencio cada vez que se ejecuta.

pipic reescribe un archivo solo cuando el resultado es realmente más pequeño. Con --replace el original queda intacto; con -o se copia igualmente, de modo que el directorio de salida sigue siendo un conjunto completo. En ambos casos el archivo se reporta como skipped, no como error — así que un agente que lea la salida no te dirá que algo falló cuando no falló nada.

La bandera que no es opcional

--replace y -o <dir> son mutuamente excluyentes, y una de las dos es obligatoria. Ejecuta pipic ./assets sin ninguna y terminará con un error de uso antes de enviar una sola petición.

Esto es deliberado, y importa más cuando es un agente quien conduce. Una herramienta que sobrescribe por defecto es una herramienta que acabará sobrescribiendo algo que querías conservar, en una ejecución que no leíste del todo. Hacer explícito el destino significa que el agente tiene que declarar su intención, y tú puedes ver esa intención en el comando que te muestra.

Cuando el agente no puede ver tus credenciales

Agentes en sandbox, contenedores, CI — cualquier sitio donde ~/.config no sea tuyo. Crea un token en tu página de cuenta y exponlo como PIPIC_TOKEN en ese entorno. Tiene prioridad sobre el archivo de credenciales, así que el mismo comando funciona sin pipic login.

Fíjate en que pipic token create te envía deliberadamente a la página web en vez de emitir un token localmente. Una credencial de CLI robada no debería poder emitir credenciales nuevas.

Los códigos de salida son la interfaz

Para cualquier cosa automatizada, esta es la parte que más importa:

3 significa ejecutar pipic login — lo único que tienes que hacer tú mismo. 4 significa que te has quedado sin asignación mensual para CLI y API; no se cobra nada automáticamente, y comprimir en pipic.cc sigue siendo gratis e ilimitado en cualquier caso.

Un agente que se ramifica según estos códigos hace lo correcto sin pedirte que interpretes un muro de texto. Uno que hace coincidencia de patrones sobre cadenas de mensajes se rompe la primera vez que reformulamos algo — por eso los códigos, los valores de status y los nombres de los campos son el contrato estable, y el texto error legible por humanos no lo es.