К основному содержанию
скилл CX Codex

agent-desktop — скилл для Claude Code: клики и чтение интерфейса

Скилл agent-desktop для Claude Code и Codex позволяет агентам управлять десктопными программами через системное дерево доступности. Автоматизирует клики, чтение интерфейса и ввод текста на macOS, Windows и Linux.

Apache-2.0 12 100 установок ★ 25 974 обновлён 2026-11-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add vercel-labs/agent-desktop --skill agent-desktop -a claude-code
Открыть на GitHub

Что делает agent-desktop

Скилл даёт агенту команды для чтения и управления графическими окнами через системное дерево доступности. Каждая операция возвращает JSON со статусом ok, data или error. Агент делает снимок окна, получает ссылки на интерактивные элементы вида @s8f3k2p9:e1 и выполняет нажатия без перехвата курсора.

По умолчанию манипуляции работают в фоновом режиме. Прямой ввод мыши и клавиатуры через флаг --headed используется только при явном разрешении. На Windows и Linux одинаковые элементы окна не получают уникальных ссылок: нажать одну из дублирующихся кнопок можно только по координатам --xy.

Для работы требуется установленный в системе бинарник agent-desktop и права на управление специальными возможностями ОС. Встроенное создание песочниц ограничено macOS на базе Apple Silicon версии 13 и выше.

Какие задачи решает

  • нажимать кнопки и переключать флажки в десктопных окнах
  • считывать структуру и текстовое состояние интерфейса
  • заполнять поля форм и передавать клавиатурные комбинации
  • управлять окнами и буфером обмена без перехвата фокуса

Примеры запросов агенту

  • Сделай снимок интерфейса приложения Заметки и нажми кнопку создания новой записи
  • Найди форму авторизации в активном окне и заполни поле логина
  • Проверь статус флажка в открытом системном диалоге

Как установить agent-desktop

1Через Skills CLI (Vercel)

npx skills add vercel-labs/agent-desktop --skill agent-desktop -a claude-code

2Вручную: положить файлы

~/.claude/skills/agent-desktop/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/agent-desktop/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об agent-desktop

Как установить agent-desktop в Claude Code?

Выполните команду npx skills add vercel-labs/agent-desktop --skill agent-desktop -a claude-code.

Что делает agent-desktop?

Скилл позволяет агенту считывать дерево доступности запущенных программ и управлять ими через клики, ввод текста и чтение состояний окон.

Что нужно для работы agent-desktop?

Требуется установленная утилита agent-desktop в PATH и выданные операционной системой разрешения на работу со специальными возможностями.

Исходный текст

SKILL.md · Apache-2.0
---
name: agent-desktop
tags: computer-use, desktop-automation, accessibility, ai-agent, gui-automation, cli
requirements:
  - agent-desktop
description: >
  Operate desktop applications on macOS, Windows and Linux through native accessibility trees,
  using the agent-desktop CLI. Use when an AI agent must see or act on a desktop GUI:
  click buttons, fill forms, read UI state, navigate menus, toggle checkboxes, scroll,
  drag, type text, press shortcuts, take screenshots, manage windows, use the clipboard,
  launch or close apps, read notifications.
  Triggers on: "click button", "fill form", "open app", "read UI", "computer use",
  "operate desktop", "accessibility tree", "snapshot app", "type into field", "navigate menu",
  "toggle checkbox", "take screenshot", "desktop automation", "agent-desktop",
  or any desktop GUI task on macOS, Windows or Linux.
---

# agent-desktop

agent-desktop is a CLI that reads and operates desktop apps through the OS accessibility tree. Every command prints one JSON envelope (`ok`, `data` or `error`). It is a tool, not an agent: the observe, act and verify loop runs in you.

## Shell syntax

Examples use a POSIX shell. In PowerShell, quote every ref (`'@s8f3k2p9:e1'`), because a bare `@token` is the splatting operator. Use `$env:NAME = 'value'` instead of `export`, and `| ConvertFrom-Json` instead of `$(...)` and `jq`. The Windows skill has the PowerShell forms.

## First run

1. Run `agent-desktop status`. It reports the platform, permissions and `supported_surfaces`.
2. Run `agent-desktop skills get platform`. It loads the skill for the OS the binary runs on (macOS, Windows or Linux).
3. For flags and syntax, run `agent-desktop <command> --help`. This skill does not repeat flag lists.

## The loop

Use `find` when you know the role or exact name. Otherwise map the app first and drill into one region.

```
agent-desktop snapshot --skeleton --app "Notes" -i --compact   # shallow map, children_count on cut branches
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verify: re-read the same region
```

