En bref : agent-desktop est un outil en ligne de commande open source de Vercel Labs (Apache-2.0) qui permet aux agents de code de « voir » et d'utiliser les applications de bureau natives. Il lit l'arbre d'accessibilité du système d'exploitation et attribue une ref à chaque bouton et champ de saisie. L'agent agit sur une ref puis relit l'interface pour vérifier le résultat, au lieu de deviner des coordonnées en pixels sur une capture d'écran.
- Ce n'est pas un agent et il n'y a aucun modèle dedans. Chaque commande affiche un objet JSON puis se termine. La boucle observer, agir, vérifier tourne dans votre Claude Code, Codex ou Cursor : les trois peuvent donc l'utiliser.
- Une seule ligne pour l'installer :
npm install -g agent-desktop, puisnpx skills addajoute le skill officiel au projet, que Claude Code, Codex et Cursor lisent chacun. - Nous l'avons testé de bout en bout : avec la clé API de notre site, Claude Code a mis environ 28,6 secondes et Codex environ 35 secondes pour cliquer sur une calculatrice de bureau et relire le résultat. Les deux réponses étaient justes.
- Deux pièges à connaître : certaines applications (comme GNOME Calculator en GTK4, que nous avons essayée) n'exposent pas la position des contrôles, et les clics par ref échouent avec
bounds unavailable; et dans le bac à sable par défaut de Codex sous Linux, agent-desktop ne peut pas joindre le D-Bus du bureau et renvoieOperation not permitted. Les solutions sont dans la section des erreurs.
Créer une API Key et brancher agent-desktop sur Claude Code, Codex ou Cursor →
Qu'est-ce qu'agent-desktop et pourquoi on en parle autant
Le 31 octobre au matin (heure de Pékin), Chris Tate, de Vercel, a présenté agent-desktop sur X comme « agent-browser, for your whole computer » : du computer use pour n'importe quel agent de code, sur macOS, Windows et Linux, en arrière-plan sans prendre votre souris, avec plusieurs agents en parallèle. L'après-midi du 1er novembre, ce post comptait environ 640 000 vues, plus de 7 700 j'aime et plus de 8 700 enregistrements. L'auteur, Lahfir, a résumé les points forts dans son post de lancement : tests de bout en bout d'applications de bureau avec des agents, lecture via l'arbre d'accessibilité, exploration d'une seule partie de la fenêtre pour économiser des tokens, et plusieurs agents sur une même application.
Le dépôt GitHub compte environ 5 000 étoiles, a publié la v1.0.2 le 30 octobre et a mis en ligne sa documentation officielle en même temps. Les points clés :
| Élément | Détail |
|---|---|
| Forme | Une CLI en Rust et une bibliothèque C ; 60 noms de commandes, chacune renvoie un objet JSON |
| Fonctionnement | AX API sur macOS, UI Automation sur Windows, AT-SPI sur Linux ; il lit l'arbre de contrôles exposé par l'application |
| Configuration requise | macOS 13+ ; Windows 10 1809+ ou Server 2019+ ; Ubuntu 24.04+ (glibc 2.35 minimum) ; x64 et ARM64 |
| Ce qu'il ne fait pas | Pas de modèle intégré, pas d'automatisation web (agent-browser pour les pages), et rien sur une interface sans arbre d'accessibilité |
Côté communauté : selon @decildmc, il a remplacé cua-driver par agent-desktop sur son Mac, car ce dernier n'envoie au modèle que les éléments cliquables et déclenche le bouton directement sans bouger la souris. Selon @o_kwasniewski, il en a tiré un week-end une démo de tests e2e pour applications natives. Selon un résumé de tendance X, une démo de 52 étapes est passée d'environ 198k à environ 31k tokens grâce au squelette et à l'exploration ciblée.
Par rapport au computer use par captures d'écran, ses atouts sont des refs stables et des nouvelles tentatives sûres (chaque erreur indique si l'entrée a été livrée). Sa limite : il ne fonctionne qu'avec les applications qui exposent leurs informations d'accessibilité.
Étape 1 : installer agent-desktop et vérifier les permissions
npm install -g agent-desktop
agent-desktop version
agent-desktop status
Si status renvoie un supported_surfaces non vide et accessibility à granted, c'est prêt. Voici la sortie normale obtenue sous Linux :
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
"platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}
Permissions selon le système :
- macOS : accordez l'Accessibilité à l'application qui lance agent-desktop (Terminal, iTerm2, VS Code ou l'application hôte de l'agent).
agent-desktop permissions --guideouvre la bonne page des Réglages Système. Les captures demandent aussi l'Enregistrement de l'écran. Voir la doc macOS. - Windows : aucune autorisation, mais une application lancée en administrateur peut être lue sans être pilotée, sauf depuis un terminal au même niveau d'élévation. Le binaire n'est pas signé : SmartScreen ou l'antivirus peuvent le bloquer. Voir la doc Windows.
- Linux : lancez-le dans la session graphique de l'utilisateur, avec
at-spi2-coreinstallé. Voir la doc Linux.
Étape 2 : brancher agent-desktop sur Claude Code, Codex et Cursor
agent-desktop embarque ses propres guides alignés sur sa version (agent-desktop skills get desktop et skills get platform). Le brancher, c'est simplement faire lire ces deux guides à l'agent avant la première utilisation. Deux méthodes au choix.
Méthode A : installer le skill officiel avec skills (recommandé)
# 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
Dans notre projet, l'installateur a affiché :
✓ ./.agents/skills/agent-desktop
universal: Codex, Cursor
symlinked: Claude Code
Le skill est donc placé dans .agents/skills/agent-desktop du projet. Codex et Cursor lisent ce dossier directement, et Claude Code lit les mêmes fichiers via le lien symbolique .claude/skills/agent-desktop. Ajoutez -g pour l'installer au niveau utilisateur, pour tous les projets. Les bases des skills sont dans Utiliser les skills dans les agents IA.
L'installateur affiche aussi les résultats d'analyses de sécurité (cette fois Gen : Safe, Socket : 0 alerte, Snyk : Med Risk) et rappelle que les skills s'exécutent avec toutes les permissions de l'agent. Lisez SKILL.md avant d'installer.
Méthode B : ajouter deux lignes dans AGENTS.md / CLAUDE.md
Sans skill, placez l'extrait officiel dans le AGENTS.md du projet (lu par Codex et Cursor), et dans CLAUDE.md pour 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.
Pour partager un seul fichier d'instructions entre Claude Code et Codex, voir Un seul AGENTS.md pour Claude Code et Codex.
Étape 3 : configurer le client avec notre clé API
- Inscrivez-vous sur aicodewith.ai, ouvrez la gestion des clés, créez une clé et copiez la chaîne complète.
- Configurez votre client.
Claude Code :
export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="VOTRE_API_KEY"
Pour une configuration permanente ou sous Windows, voir Connecter Claude Code à une API tierce. Le même guide explique le choix des modèles dans Cursor.
Codex : dans le fichier 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 = "VOTRE_API_KEY"
Les autres champs sont décrits dans Le config.toml de Codex en détail.
Cursor : une fois le modèle configuré avec le guide ci-dessus, l'agent de Cursor lit .agents/skills et AGENTS.md dans le projet, comme Codex.
Étape 4 : laisser l'agent observer, agir, vérifier
La boucle tient en trois temps : snapshot renvoie l'arbre des contrôles avec leurs refs, vous agissez sur une ref avec click, type, etc., puis snapshot ou get à nouveau pour confirmer. Une ref porte l'identifiant du snapshot qui l'a produite (par exemple @s2jrj9msmdpdlw:e46) : refaites un snapshot quand l'interface change.
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
Pour les applications denses (clients Electron, IDE), la doc conseille d'abord un --skeleton peu profond, puis --root pour n'ouvrir que la zone utile : la consommation de tokens suit alors la zone travaillée. Voir Squelette et exploration ciblée.
En pratique, vous ne tapez pas ces commandes vous-même. Dites simplement à l'agent : « utilise agent-desktop pour ouvrir l'application X, fais Y et vérifie le résultat ».
Test : Claude Code et Codex pilotent une calculatrice avec notre clé API
Date du test : 1er novembre 2026. Environnement : Linux (Debian 13, X11 avec le gestionnaire de fenêtres xfwm4), agent-desktop 1.0.2, application cible galculator (GTK3). La consigne : uniquement cliquer sur les boutons, sans taper de formule, puis relire le résultat dans l'application. Les deux clients n'avaient que les lignes CLAUDE.md / AGENTS.md de la méthode B.
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:*)"
| Élément | Résultat |
|---|---|
| Calcul | 12 × 34 |
| Réponse | RESULT=408 (juste) |
| Durée | environ 28,6 secondes, 11 tours |
| Commandes agent-desktop | 15, dont une en échec corrigée par l'agent |
Commandes réellement lancées par Claude Code (extrait) :
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
Il a lu les deux guides comme demandé dans CLAUDE.md, pris un snapshot et cliqué les boutons par ref. Son premier clic sur « Copy Display Value » a échoué car le menu n'était pas encore ouvert, avec l'erreur ci-dessous. Il a alors ouvert le menu Edit, repris un snapshot avec --surface menu, recliqué, puis lu 408 avec clipboard-get :
{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
"message":"Target is not actionable: visible (live offscreen state is true)"}}
Un click prenait environ 0,07 seconde sur cette machine ; l'essentiel du temps passait dans la réflexion du modèle.
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>."
| Élément | Résultat |
|---|---|
| Calcul | 56 × 78 |
| Réponse | RESULT=4368 (juste) |
| Durée | environ 35 secondes |
| Commandes agent-desktop | 24, dont deux en échec |
Les deux échecs étaient des agent-desktop: command not found au début. Pour le test, nous avions installé agent-desktop dans le dossier du projet et non globalement, et Codex exécute les commandes dans un shell de connexion dont le PATH ne le contenait pas. Codex a retrouvé seul le chemin de l'exécutable et terminé la tâche. En usage réel, installez-le globalement avec npm install -g.
Un essai qui n'a pas abouti : GNOME Calculator en GTK4
Nous avions d'abord essayé GNOME Calculator (GTK4). agent-desktop listait tous les boutons, mais chaque clic échouait avec bounds unavailable : dans notre environnement X11, cette application n'expose pas la position de ses contrôles, la vérification de visibilité échoue et agent-desktop refuse de cliquer (delivery: not_delivered, donc aucun clic par erreur). Claude Code s'est alors mis à deviner des coordonnées avec mouse-click --headed ; au bout de 10 minutes il n'avait pas fini et nous l'avons arrêté. La saisie clavier avec agent-desktop press fonctionnait dans cette application.
Leçon : si un agent bute sans cesse sur bounds unavailable, ne le laissez pas deviner des coordonnées. Passez au clavier ou changez d'application. Vous pouvez l'écrire dans le prompt : « si les clics échouent, envoie les touches avec press ».
Créer une API Key et essayer sur votre propre machine →
Erreurs courantes et solutions
Les erreurs d'agent-desktop sont en JSON. Décidez d'après error.code et disposition.retry : safe signifie que l'entrée n'a pas été livrée et qu'on peut réessayer ; avec unsafe ou unknown, observez d'abord pour éviter une double action. La liste complète est sur la page officielle des erreurs. Voici celles que nous avons rencontrées.
status indique accessibility denied et supported_surfaces vide (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":[]}}
AT-SPI est absent ou invisible pour le processus. Installez at-spi2-core et lancez la commande dans la session graphique (un shell SSH sans variables de session ne voit aucune application). Les applications Flatpak ou snap demandent l'interface correspondante.
list-apps indique que le type de fenêtre native n'a pas pu être prouvé
{"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"}}
Nous l'avons eue sur un écran virtuel sans gestionnaire de fenêtres. Dès que nous en avons lancé un (xfwm4), list-apps a fonctionné. Un bureau normal ne devrait pas la rencontrer.
click expire avec 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"}}}
L'application n'expose pas la position de ses contrôles, et --headed n'y change rien. Utilisez press pour le clavier ou une application mieux prise en charge. Voir l'essai GTK4 plus haut.
click échoue avec ACTION_FAILED : visible (live offscreen state is true)
La cible n'est pas visible à ce moment, par exemple un élément d'un menu fermé. Ouvrez d'abord le menu, puis prenez une nouvelle ref avec snapshot --surface menu.
INTERNAL avec Operation not permitted dans 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)"}}
Nous l'avons constatée sous Linux avec codex exec -s workspace-write : le bac à sable de Codex bloque la connexion au D-Bus du bureau, et agent-desktop ne joint plus le bus d'accessibilité. Faites exécuter les commandes agent-desktop hors du bac à sable : approuvez la commande quand Codex le demande en mode interactif, ou réservez --dangerously-bypass-approvals-and-sandbox à une machine de test ou une VM dédiée. Notre test a utilisé cette seconde option sur un bureau de test séparé.
command not found
/bin/bash: line 1: agent-desktop: command not found
agent-desktop n'est pas dans le PATH utilisé par l'agent. Installez-le globalement avec npm install -g agent-desktop, ou indiquez le chemin complet dans AGENTS.md.
Les refs ne font rien dans Windows PowerShell
PowerShell interprète un @xxx nu comme l'opérateur de splatting : mettez les refs entre apostrophes.
agent-desktop click '@s8f3k2p9:e8'
Sécurité
- Les snapshots contiennent ce qui est à l'écran. Selon @mikawuf, ils incluent ce qui est affiché : ne les mettez pas dans des journaux publics. Fermez gestionnaire de mots de passe et messageries avant de laisser travailler un agent.
- N'accordez que le nécessaire. Dans Claude Code,
--allowedTools "Bash(agent-desktop:*)"n'autorise qu'agent-desktop ; ne désactivez le bac à sable de Codex que dans un environnement isolé. - Les skills et AGENTS.md sont des instructions que l'agent suivra : utilisez des sources fiables. Voir Les risques de détournement d'AGENTS.md.
- Pour le cloud : selon l'auteur Lahfir, agent-desktop peut aussi tourner dans un bureau Linux lancé dans une Vercel Sandbox.
FAQ
Quelle différence entre agent-desktop et agent-browser
agent-browser pilote les pages web, agent-desktop les applications de bureau natives. Pour le contenu web d'une application Chromium ou Electron, agent-desktop peut ouvrir un port DevTools avec launch "App" --cdp et le confier à agent-browser.
Faut-il un modèle spécial de computer use
Non. agent-desktop ne produit que du texte (JSON) : tout agent de code capable de lancer des commandes shell peut l'utiliser. Nos tests ont utilisé Claude Sonnet 4.6 et GPT-6.1 Sol.
Peut-on s'en servir pour les tests e2e de sa propre application de bureau
Oui, c'est l'un des usages principaux cités par les auteurs. Pour vérifier qu'une modification de code marche dans la vraie application, voir aussi Piloter une vraie application avec un skill de vérification.
À lire aussi
- Connecter Claude Code à une API tierce
- Le config.toml de Codex en détail
- Utiliser les skills dans les agents IA
- Un seul AGENTS.md pour Claude Code et Codex
- Piloter une vraie application avec un skill de vérification
Créer une API Key et démarrer avec Claude Code, Codex ou Cursor →
