Le pides a tu copiloto IA que capture una ventana. El copiloto escribe peek app "Xcode". La herramienta busca una ventana cuyo dueño se llame exactamente Xcode. No la encuentra, porque el proceso se llama Xcode-16.3. La herramienta imprime Error: application not found. El copiloto, que es un LLM y tiene la memoria emocional de un pez dorado, intenta peek app "Xcode-16.3". Funciona. Pero ha gastado un turno de conversación, tokens de entrada, tokens de salida, y la paciencia de quien paga la factura.
Ahora imagina otra versión: el copiloto escribe peek app xcode. La herramienta normaliza el nombre, busca coincidencia parcial, encuentra Xcode-16.3, captura la ventana, y devuelve /tmp/peek/Xcode-16.3-1712524800.png. Un token de salida. Cero turnos desperdiciados.
La diferencia entre esas dos versiones no es un bug. Es una decisión de diseño.
El usuario que no lee tu --help
A principios de 2025, Mathias Biilmann (CEO de Netlify) acuñó el término Agent Experience — AX — para describir la experiencia que tienen los agentes IA cuando interactúan con un producto. Igual que UX es para humanos y DX para desarrolladores, AX es para LLMs.
El concepto suena abstracto hasta que lo aplicas a algo concreto. Una CLI, por ejemplo. Las CLIs llevan cuarenta años diseñadas para humanos: mensajes descriptivos, colores, barras de progreso, páginas de --help. Todo eso es ruido para un LLM. Un LLM no lee la ayuda — infiere los flags por el nombre del comando. No aprecia el color verde en «Success» — procesa texto plano. No mira una barra de progreso — espera a que el proceso termine.
El diseño tradicional de CLIs optimiza para que un humano entienda qué está pasando. AX optimiza para que un agente pueda actuar con el mínimo de tokens y turnos.
Cinco principios, tres herramientas
En los últimos meses he construido tres CLIs con la misma filosofía: peek (captura de ventanas en macOS), lql (gestión de issues en Linear), y driftkit (auditoría de harness para agentes). Las tres están diseñadas para que un LLM las use sin manual. De esa experiencia salen cinco principios.
1. El output es un contrato, no una conversación
Una CLI tradicional para capturar una ventana te dice algo como:
✅ Screenshot saved successfully!
File: /tmp/peek/Xcode-1712524800.png
Size: 1920x1080
Format: PNG
Bonito. Informativo. Y completamente inútil para un LLM que necesita el path para pasárselo a otra herramienta. Tiene que parsear esa salida, ignorar el emoji, encontrar la línea que empieza por File:, extraer el path. Tokens desperdiciados.
peek imprime una cosa:
/tmp/peek/Xcode-1712524800.png
Un path. Nada más. El LLM lo lee, lo usa, sigue adelante. El output de stdout es un contrato: siempre un path, siempre parseable, siempre estable. Si cambias el formato, rompes el contrato y rompes a todos los agentes que dependen de ti.
Es decir: tu stdout no es para decorar. Es una API.
2. Tolera las alucinaciones — no las castigues
Los LLMs alucinan nombres. Es un hecho de la naturaleza, como la gravedad o que el WiFi falla cuando tienes prisa. Si tu herramienta exige nombres exactos, estás pidiendo precisión a una máquina probabilística. No va a funcionar.
peek tiene tres fases de búsqueda para encontrar una app:
- Coincidencia exacta (case-insensitive):
xcode→Xcode - Coincidencia normalizada (sin espacios ni guiones):
thinklocal→ThinkLocal - Coincidencia parcial:
xcode→Xcode-16.3
El LLM no necesita saber cómo se llama exactamente el proceso. Dice un nombre aproximado y la herramienta se encarga del resto. Lo mismo hace lql con nombres de proyectos y teams — resuelve tokamak a Tokamak sin necesitar un UUID.
El principio es simple: si el humano que supervisa al agente puede deducir qué quiso decir, la herramienta también debería poder.
3. Los errores deben decir qué hacer, no qué pasó
Compara estos dos errores:
Error: application not found in window list
Error: "Xcode" is not running. Start it with: open -a "Xcode"
El primero describe el problema. El segundo resuelve el problema. Un humano lee el primero y piensa «ah, no está abierta». Un LLM lee el primero y… intenta otra vez con otro nombre, o busca en Google, o se inventa un flag --force. Con el segundo, el LLM ejecuta open -a "Xcode", espera, vuelve a intentar. Problema resuelto en un turno.
Otro ejemplo. Cuando peek no sabe a qué app te refieres porque el nombre coincide con varias:
Error: "code" matches multiple apps:
Visual Studio Code
Xcode
Be more specific.
El LLM recibe la lista de candidatos, elige el correcto, vuelve a intentar. No tiene que adivinar. No tiene que buscar. La herramienta le da toda la información que necesita para actuar.
La regla: cada mensaje de error debe contener un comando ejecutable o una lista de opciones válidas. Si el agente tiene que pensar después de leer tu error, tu error no es suficientemente bueno.
4. Zero flags obligatorios
Una CLI tradicional para capturar ventanas podría requerir:
capture --app "Xcode" --format png --output /tmp/screenshot.png --window-id 12345
Cuatro flags obligatorios. Un LLM tiene que recordar (o adivinar) los cuatro. Cada flag que falta es un turno de error-corrección.
peek solo necesita:
peek app Xcode
El formato siempre es PNG. El output tiene un default sensato (/tmp/peek/<app>-<timestamp>.png). El window ID se resuelve automáticamente buscando la ventana más grande. Si quieres personalizar algo, puedes — --output, --panel. Pero no tienes que hacerlo.
lql sigue la misma filosofía: lql create "El login falla con OAuth" clasifica automáticamente el tipo, la prioridad, el team, y el proyecto a partir del directorio de trabajo. Zero flags.
El principio: los defaults sensatos no son comodidad — son resiliencia contra alucinaciones. Cuantos menos parámetros necesite el agente, menos cosas puede inventar.
5. La captura silenciosa — no interrumpas al agente
Este es específico de peek pero ilustra un principio general: la herramienta no debe interferir con el flujo del agente.
En macOS, capturar una ventana con screencapture requiere traerla al frente. Eso roba el foco del terminal donde corre el agente. El agente se queda sin su ventana activa. Es como quitarle el destornillador a un electricista en mitad de una reparación.
peek usa ScreenCaptureKit — el framework de Apple para captura de pantalla — con un filtro que selecciona una ventana individual por su ID (SCContentFilter(desktopIndependentWindow:)). La ventana se captura tal cual, sin activarla, sin moverla, sin tocar el foco. El terminal sigue siendo la ventana activa.
El principio general: una herramienta diseñada para agentes no debe tener efectos secundarios visibles. Nada de abrir ventanas, nada de diálogos de confirmación, nada de «Press Enter to continue». El agente opera en background — tu herramienta también debería.
Antes y después
Para verlo en perspectiva, aquí va la comparación entre diseño tradicional y diseño AX para las mismas operaciones:
| Operación | CLI tradicional | CLI AX-first |
|---|---|---|
| Output de captura | ✅ Saved to /tmp/... + metadatos |
/tmp/peek/App-123.png |
| App no encontrada | Error: not found |
Error: "X" not running. Start: open -a "X" |
| Nombre inexacto | Error | Fuzzy match automático |
| Flags necesarios | 3-4 obligatorios | 0 (solo el argumento posicional) |
| Crear issue | --team T --type bug --priority 2 --project P |
"El login falla" (auto-clasifica) |
| Robar foco | Sí (screencapture) | No (ScreenCaptureKit) |
La columna de la derecha no es más cómoda solo para LLMs. Es más cómoda para todo el mundo. Eso es lo interesante: diseñar para agentes suele mejorar la experiencia para humanos también.
Cómo aplicar esto hoy
No necesitas reescribir tus herramientas desde cero. Tres cambios que puedes hacer esta semana:
-
Revisa tu
stdout. Si tu herramienta imprime algo que no es directamente utilizable como input para otra herramienta, tienes decoración, no output. Añade un--quieto--jsonque devuelva solo datos. Mejor aún: haz que ese sea el default. -
Audita tus mensajes de error. Lee cada
Error:de tu código y pregúntate: «¿Un agente podría resolver esto sin más contexto?» Si la respuesta es no, añade un comando sugerido o una lista de opciones válidas. -
Cuenta tus flags obligatorios. Cada flag obligatorio es un punto de fallo para un agente. ¿Puede tener un default sensato? ¿Puede inferirse del contexto? Un directorio de trabajo, un fichero de configuración, una convención de nombres — cualquier cosa que evite que el agente tenga que adivinar.
Lo que no funciona (todavía)
Estos principios no son una bala de plata. El fuzzy matching de peek resuelve bien los casos comunes, pero falla cuando hay dos apps con nombres casi idénticos — Code contra Xcode, por ejemplo. En esos casos, la herramienta devuelve una lista de candidatos y el agente tiene que elegir, lo cual sigue costando un turno extra.
La inferencia automática de lql (auto-clasificar tipo, prioridad y team a partir del texto del issue) acierta en el ~70% de los casos. En el 30% restante, el agente tiene que corregir. Es mejor que obligar a pasar cuatro flags, pero no es magia.
Y el diseño «output mínimo por defecto» tiene un coste real: los humanos que usan peek directamente desde el terminal echan de menos la confirmación visual. Un path crudo no genera la misma confianza que un Saved to... con metadatos. El flag --verbose existe por algo.
Pruébalo
peek está disponible en Homebrew:
brew tap frr149/tap
brew install peek
peek app Safari
El código está en github.com/frr149/peek. Si construyes CLIs para agentes (o quieres adaptar una existente), abre un issue — me interesa ver cómo aplicas estos principios a tu caso.
El futuro es bilingüe
No estoy diciendo que abandones a tus usuarios humanos. Estoy diciendo que tus herramientas van a tener dos tipos de usuario: humanos que quieren output legible y agentes que quieren output parseable. Y que diseñar primero para el agente y luego añadir la capa humana es más fácil que al revés.
Un path en stdout es perfecto para un agente y aceptable para un humano. Un mensaje con emojis y colores es perfecto para un humano e infernal para un agente.
La dirección del camino está clara. Las CLIs del futuro hablan dos idiomas. Empieza por el que no necesita decoración.
Read this article in English.
