En resumen: agent-desktop es una herramienta de línea de comandos de código abierto de Vercel Labs (Apache-2.0) que permite a los agentes de programación «ver» y usar apps nativas de escritorio. Lee el árbol de accesibilidad del sistema operativo y asigna una ref a cada botón y campo de texto. El agente actúa sobre una ref y vuelve a leer la interfaz para confirmar el resultado, en lugar de adivinar coordenadas de píxeles en una captura.
- No es un agente y no lleva ningún modelo dentro. Cada comando imprime un objeto JSON y termina. El bucle de observar, actuar y verificar corre en tu Claude Code, Codex o Cursor, así que sirve para los tres.
- Se instala con una línea:
npm install -g agent-desktop, y luegonpx skills addañade el skill oficial al proyecto, donde Claude Code, Codex y Cursor lo leen. - Lo probamos de principio a fin: con la API Key de nuestro sitio, Claude Code tardó unos 28,6 segundos y Codex unos 35 segundos en pulsar los botones de una calculadora de escritorio y leer el resultado. Las dos respuestas fueron correctas.
- Dos trampas que conviene conocer: algunas apps (como la calculadora de GNOME en GTK4 que probamos) no exponen la posición de sus controles, y los clics por ref fallan con
bounds unavailable; y en el sandbox por defecto de Codex en Linux, agent-desktop no llega al D-Bus del escritorio y devuelveOperation not permitted. Las soluciones están en la sección de errores.
Crear API Key y conectar agent-desktop a Claude Code, Codex o Cursor →
Qué es agent-desktop y por qué se habla tanto de él
La mañana del 31 de octubre (hora de Pekín), Chris Tate, de Vercel, presentó agent-desktop en X como «agent-browser, for your whole computer»: computer use para cualquier agente de programación, en macOS, Windows y Linux, en segundo plano sin quitarte el ratón y con varios agentes a la vez. La tarde del 1 de noviembre la publicación sumaba unas 640.000 visualizaciones, más de 7.700 me gusta y más de 8.700 guardados. El autor, Lahfir, resumió los puntos clave en su publicación de lanzamiento: pruebas end-to-end de apps de escritorio con agentes, lectura mediante el árbol de accesibilidad, explorar solo una parte de la ventana para ahorrar tokens y muchos agentes sobre una misma app.
El repositorio de GitHub tiene unas 5.000 estrellas, publicó la v1.0.2 el 30 de octubre y estrenó al mismo tiempo su documentación oficial. Lo esencial:
| Aspecto | Detalle |
|---|---|
| Forma | Una CLI en Rust y una biblioteca C; 60 nombres de comando, cada uno imprime un objeto JSON |
| Funcionamiento | AX API en macOS, UI Automation en Windows, AT-SPI en Linux; lee el árbol de controles que expone la app |
| Requisitos | macOS 13+; Windows 10 1809+ o Server 2019+; Ubuntu 24.04+ (glibc 2.35 como mínimo); x64 y ARM64 |
| Lo que no hace | No incluye modelo, no automatiza la web (para páginas, agent-browser) y no ve interfaces sin árbol de accesibilidad |
En la comunidad: según @decildmc, cambió cua-driver por agent-desktop en su Mac porque solo envía al modelo lo que se puede pulsar y los clics activan el botón directamente sin mover el ratón. Según @o_kwasniewski, montó en un fin de semana una demo de pruebas e2e para apps nativas sobre él. Según un resumen de tendencias de X, una demo de 52 pasos bajó de unos 198k a unos 31k tokens usando el esqueleto y la exploración por regiones.
Frente al computer use por capturas, sus ventajas son refs estables y reintentos seguros (cada error indica si la entrada llegó a la app). Su límite: solo funciona con apps que exponen información de accesibilidad.
Paso 1: instalar agent-desktop y revisar permisos
npm install -g agent-desktop
agent-desktop version
agent-desktop status
Si status devuelve un supported_surfaces no vacío y accessibility en granted, ya está listo. Esta fue la salida normal en Linux:
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
"platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}
Permisos por sistema:
- macOS: concede Accesibilidad a la app que lanza agent-desktop (Terminal, iTerm2, VS Code o la app anfitriona del agente).
agent-desktop permissions --guideabre la página correcta de Ajustes del Sistema. Las capturas necesitan además Grabación de pantalla. Consulta la documentación de macOS. - Windows: no hace falta conceder nada, pero las apps que se ejecutan como administrador solo se pueden leer, no manejar, salvo desde una terminal con el mismo nivel de elevación. El binario no está firmado y SmartScreen o el antivirus pueden bloquearlo. Consulta la documentación de Windows.
- Linux: ejecútalo dentro de la sesión gráfica del usuario con
at-spi2-coreinstalado. Consulta la documentación de Linux.
Paso 2: conectar agent-desktop a Claude Code, Codex y Cursor
agent-desktop trae sus propias guías ajustadas a su versión (agent-desktop skills get desktop y skills get platform). Conectarlo consiste en que el agente lea esas dos antes de usarlo por primera vez. Hay dos formas; basta con una.
Opción A: instalar el skill oficial con skills (recomendado)
# in your project root
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
# non-interactive, pick the clients explicitly
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop \
-a claude-code -a codex -a cursor -y
Al ejecutarlo en un proyecto, el instalador mostró:
✓ ./.agents/skills/agent-desktop
universal: Codex, Cursor
symlinked: Claude Code
Es decir, el skill queda en .agents/skills/agent-desktop del proyecto. Codex y Cursor leen esa carpeta directamente, y Claude Code lee los mismos archivos a través del enlace simbólico .claude/skills/agent-desktop. Con -g se instala a nivel de usuario para todos los proyectos. Lo básico de los skills está en Cómo usar skills en agentes de IA.
El instalador también muestra resultados de análisis de seguridad (esta vez Gen: Safe, Socket: 0 alerts, Snyk: Med Risk) y recuerda que los skills se ejecutan con todos los permisos del agente. Lee SKILL.md antes de instalarlo.
Opción B: añadir dos líneas a AGENTS.md / CLAUDE.md
Si prefieres no instalar el skill, pon el texto oficial en el AGENTS.md del proyecto (lo leen Codex y Cursor) y en CLAUDE.md para Claude Code:
Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
Para compartir un solo archivo de instrucciones entre Claude Code y Codex, consulta Un solo AGENTS.md para Claude Code y Codex.
Paso 3: configurar el cliente con nuestra API Key
- Regístrate en aicodewith.ai, entra en la gestión de claves, crea una Key y copia la cadena completa.
- Configura tu cliente.
Claude Code:
export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="TU_API_KEY"
Para dejarlo fijo o configurarlo en Windows, consulta Cómo conectar Claude Code a una API de terceros. La misma guía explica cómo elegir modelos en Cursor.
Codex: en el archivo global ~/.codex/config.toml:
# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "TU_API_KEY"
El resto de campos está en Guía de config.toml de Codex.
Cursor: con el modelo configurado según la guía anterior, el agente de Cursor lee .agents/skills y AGENTS.md del proyecto igual que Codex.
Paso 4: dejar que el agente observe, actúe y verifique
El bucle tiene tres pasos: snapshot devuelve el árbol de controles con sus refs, actúas sobre una ref con click, type, etc., y vuelves a hacer snapshot o get para confirmar. Cada ref lleva el id del snapshot que la generó (por ejemplo @s2jrj9msmdpdlw:e46), así que haz un snapshot nuevo cuando cambie la interfaz.
agent-desktop list-apps # app names agent-desktop can see
agent-desktop snapshot --app galculator -i --compact # interactive elements, each with a ref
agent-desktop click @s2jrj9msmdpdlw:e46 # act on a ref from that snapshot
agent-desktop snapshot --app galculator -i --compact # observe again to verify
# dense apps (Electron, IDEs): map a skeleton first, then drill into one region
agent-desktop snapshot --app "Visual Studio Code" --skeleton -i --compact
agent-desktop snapshot --root @sXXXX:e1 -i --compact
Para apps densas (clientes Electron, IDE), la documentación aconseja primero un --skeleton poco profundo y luego --root para abrir solo la región que necesitas, de modo que el uso de tokens dependa de la zona en la que trabajas. Consulta Esqueleto y exploración por regiones.
Normalmente no escribes estos comandos tú. Basta con decirle al agente: «usa agent-desktop para abrir la app X, haz Y y confirma el resultado».
Prueba: Claude Code y Codex manejan una calculadora con nuestra API Key
Fecha de la prueba: 1 de noviembre de 2026. Entorno: Linux (Debian 13, X11 con el gestor de ventanas xfwm4), agent-desktop 1.0.2, app objetivo galculator (GTK3). La tarea: pulsar solo botones, sin escribir la fórmula, y leer el resultado desde la app. Los dos clientes tenían únicamente las líneas de la opción B en CLAUDE.md / AGENTS.md.
Claude Code 2.1.316
claude -p "Use agent-desktop to operate the galculator app that is already open: calculate 12 × 34 by clicking its buttons, then read the result back (Edit > Copy Display Value, then agent-desktop clipboard-get). Reply with RESULT=<number>." \
--model claude-sonnet-4-6 \
--allowedTools "Bash(agent-desktop:*)"
| Aspecto | Resultado |
|---|---|
| Operación | 12 × 34 |
| Respuesta | RESULT=408 (correcta) |
| Tiempo | unos 28,6 segundos, 11 turnos |
| Comandos de agent-desktop | 15, uno falló y el agente lo corrigió |
Comandos que ejecutó realmente Claude Code (extracto):
agent-desktop skills get desktop
agent-desktop skills get platform
agent-desktop snapshot --app "galculator" -i --compact
agent-desktop click @s2jrj9msmdpdlw:e40 # AC
agent-desktop click @s2jrj9msmdpdlw:e46 # 1 (then 2, *, 3, 4, =)
agent-desktop click @s2jrj9msmdpdlw:e6 # "Copy Display Value" -> ACTION_FAILED, menu not open
agent-desktop click @s2jrj9msmdpdlw:e4 # open the Edit menu
agent-desktop snapshot --surface menu --app "galculator" -i --compact
agent-desktop click @s1muxufwf6hxgz:e3 # Copy Display Value
agent-desktop clipboard-get # -> 408
Leyó las dos guías como pedía CLAUDE.md, tomó un snapshot y pulsó los botones por ref. Su primer clic en «Copy Display Value» falló porque el menú aún no estaba abierto, con este error. Después abrió el menú Edit, tomó un snapshot nuevo con --surface menu, volvió a pulsar y leyó 408 con clipboard-get:
{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
"message":"Target is not actionable: visible (live offscreen state is true)"}}
Un click tardaba unos 0,07 segundos en esta máquina; casi todo el tiempo se fue en lo que pensaba el modelo.
Codex 0.164.0
codex exec "Use agent-desktop to operate the galculator app that is already open: calculate 56 × 78 by clicking its buttons, then read the result back from the app. Reply with RESULT=<number>."
| Aspecto | Resultado |
|---|---|
| Operación | 56 × 78 |
| Respuesta | RESULT=4368 (correcta) |
| Tiempo | unos 35 segundos |
| Comandos de agent-desktop | 24, dos fallaron |
Los dos fallos fueron agent-desktop: command not found al principio. Para la prueba habíamos instalado agent-desktop en la carpeta del proyecto y no de forma global, y Codex ejecuta los comandos en una shell de inicio de sesión cuyo PATH no lo incluía. Codex encontró solo la ruta del ejecutable y terminó la tarea. Para usarlo de verdad, instálalo de forma global con npm install -g.
Una prueba que no salió: la calculadora de GNOME en GTK4
Primero probamos la calculadora de GNOME (GTK4). agent-desktop listaba todos los botones, pero cada clic fallaba con bounds unavailable: en nuestro entorno X11 esta app no expone la posición de sus controles, la comprobación previa de visibilidad falla y agent-desktop se niega a pulsar (delivery: not_delivered, así que no hubo clics por error). Claude Code empezó entonces a adivinar coordenadas con mouse-click --headed; a los 10 minutos seguía sin terminar y lo detuvimos. La entrada de teclado con agent-desktop press sí funcionaba en esa app.
Lección: si un agente choca una y otra vez con bounds unavailable, no lo dejes adivinar coordenadas. Pasa al teclado o a otra app. Puedes ponerlo en el prompt: «si los clics fallan, envía teclas con press».
Crear API Key y probarlo en tu propio equipo →
Errores frecuentes y soluciones
Los errores de agent-desktop son JSON. Decide según error.code y disposition.retry: safe significa que la entrada no llegó y se puede reintentar; con unsafe o unknown, observa primero para no repetir una acción. La lista completa está en la página oficial de errores. Estos son los que encontramos.
status muestra accessibility denied y supported_surfaces vacío (Linux)
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"denied",
"suggestion":"AT-SPI is not installed or not visible to this process. Install the at-spi2-core package, then retry."}},
"supported_surfaces":[]}}
Falta AT-SPI o el proceso no lo ve. Instala at-spi2-core y asegúrate de ejecutar dentro de la sesión gráfica (una shell SSH sin variables de sesión no ve ninguna app). Las apps de Flatpak o snap necesitan la interfaz correspondiente.
list-apps dice que no se pudo probar el tipo de ventana nativa
{"ok":false,"command":"list-apps","error":{"code":"ACTION_NOT_SUPPORTED",
"message":"The native window type of accessibility frame owned by pid 3857714 could not be proven"}}
Nos pasó en una pantalla virtual sin gestor de ventanas. En cuanto arrancamos uno (xfwm4), list-apps funcionó. En un escritorio normal no debería ocurrir.
click agota el tiempo con bounds unavailable
{"ok":false,"command":"click","error":{"code":"TIMEOUT",
"message":"Target did not become actionable within the wait budget",
"details":{"kind":"actionability_timeout","last_report":{"report":{"checks":[
{"check":"visible","reason":"bounds unavailable","status":"unknown"}]}}},
"disposition":{"delivery":"not_delivered","retry":"safe"}}}
La app no expone la posición de sus controles y --headed no ayuda. Usa press para el teclado o una app con mejor soporte de accesibilidad. Mira la prueba con GTK4 de más arriba.
click falla con ACTION_FAILED: visible (live offscreen state is true)
El objetivo no está visible en ese momento, por ejemplo un elemento de un menú cerrado. Abre primero el menú y toma una ref nueva con snapshot --surface menu.
INTERNAL con Operation not permitted dentro de Codex
{"ok":false,"command":"list-apps","error":{"code":"INTERNAL",
"message":"The accessibility bus returned an unexpected error",
"platform_detail":"Failed to connect to address `unix:path=/tmp/dbus-...`: Operation not permitted (os error 1)"}}
Lo vimos en Linux con codex exec -s workspace-write: el sandbox de Codex bloquea la conexión al D-Bus del escritorio y agent-desktop no llega al bus de accesibilidad. Haz que los comandos de agent-desktop se ejecuten fuera del sandbox: aprueba el comando cuando Codex lo pida en modo interactivo, o usa --dangerously-bypass-approvals-and-sandbox solo en una máquina de pruebas o VM dedicada. Nuestra prueba usó esta segunda opción en un escritorio de pruebas aparte.
command not found
/bin/bash: line 1: agent-desktop: command not found
agent-desktop no está en el PATH que usa el agente. Instálalo de forma global con npm install -g agent-desktop o escribe la ruta completa en AGENTS.md.
Las refs no funcionan en Windows PowerShell
PowerShell interpreta un @xxx suelto como el operador de splatting, así que pon las refs entre comillas simples:
agent-desktop click '@s8f3k2p9:e8'
Notas de seguridad
- Los snapshots contienen lo que hay en tu pantalla. Según @mikawuf, incluyen lo que se muestra, así que no los pongas en registros públicos. Cierra gestores de contraseñas y apps de chat antes de dejar trabajar a un agente.
- Concede solo lo necesario. En Claude Code,
--allowedTools "Bash(agent-desktop:*)"permite solo agent-desktop; desactiva el sandbox de Codex únicamente en un entorno aislado. - Los skills y AGENTS.md son instrucciones que tu agente seguirá, así que usa fuentes de confianza. Consulta Riesgos de secuestro de AGENTS.md.
- Para la nube: según el autor Lahfir, agent-desktop también puede ejecutarse en un escritorio Linux iniciado dentro de un Vercel Sandbox.
Preguntas frecuentes
En qué se diferencian agent-desktop y agent-browser
agent-browser maneja páginas web y agent-desktop apps nativas de escritorio. Para el contenido web de una app Chromium o Electron, agent-desktop puede abrir un puerto DevTools con launch "App" --cdp y pasárselo a agent-browser.
Necesito un modelo especial de computer use
No. agent-desktop solo produce texto (JSON), así que cualquier agente de programación que pueda ejecutar comandos de shell puede usarlo. En nuestras pruebas usamos Claude Sonnet 4.6 y GPT-6.1 Sol.
Sirve para pruebas e2e de mi propia app de escritorio
Sí, es uno de los usos principales que citan los autores. Para comprobar si un cambio de código funciona en la app real, consulta también Manejar una app real con un skill de verificación.