- A small app needs no skeleton. Take a full `snapshot -i`.
- `-i` keeps interactive nodes only, so a row's static-text label is dropped. To tell which row a repeated button belongs to, drill that row's container with `--root` and leave out `-i`. On Windows and Linux that reads the row but does not make its button actionable: a button repeated in other rows is a twin in the window and its ref is refused (see Refs).
- A `--root` drill adds its refs to the same snapshot id. Refs outside the drilled subtree, and the drilled root itself, stay valid; refs that were already inside it are replaced, so an old ref there returns `STALE_REF`.
- Never skeleton a surface (`--surface menu`, `sheet`, `alert`). A surface is already focused.
- An action that opens a menu, sheet or alert lists it in `data.surfaces`. Target that overlay next.
- After an async step, use `wait` (see `commands-system.md`). A fixed sleep is a race.

## Refs

- Output refs are qualified: `@<snapshot_id>:e<N>`, for example `@s8f3k2p9:e1`. Pass them to later commands as they are.
- Refs are valid for one snapshot. After any UI change, re-drill the affected region or take a new snapshot.
- Only addressable elements get refs. Static text and inert containers do not.
- A command re-identifies the element before it acts. On macOS the ref carries the element's own address, so identical twins each keep their ref. On Windows and Linux a ref resolves only when it was the only element in the window its snapshot captured with its role, native id, name and description, counted even below a skeleton or depth cut, and exactly one live element still matches. Identical twins there have no ref path: only `--headed mouse-click --xy X,Y` can choose one, it takes the foreground, and a Linux Wayland session refuses it.
- `STALE_REF`: the element is gone or no longer matches. `details.kind` is `saved_ref_absent`, or `retained_object_stale` on macOS. Take a fresh snapshot and use the new ref.
- `AMBIGUOUS_TARGET`: an identical element appeared (`saved_ref_ambiguous`), or the ref was not proven unique at capture (`identity_not_unique`). Repeating the ref or re-snapshotting identical twins gives the same refusal; act on a control that is unique in the window. `identity_not_unique` also follows a snapshot that could not read the whole window in time: retake it with a larger `--timeout-ms`.
- `TIMEOUT` with `details.kind: resolution_identity_unknown`: a live read did not answer, so identity is unproven. Nothing was sent; retry.
- `SNAPSHOT_NOT_FOUND`: the snapshot id expired. Snapshot again.

## Delivery and retry

Action results carry `data.disposition` and errors carry `error.disposition`, each with `delivery` and `retry`. Observation commands such as `snapshot` have none on success; their errors, and every `INVALID_ARGS` refusal, carry `not_delivered` and `retry: safe`.

- Retry or substitute an action only when `disposition.retry` is `safe`. Only `not_delivered` is safe.
- Any other delivery value means the action may have landed. A repeat can click, type or submit twice, and `toggle` can undo itself.
- On a result that is not safe, read the live state (`get`, `is`, or a fresh snapshot) and decide from that. `details.post_state` helps when present.
- Branch on `error.code` and `error.disposition`. Message and suggestion text can change.
- `details.retryable: false` means waiting cannot change the outcome. Try a different approach.

## Headless and headed

Ref actions are headless by default. They use semantic accessibility calls and do not take focus, move the cursor, synthesize keys or use the clipboard. If no semantic path exists, the action fails closed. Use the global `--headed` flag only when the user explicitly permits physical input, such as double-click, hover, drag, or focus. Never switch to headed mode to recover from a headless failure. Raw coordinates (`--xy`) never imply focus. Which actions need `--headed` differs by OS: read the platform skill.

## Sandboxes

A sandbox is a desktop a provider manages on your machine. The provider is `macos`: a macOS VM on an Apple Silicon Mac running macOS 13 or later. Linux and Windows have no provider; to run agent-desktop in a container you manage yourself there, follow `agent-browser.dev/desktop/guides/docker-container`.

```sh
agent-desktop sandbox install                          # report the provider's state
agent-desktop sandbox install macos                    # compile and sign the VM host and guest agent, then report ready
```

```sh
agent-desktop sandbox create demo --provider macos --set from=base   # clone a set-up sandbox; or --set ipsw=latest to install
agent-desktop sandbox start demo                       # start it headless; add --window to show its desktop
agent-desktop sandbox status demo                      # state, message and next command
agent-desktop sandbox list                             # every sandbox and its state
agent-desktop sandbox exec demo -- status              # run a command in the guest
agent-desktop sandbox stop demo                        # stop the sandbox
agent-desktop sandbox rm demo                          # remove it
```

Names are 1–32 lowercase letters, digits or hyphens, starting with a letter or digit. `exec` returns the guest's envelope and exit status; a provider failure returns a host error. `rm` refuses a sandbox reported as `running`; stop it first. `create` needs exactly one source: `--set from=<sandbox>`, `--set ipsw=latest` or `--set ipsw=<path>`. `start` answers `working`, or `needs_setup` when the guest agent is not answering; wait for `status` to report `running` before `exec`.

Read `state`, `message` and optional `next`; `ok: true` alone does not mean the sandbox is ready.

