Kurz gesagt: agent-desktop ist ein Open-Source-Kommandozeilenwerkzeug von Vercel Labs (Apache-2.0), mit dem Coding-Agents native Desktop-Apps „sehen“ und bedienen können. Es liest den Accessibility-Baum des Betriebssystems und gibt jedem Button und jedem Eingabefeld eine Ref. Der Agent handelt auf einer Ref und liest die Oberfläche danach erneut, um das Ergebnis zu prüfen, statt Pixelkoordinaten aus einem Screenshot zu raten.
- Es ist kein Agent und enthält kein Modell. Jeder Befehl gibt ein JSON-Objekt aus und beendet sich. Die Schleife aus Beobachten, Handeln und Prüfen läuft in Ihrem Claude Code, Codex oder Cursor, deshalb funktioniert es mit allen dreien.
- Installation in einer Zeile:
npm install -g agent-desktop, danach legtnpx skills addden offiziellen Skill ins Projekt, wo Claude Code, Codex und Cursor ihn jeweils finden. - Wir haben es komplett getestet: Mit dem API Key unserer Seite brauchte Claude Code etwa 28,6 Sekunden und Codex etwa 35 Sekunden, um einen Desktop-Taschenrechner per Klick zu bedienen und das Ergebnis zurückzulesen. Beide Antworten stimmten.
- Zwei Fallen vorab: Manche Apps (etwa der GNOME-Rechner in GTK4, den wir ausprobiert haben) geben keine Positionen ihrer Bedienelemente heraus, dann scheitern Ref-Klicks mit
bounds unavailable; und in der Standard-Sandbox von Codex unter Linux erreicht agent-desktop den D-Bus des Desktops nicht und meldetOperation not permitted. Die Lösungen stehen im Fehlerabschnitt.
API Key erstellen und agent-desktop mit Claude Code, Codex oder Cursor verbinden →
Was agent-desktop ist und warum gerade alle darüber reden
Am Morgen des 31. Oktober (Pekinger Zeit) hat Chris Tate von Vercel agent-desktop auf X vorgestellt, als „agent-browser, for your whole computer“: Computer Use für jeden Coding-Agent, unter macOS, Windows und Linux, im Hintergrund, ohne Ihnen die Maus wegzunehmen, mit mehreren Agents parallel. Am Nachmittag des 1. November hatte der Beitrag rund 640.000 Aufrufe, über 7.700 Likes und über 8.700 Lesezeichen. Der Autor Lahfir nannte in seinem Launch-Beitrag die Kernpunkte: End-to-End-Tests von Desktop-Apps mit Agents, Lesen über den Accessibility-Baum, gezieltes Aufklappen eines Fensterbereichs, um Tokens zu sparen, und viele Agents gleichzeitig in einer App.
Das GitHub-Repository hat rund 5.000 Sterne, veröffentlichte am 30. Oktober v1.0.2 und gleichzeitig die offizielle Dokumentation. Die wichtigsten Fakten:
| Punkt | Details |
|---|---|
| Form | Eine Rust-CLI plus C-Bibliothek; 60 Befehlsnamen, jeder gibt ein JSON-Objekt aus |
| Funktionsweise | AX API unter macOS, UI Automation unter Windows, AT-SPI unter Linux; gelesen wird der Baum, den die App bereitstellt |
| Voraussetzungen | macOS 13+; Windows 10 1809+ oder Server 2019+; Ubuntu 24.04+ (ab glibc 2.35); x64 und ARM64 |
| Was es nicht kann | Kein eingebautes Modell, keine Web-Automatisierung (dafür agent-browser), und keine Oberflächen ohne Accessibility-Baum |
Aus der Community: Laut @decildmc hat er auf dem Mac von cua-driver zu agent-desktop gewechselt, weil es dem Modell nur anklickbare Elemente schickt und Klicks den Button direkt auslösen, ohne die Maus zu bewegen. Laut @o_kwasniewski hat er an einem Wochenende darauf eine Demo für e2e-Tests nativer Desktop-Apps gebaut. Laut einer X-Trend-Zusammenfassung sank in einer Demo mit 52 Schritten der Token-Verbrauch von etwa 198k auf etwa 31k, dank Skelett-Snapshot und gezieltem Aufklappen.
Gegenüber Computer Use per Screenshot sind die Stärken stabile Refs und sichere Wiederholungen (jeder Fehler sagt, ob die Eingabe angekommen ist). Die Grenze: Es funktioniert nur mit Apps, die Accessibility-Informationen bereitstellen.
Schritt 1: agent-desktop installieren und Berechtigungen prüfen
npm install -g agent-desktop
agent-desktop version
agent-desktop status
Liefert status ein nicht leeres supported_surfaces und steht accessibility auf granted, kann es losgehen. So sah die normale Ausgabe bei uns unter Linux aus:
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
"platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}
Berechtigungen je System:
- macOS: Geben Sie der App, die agent-desktop startet (Terminal, iTerm2, VS Code oder die Host-App des Agents), die Bedienungshilfen-Berechtigung.
agent-desktop permissions --guideöffnet die passende Seite der Systemeinstellungen. Screenshots brauchen zusätzlich die Bildschirmaufnahme. Siehe macOS-Doku. - Windows: Keine Freigabe nötig, aber Apps, die als Administrator laufen, lassen sich nur lesen und nicht bedienen, außer aus einem gleich hoch berechtigten Terminal. Die Binärdatei ist nicht signiert, SmartScreen oder Virenscanner können sie blockieren. Siehe Windows-Doku.
- Linux: In der grafischen Sitzung des Benutzers ausführen, mit installiertem
at-spi2-core. Siehe Linux-Doku.
Schritt 2: agent-desktop mit Claude Code, Codex und Cursor verbinden
agent-desktop bringt eigene, zur Version passende Anleitungen mit (agent-desktop skills get desktop und skills get platform). Verbinden heißt nur: Der Agent liest diese beiden vor dem ersten Einsatz. Zwei Wege zur Auswahl.
Weg A: den offiziellen Skill mit skills installieren (empfohlen)
# 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
In unserem Projekt gab der Installer Folgendes aus:
✓ ./.agents/skills/agent-desktop
universal: Codex, Cursor
symlinked: Claude Code
Der Skill liegt also in .agents/skills/agent-desktop im Projekt. Codex und Cursor lesen diesen Ordner direkt, Claude Code liest dieselben Dateien über den Symlink .claude/skills/agent-desktop. Mit -g wird er auf Benutzerebene für alle Projekte installiert. Grundlagen zu Skills: Skills in KI-Agents nutzen.
Der Installer zeigt außerdem Ergebnisse von Sicherheitsscans (diesmal Gen: Safe, Socket: 0 alerts, Snyk: Med Risk) und erinnert daran, dass Skills mit den vollen Rechten des Agents laufen. Lesen Sie SKILL.md vor der Installation.
Weg B: zwei Zeilen in AGENTS.md / CLAUDE.md
Ohne Skill fügen Sie den offiziellen Text in die AGENTS.md des Projekts ein (lesen Codex und Cursor) und für Claude Code in CLAUDE.md:
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.
Eine gemeinsame Anweisungsdatei für Claude Code und Codex beschreibt Eine AGENTS.md für Claude Code und Codex.
Schritt 3: den Client mit unserem API Key einrichten
- Bei aicodewith.ai registrieren, die Schlüsselverwaltung öffnen, einen Key erstellen und die komplette Zeichenkette kopieren.
- Ihren Client konfigurieren.
Claude Code:
export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="IHR_API_KEY"
Für eine dauerhafte Einrichtung oder Windows siehe Claude Code mit einer Drittanbieter-API verbinden. Dieselbe Anleitung erklärt die Modellauswahl in Cursor.
Codex: in die globale ~/.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 = "IHR_API_KEY"
Weitere Felder erklärt Codex config.toml im Detail.
Cursor: Ist das Modell nach der Anleitung oben eingerichtet, liest der Cursor-Agent .agents/skills und AGENTS.md im Projekt, genau wie Codex.
Schritt 4: den Agent beobachten, handeln, prüfen lassen
Die Schleife hat drei Schritte: snapshot liefert den Baum der Bedienelemente mit Refs, Sie handeln auf einer Ref mit click, type usw., danach erneut snapshot oder get zur Bestätigung. Eine Ref enthält die ID des Snapshots, aus dem sie stammt (etwa @s2jrj9msmdpdlw:e46). Ändert sich die Oberfläche, machen Sie einen neuen Snapshot.
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
Bei dichten Apps (Electron-Clients, IDEs) empfiehlt die Doku erst ein flaches --skeleton und dann --root, um nur den benötigten Bereich aufzuklappen. Der Token-Verbrauch richtet sich dann nach dem Bereich, in dem Sie arbeiten. Siehe Skelett und gezieltes Aufklappen.
Normalerweise tippen Sie diese Befehle nicht selbst. Sagen Sie dem Agent einfach: „Öffne mit agent-desktop die App X, erledige Y und prüfe das Ergebnis.“
Test: Claude Code und Codex bedienen einen Taschenrechner mit unserem API Key
Testdatum: 1. November 2026. Umgebung: Linux (Debian 13, X11 mit dem Fenstermanager xfwm4), agent-desktop 1.0.2, Ziel-App galculator (GTK3). Aufgabe: nur Buttons klicken, keine Formel tippen, dann das Ergebnis aus der App zurücklesen. Beide Clients hatten nur die Zeilen aus Weg B in 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:*)"
| Punkt | Ergebnis |
|---|---|
| Aufgabe | 12 × 34 |
| Antwort | RESULT=408 (richtig) |
| Dauer | etwa 28,6 Sekunden, 11 Runden |
| agent-desktop-Befehle | 15, davon einer fehlgeschlagen und vom Agent korrigiert |
Von Claude Code tatsächlich ausgeführte Befehle (Auszug):
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
Es las die beiden Anleitungen wie in CLAUDE.md verlangt, machte einen Snapshot und klickte die Buttons per Ref. Der erste Klick auf „Copy Display Value“ schlug fehl, weil das Menü noch nicht offen war, mit dem Fehler unten. Danach öffnete es das Edit-Menü, machte mit --surface menu einen neuen Snapshot, klickte erneut und las mit clipboard-get die 408 aus:
{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
"message":"Target is not actionable: visible (live offscreen state is true)"}}
Ein einzelner click dauerte auf dieser Maschine etwa 0,07 Sekunden; die meiste Zeit verbrachte das Modell mit Nachdenken.
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>."
| Punkt | Ergebnis |
|---|---|
| Aufgabe | 56 × 78 |
| Antwort | RESULT=4368 (richtig) |
| Dauer | etwa 35 Sekunden |
| agent-desktop-Befehle | 24, davon zwei fehlgeschlagen |
Beide Fehlschläge waren agent-desktop: command not found am Anfang. Für den Test hatten wir agent-desktop im Projektordner statt global installiert, und Codex führt Befehle in einer Login-Shell aus, deren PATH es nicht enthielt. Codex fand den Pfad zur Datei selbst und erledigte die Aufgabe. Im echten Einsatz global mit npm install -g installieren.
Ein Lauf, der nicht klappte: GNOME-Rechner in GTK4
Zuerst hatten wir den GNOME-Rechner (GTK4) genommen. agent-desktop listete alle Buttons, aber jeder Klick scheiterte mit bounds unavailable: In unserer X11-Umgebung gibt diese App keine Positionen ihrer Bedienelemente heraus, die Sichtbarkeitsprüfung schlägt fehl und agent-desktop verweigert den Klick (delivery: not_delivered, es wurde also nichts versehentlich geklickt). Claude Code begann daraufhin, Bildschirmkoordinaten mit mouse-click --headed zu raten, war nach 10 Minuten noch nicht fertig, und wir haben es gestoppt. Tastatureingaben mit agent-desktop press funktionierten in dieser App.
Lehre: Wenn ein Agent ständig auf bounds unavailable stößt, lassen Sie ihn keine Koordinaten raten. Wechseln Sie auf Tastatur oder eine andere App. Das können Sie in den Prompt schreiben: „Wenn Klicks scheitern, sende Tasten mit press.“
API Key erstellen und auf dem eigenen Rechner ausprobieren →
Häufige Fehler und Lösungen
Fehler von agent-desktop sind JSON. Entscheiden Sie anhand von error.code und disposition.retry: safe heißt, die Eingabe kam nicht an, eine Wiederholung ist unproblematisch; bei unsafe oder unknown erst beobachten, damit nichts doppelt ausgelöst wird. Die vollständige Liste steht auf der offiziellen Fehlerseite. Diese hatten wir selbst.
status zeigt accessibility denied und leeres supported_surfaces (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 fehlt oder ist für den Prozess nicht sichtbar. Installieren Sie at-spi2-core und arbeiten Sie in der grafischen Sitzung (eine SSH-Shell ohne Sitzungsvariablen sieht keine Apps). Apps in Flatpak oder snap brauchen die passende Schnittstelle.
list-apps meldet, der native Fenstertyp sei nicht nachweisbar
{"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"}}
Das trat bei uns auf einem virtuellen Display ohne Fenstermanager auf. Sobald einer lief (xfwm4), funktionierte list-apps. Auf einem normalen Desktop sollte das nicht vorkommen.
click läuft mit bounds unavailable in einen Timeout
{"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"}}}
Die App gibt keine Positionen heraus, und --headed hilft nicht. Nutzen Sie press für Tastatureingaben oder eine App mit besserer Accessibility-Unterstützung. Siehe den GTK4-Lauf oben.
click scheitert mit ACTION_FAILED: visible (live offscreen state is true)
Das Ziel ist gerade nicht sichtbar, etwa ein Eintrag in einem geschlossenen Menü. Öffnen Sie zuerst das Menü und holen Sie mit snapshot --surface menu eine neue Ref.
INTERNAL mit Operation not permitted in 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)"}}
Wir sahen das unter Linux mit codex exec -s workspace-write: Die Codex-Sandbox blockiert die Verbindung zum D-Bus des Desktops, agent-desktop erreicht den Accessibility-Bus nicht. Lassen Sie agent-desktop-Befehle außerhalb der Sandbox laufen: Im interaktiven Modus den Befehl freigeben, wenn Codex fragt, oder --dangerously-bypass-approvals-and-sandbox nur auf einer eigenen Testmaschine oder VM verwenden. Unser Test lief mit Letzterem auf einem separaten Test-Desktop.
command not found
/bin/bash: line 1: agent-desktop: command not found
agent-desktop ist nicht im PATH, den der Agent benutzt. Global mit npm install -g agent-desktop installieren oder den vollen Pfad in AGENTS.md angeben.
Refs wirken in Windows PowerShell nicht
PowerShell hält ein nacktes @xxx für den Splatting-Operator, also Refs in einfache Anführungszeichen setzen:
agent-desktop click '@s8f3k2p9:e8'
Sicherheitshinweise
- Snapshots enthalten, was auf Ihrem Bildschirm steht. Laut @mikawuf enthalten sie die angezeigten Inhalte, also nicht in öffentliche Logs damit. Schließen Sie Passwortmanager und Chat-Apps, bevor ein Agent arbeitet.
- Nur freigeben, was nötig ist. In Claude Code erlaubt
--allowedTools "Bash(agent-desktop:*)"nur agent-desktop; die Codex-Sandbox nur in einer isolierten Umgebung abschalten. - Skills und AGENTS.md sind Anweisungen, die Ihr Agent befolgt, also nur aus vertrauenswürdigen Quellen. Siehe Risiken durch gekaperte AGENTS.md.
- Für die Cloud: Laut Autor Lahfir läuft agent-desktop auch in einem Linux-Desktop, der in einer Vercel Sandbox gestartet wird.
FAQ
Was ist der Unterschied zwischen agent-desktop und agent-browser
agent-browser steuert Webseiten, agent-desktop native Desktop-Apps. Für die Webinhalte einer Chromium- oder Electron-App kann agent-desktop mit launch "App" --cdp einen DevTools-Port öffnen und an agent-browser übergeben.
Brauche ich ein spezielles Computer-Use-Modell
Nein. agent-desktop gibt nur Text (JSON) aus, jeder Coding-Agent, der Shell-Befehle ausführen kann, kann es nutzen. Unsere Tests liefen mit Claude Sonnet 4.6 und GPT-6.1 Sol.
Kann ich damit e2e-Tests meiner eigenen Desktop-App schreiben
Ja, das ist einer der Hauptzwecke, die die Autoren nennen. Um zu prüfen, ob eine Codeänderung in der echten App funktioniert, siehe auch Eine echte App mit einem Verification-Skill steuern.
Weiterlesen
- Claude Code mit einer Drittanbieter-API verbinden
- Codex config.toml im Detail
- Skills in KI-Agents nutzen
- Eine AGENTS.md für Claude Code und Codex
- Eine echte App mit einem Verification-Skill steuern
API Key erstellen und mit Claude Code, Codex oder Cursor loslegen →
