agent-desktop CLI
CLI на Rust для macOS: агент читает интерфейс любого приложения через дерево доступности и кликает, печатает, листает по ссылкам на элементы без скриншотов
- 1 829 ★ репозитория
- Последний коммит
- Apache-2.0
Широкий доступ
Почему такой уровень
- Видит и нажимает любые элементы любых приложений, может закрывать их принудительно, печатать текст и отправлять сообщения от вашего имени
- Читает и записывает буфер обмена и читает уведомления, где бывают коды и личные сообщения
- Для работы просит у macOS Универсальный доступ и запись экрана, разрешение выдается терминалу целиком
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add cli/agent-desktopОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Видит и нажимает любые элементы любых приложений, может закрывать их принудительно, печатать текст и отправлять сообщения от вашего имени
- Читает и записывает буфер обмена и читает уведомления, где бывают коды и личные сообщения
- Для работы просит у macOS Универсальный доступ и запись экрана, разрешение выдается терминалу целиком
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
agent-desktop — консольная программа на Rust, через которую агент видит окна macOS и управляет ими. Программа не принимает решений: цикл «посмотреть, выбрать, сделать» ведет сам агент, а `agent-desktop` отвечает на каждую команду структурированным JSON с кодом ошибки и подсказкой для повтора. Для чтения интерфейса она использует дерево доступности системы, поэтому скриншоты и поиск по пикселям не нужны. Команда `snapshot --app Finder -i` возвращает дерево элементов окна и присваивает кнопкам, полям, пунктам меню ссылки вида `@s8f3k2p9:e1`. По ссылке выполняются `click`, `type`, `set-value`, `select`, `toggle`, `scroll`, `drag`, а `press cmd+s` нажимает сочетание клавиш. Перед действием программа проверяет, что элемент виден, доступен и поддерживает действие. Если интерфейс изменился, вернется `STALE_REF` или `AMBIGUOUS_TARGET` вместо клика наугад. Для плотных приложений вроде Slack или VS Code режим `--skeleton` дает короткий обзор, а `--root` раскрывает нужную область. Помимо работы с элементами, у программы есть команды для запуска и закрытия приложений, перемещения окон, чтения и записи буфера обмена, чтения уведомлений, ожидания элемента, текста или окна и пакетного выполнения `batch`. Режим `session start` ведет журнал шагов, который `trace export` собирает в один HTML-файл. Команда `launch "Obsidian" --cdp` открывает у приложения на Chromium порт отладки на `127.0.0.1`, чтобы веб-содержимое вел Playwright или `agent-browser`. Скилл `agent-desktop` в `skills/` объясняет агенту эти команды.
Для кого. Для разработчиков агентов и пользователей Claude Code или Codex на Mac, которым нужно, чтобы агент управлял обычными приложениями, у которых нет API: Finder, Системными настройками, Slack, Xcode.
Подходит, если
- Нужно автоматизировать приложение для Mac, у которого нет командной строки и API, например настройки в Системных настройках или шаги в Xcode
- Агент, работающий по скриншотам, путает кнопки, а нужны повторяемые действия по стабильным ссылкам на элементы
- Приложение на Electron вроде Slack или Obsidian надо читать дешево по токенам: режим `--skeleton` сокращает снимок интерфейса
- Нужен разбор шагов после запуска: журнал `session` с `trace export` показывает, что агент делал в каждом окне
Не подходит, если
- У вас Windows или Linux: поддержка этих систем в таблице платформ отмечена как плановая, готов только macOS
- Нужен веб-браузер: для страниц лучше инструменты вроде Playwright, а `agent-desktop` берет на себя нативные окна и меню
- Вы не хотите ставить Rust: сборка из исходников требует Rust 1.89 и macOS 13.0, а пакет npm приносит готовый бинарник
- Агент должен держать клавишу или кнопку мыши: команды `key-down`, `key-up`, `mouse-down` и `mouse-up` зарезервированы и пока возвращают ошибку
Пример запроса к агенту
Открой Системные настройки, найди раздел «Основные» и скажи, какая у меня сейчас версия macOS, ничего не меняяОграничения
- Работает на macOS. Ему нужно разрешение «Универсальный доступ» для программы, которая запускает команду (Terminal, iTerm2, VS Code, Codex), а для скриншотов еще «Запись экрана». `agent-desktop permissions --request` запрашивает недостающее в изолированном помощнике.
- В npm лежит версия 0.9.4, а текущий адаптер macOS автор называет первой фазой проекта.
- По умолчанию действия по ссылке идут без физического клика и без перехвата фокуса. Для двойного клика, наведения и перетаскивания нужен флаг `--headed`, и тогда реальный курсор и фокус занимает агент.
- При установке пакета бинарник скачивается из релизов GitHub, поэтому нужен доступ к github.com. Лицензия Apache-2.0.
Как отключить. Выполните `npm uninstall -g agent-desktop` и уберите папку скилла `agent-desktop` из каталога скиллов агента. Разрешение «Универсальный доступ» снимите в Системных настройках, в разделе «Конфиденциальность и безопасность». Журналы сессий лежат в `~/.agent-desktop/sessions`, `session gc` чистит старые.
Частые вопросы
Нужны ли скриншоты, чтобы агент видел интерфейс?
Нет. Агент читает дерево доступности: команда `snapshot` выдает роли, названия и ссылки на кнопки, поля и пункты меню. Скриншот делает отдельная команда `screenshot`, и для него нужно разрешение на запись экрана.
Что значит ошибка STALE_REF?
Ссылка указывала на элемент, которого в окне уже нет или который изменился. Программа перед действием заново находит цель по окну, пути, роли и положению и не кликает вслепую. Сделайте новый `snapshot` и повторите действие по свежей ссылке.
Чем режим skeleton полезен на Slack или VS Code?
Полный снимок такого приложения огромен: в примере автора по Slack это 30 743 токена против 383 у обзора. Режим `--skeleton` показывает дерево на три уровня и число вложенных элементов. Нужную область раскрывает `snapshot --root`.
Как управлять вкладками внутри приложения на Electron?
Запустите приложение командой `agent-desktop launch "Obsidian" --cdp`. Она открывает порт отладки на `127.0.0.1`, к которому подключаются Playwright, Puppeteer или `agent-browser`. Меню и диалоги остаются на стороне `agent-desktop`. Для уже запущенного приложения сначала выполните `close-app`.
Можно ли вызывать agent-desktop не из командной строки?
Да. В релизах лежит библиотека `libagent_desktop_ffi` с интерфейсом на C: ее загружают из Python, Swift, Go, Ruby, Node или C и вызывают функции без запуска процесса на каждую команду. Руководство лежит в `skills/agent-desktop-ffi`.
Как несколько агентов работают в одной сессии?
Команда `session start --cursor --multi-agent` создает общую сессию, а каждому агенту задается свой `AGENT_DESKTOP_AGENT_ID`. У каждого появляется свой курсор-подсказка с подписью. Снимки остаются общими, поэтому действуйте по ссылкам из собственного `snapshot`.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыMCP-сервер на Swift дает агенту управлять любым приложением macOS: кликать, печатать и читать дерево интерфейса
Open Computer Use
open-computer-use
Открытый MCP-сервер для управления рабочим столом: агент читает состояние приложений и кликает, печатает, скроллит на macOS, Linux и Windows
Плагин и каталог CLI для агентов: генерирует командный интерфейс к GUI-программам вроде GIMP и Blender и ставит готовые через CLI-Hub
MCP-сервер дает агенту управлять окнами и приложениями: он читает экран как структуру и действует по имени элемента
MCP-сервер для macOS: агент двигает мышь, печатает, управляет окнами и снимает экран, когда у приложения нет API
Self-hosted панель для управления несколькими агентами: постановка задач, обзор прогонов, учет трат и подключение по MCP, CLI или REST
Сравнение с похожими
Записи с тем же главным запросом: чем они отличаются.
| Запись | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| agent-desktop (эта запись) | нет | 1 829 | ||
| Open Computer Use | нет | не нужна | 2 756 | MCP-сервер управления рабочим столом на macOS, Linux и Windows |
| Windows-MCP | нет | не нужна | 10 682 | MCP-сервер для управления Windows, работает с файлами и PowerShell |
Коротко о README
В репозитории лежат исходники ядра и адаптера macOS по пакетам Rust, оболочка для npm, библиотека с интерфейсом на C, три скилла с подробными справочниками по командам, документация по формату JSON и частые вопросы, замеры точности поиска элементов и тесты. Главная страница начинается с архитектурной схемы, затем идут установка, права доступа, рабочий цикл агента, полный список команд и таблица поддержки платформ.