- `unavailable`: satisfy the host requirements in `message` and `next`.
- `missing`: install the provider.
- `ready`: create a sandbox.
- `working`: repeat the command in `next` until the work finishes.
- `needs_setup`: have a person complete guest setup, then check status.
- `running`: run guest commands, or stop before removal.
- `stopped`: start the sandbox to use it, or remove it.
- `broken`: follow `next`; a broken sandbox may need removal.

A sandbox separates the desktop, not the network or the host. Sandboxes on one host share a virtual network, and a guest can reach the host's network services; keep one trust level per host. The host reaches the guest over the virtual machine's own socket device: only the process that runs the VM can open that connection, and `agent-desktop-guest` refuses any caller that is not the host. The host sends commands only to the agent whose key it recorded at setup, so another guest account cannot answer in its place. The agent runs the guest's `agent-desktop` with the arguments after `--` and never a shell. In the guest, Accessibility belongs to `agent-desktop-guest`.

Cloning a configured macOS VM has been tested end to end. Installing the first VM from a macOS image is experimental and has not been verified end to end. Provider setup steps and limits are in the docs: `agent-browser.dev/desktop/sandboxes/macos`.

## References

Load one only when you need it: `agent-desktop skills get desktop <reference>`.

| Reference | Open it when |
|-----------|--------------|
| `commands-observation` | You need `snapshot`, `find`, `get`, `is`, `screenshot`, `list-surfaces` semantics, partial trees, or the `--root` rules |
| `commands-interaction` | You choose between click, type, set-value, select, toggle, scroll, press and mouse commands, or you debug an action error |
| `commands-system` | You launch or close apps, manage windows, use the clipboard, `wait`, `batch`, sessions, multi-agent cursors, tracing, or load skills |
| `workflows` | You want worked patterns (forms, menus, dialogs, waiting for a new window, scroll-find, drag) and the anti-patterns list |

© vercel-labs · Apache-2.0 · vercel-labs/agent-desktop

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
bad-ass-mcp HoldMyBeer-gg MCP-сервер bad-ass-mcp для Claude Code управляет окнами и элементами интерфейса через дерево доступности ОС. Агент может находить кнопки и поля, вводить текст и запускать действия в приложениях. CX Codex +1 ★ 8звёзд репо computer-control autohandai Скилл computer-control управляет нативными программами и окнами на рабочем столе через Autohand Computer Use. Помогает агенту находить окна, нажимать кнопки и проверять результат на экране. CX Codex +1 ★ 219звёзд репо Computer Use domdomegg MCP-сервер Computer Use даёт языковой модели доступ к рабочему столу через снимки экрана и клавиатурный ввод. Помогает автоматизировать рутинные действия в любых программах. CX Codex +1 ★ 406звёзд репо desktop-touch-mcp Harusame64 MCP-сервер desktop-touch-mcp, через который Claude или Cursor видят окна Windows 10/11 и работают с ними: скриншоты, UI Automation, мышь, клавиатура, Chrome. CX Codex +1 ★ 26звёзд репо desktop-applications Claude MPM Team Скилл desktop-applications для Claude Code помогает создавать кроссплатформенные приложения на Rust с Tauri или нативным GUI. Разбирает выбор фреймворка, архитектуру и интеграцию с ОС. CX Codex +1 266установок linux-at-spi2 martinholovsky Скилл linux-at-spi2 для агента, который нажимает кнопки в GTK- и Qt-приложениях на Linux через AT-SPI2 и D-Bus, с блокировкой полей паролей и журналом операций. CX Codex +1 190установок

Из того же набора6

agent-desktop-windows Скилл agent-desktop-windows для Claude Code описывает автоматизацию интерфейса Windows через agent-desktop. Он подключается к задачам с Windows GUI, деревом UIA и ошибкой E_ACCESSDENIED. CX Codex +1 1 800установок agent-desktop-macos Скилл agent-desktop-macos для Claude Code настраивает правила автоматизации графического интерфейса macOS через CLI agent-desktop. Управляет разрешениями TCC и координирует работу с системными меню. CX Codex +1 1 100установок agent-desktop-linux Скилл agent-desktop-linux для Claude Code описывает автоматизацию Linux GUI через agent-desktop, включая X11, Wayland и AT-SPI. Срабатывает на задачах с окнами и приложениями GNOME. CX Codex +1 661установок agent-desktop-ffi Скилл agent-desktop-ffi для Claude Code предоставляет C-ABI привязки к PlatformAdapter из agent-desktop. Он позволяет напрямую вызывать функции ad_* без запуска отдельного CLI-бинарника при каждом обращении. CX Codex +1 614установок jev-desktop Скилл jev-desktop для Claude Code управляет настольным приложением по цели или выполняет один заданный шаг. Запускается для автоматизации действий в приложении без передачи дерева доступности в контекст агента. CX Codex +1 587установок

Ещё в каталоге

Спонсоры проекта

Компании, которые помогают держать аналитику открытой