agent-desktop — AI가 PC 앱을 직접 누르는 무료 도구, 스크린샷 없이 쓰는 법

2026년 11월 5일 확인 · 최신 버전 v1.1.0(2026-11-03 배포, npm agent-desktop 1.1.0) · 깃허브 별 14,470개(하루 사이 +2,463개, 같은 날 오후 다시 찍은 화면에서는 15.2k) · Apache-2.0 라이선스 · macOS · Windows · Linux

매일 같은 버튼을 하나씩 눌러야 하는 PC 업무가 있다면, agent-desktop은 그 클릭을 AI가 대신 하게 해 주는 무료 오픈소스입니다. 화면을 찍어 그림을 읽는 대신, 앱이 운영체제에 알려 주는 버튼 · 입력 칸 목록을 읽습니다. 아래 내용은 11월 5일에 저장소 README를 직접 열어 확인한 것이고, 이미지도 그날 원본 페이지를 다시 찍은 화면입니다.

AI가 PC 앱을 직접 누르는 무료 도구, 하루 만에 별 +2,463

agent-desktop은 어떤 도구인가요?

AI 에이전트가 데스크톱 앱을 보고 조작하게 해 주는 명령줄 도구(CLI)이자 C 라이브러리입니다. Vercel Labs가 만들었습니다.

agent-desktop 깃허브 저장소 첫 화면 — Apache-2.0 license, 별 15.2k (2026-11-05 오후 촬영)

README 첫 줄 설명은 "AI 에이전트를 위한 컴퓨터 유즈: 운영체제 접근성 트리로 macOS · Windows · Linux 데스크톱 앱을 보고 조작한다"입니다. 중요한 점은 agent-desktop 안에 AI 모델이 없다는 것입니다. 무엇을 누를지는 내가 쓰는 AI 에이전트가 정하고, agent-desktop은 목록을 보여 주고 클릭을 실행하는 손 역할만 합니다.

항목	내용
만든 곳	Vercel Labs
라이선스	Apache-2.0 (무료 오픈소스)
지원 운영체제	macOS 13 이상 · Windows 10 1809 이상 · Ubuntu 24.04 이상
명령 수	이름 60개(실제로 동작하는 명령 56개)
형태	CLI + C 라이브러리, MCP 서버로도 실행 가능

3개 운영체제, 명령 60개, Apache-2.0

화면을 찍지 않는데 버튼 위치는 어떻게 아나요?

앱의 접근성 트리를 읽어서 압니다. README도 "스크린샷이나 픽셀 매칭 없이"라고 분명히 적고 있습니다.

README 첫머리 — 스크린샷 · 픽셀 매칭 없이 접근성 트리를 JSON으로, 개인 정보 경고, 설치 명령

접근성 트리는 화면 낭독기 같은 보조 기술을 위해 앱이 운영체제에 알려 주는 요소 목록입니다. 버튼, 입력 칸, 목록 항목마다 역할과 이름이 들어 있습니다. agent-desktop은 이 목록을 JSON으로 돌려주고, 누를 수 있는 요소마다 ref라는 번호를 붙입니다. AI는 그 번호를 골라 누르거나 글자를 넣습니다.

운영체제마다 읽는 통로는 다릅니다.

운영체제	쓰는 접근성 API
macOS	AX API
Windows	UI Automation
Linux	AT-SPI

설치하고 쓰는 순서는 어떻게 되나요?

npm 한 줄로 설치하고, "목록 받기 → 누르기 → 다시 확인" 세 단계를 반복합니다.

설치 · 권한 확인 · 스킬 붙이기

npm install -g agent-desktop으로 설치합니다. macOS · Linux는 brew install agent-desktop도 됩니다.
agent-desktop status로 플랫폼과 권한을 확인합니다.
macOS는 손쉬운 사용(Accessibility) 권한이 필요합니다. agent-desktop permissions --guide가 허용 과정을 안내합니다.
agent-desktop snapshot --app Finder -i로 누를 수 있는 요소 목록을 받습니다.
agent-desktop click @s8f3k2p9:e8처럼 목록에 나온 ref를 넣어 누릅니다.
다시 snapshot을 실행해 화면이 바뀌었는지 확인합니다.

README Quick start — snapshot, click, snapshot과 JSON 결과 예시

README의 예시 결과를 보면 Finder 창에서 ref 59개를 찾았고, "Documents" 항목에 @s8f3k2p9:e8이라는 ref와 누를 수 있는 동작(Click)이 붙어 있습니다. 쓸 때 알아 둘 규칙도 함께 적혀 있습니다.

ref에는 스냅샷 번호가 붙어 있어야 합니다. @e8처럼 짧게 쓰면 INVALID_ARGS 오류가 납니다.
그사이 화면이 바뀌었으면 STALE_REF 같은 오류가 납니다. 새로 스냅샷을 찍고 그 ref를 씁니다.
기본은 마우스 포인터를 움직이지 않고 조작합니다. 실제 입력이 필요하면 --headed를 붙입니다.
PowerShell에서는 ref를 '@s8f3k2p9:e8'처럼 작은따옴표로 감쌉니다.

snapshot으로 목록 받기 → click @ref로 누르기 → snapshot으로 다시 확인

AI 코딩 도구에는 어떻게 붙이나요?

스킬로 설치하거나, AGENTS.md에 몇 줄을 적거나, MCP 서버로 붙입니다.

README For AI agents — skills get, npx skills add, AGENTS.md 예시

스킬 설치: npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
프로그램 안에 든 안내서 보기: agent-desktop skills get desktop(쓰는 순서 · ref · 확인 · 재시도 규칙), agent-desktop skills get platform(운영체제별 차이)
MCP로 붙이기: agent-desktop mcp를 실행하면 모든 명령이 desktop_snapshot, desktop_click 같은 MCP 도구가 됩니다.

명령은 보기(snapshot · find · screenshot 등), ref 조작(click · type · scroll 등), 키보드 · 마우스, 앱 · 창 관리, 알림, 클립보드, 대기, 세션, 시스템으로 나뉩니다.

README Commands와 Platform support 표 — 명령 60개, 운영체제별 요구 사항

쓸 때 조심할 점은 무엇인가요?

스냅샷 같은 출력물에 개인 정보가 그대로 담길 수 있습니다. README 첫머리에서 따로 경고하는 부분입니다.

스냅샷엔 개인 정보도 담긴다 — 공개 로그 · 업로드 금지

출력물 관리: 스냅샷, 클립보드 읽기, 스크린샷, 명령 출력, 디버그 파일에는 화면 속 개인 내용이 들어갈 수 있습니다. 공개 로그나 업로드에 넣지 않습니다.
비밀 값 입력: type · set-value · clipboard-set은 --stdin으로 글자를 받을 수 있어 명령 인자에 남지 않습니다. README는 비밀 값을 넣는 단계를 따로 실행하라고 권합니다. 여러 명령을 묶는 batch JSON의 글자는 명령 인자에 그대로 보입니다.
재시도: 실패한 명령은 결과의 error.disposition.retry가 safe일 때만 다시 시도하라고 적혀 있습니다.
권한: macOS는 손쉬운 사용 권한을 줘야 동작합니다. 어떤 앱을 맡길지 먼저 정해 두는 게 좋습니다.

한 번에 정리하면

항목	내용
무엇	AI 에이전트가 데스크톱 앱을 누르게 해 주는 CLI · C 라이브러리
방식	스크린샷 대신 접근성 트리를 JSON으로 읽고 ref로 조작
설치	`npm install -g agent-desktop` → `agent-desktop status`
쓰는 순서	snapshot → click @ref → snapshot으로 확인
주의	출력물에 개인 정보, 공개 로그 · 업로드 금지

출처

agent-desktop 저장소 · README: https://github.com/vercel-labs/agent-desktop (2026-11-05 확인)
공식 문서: https://agent-browser.dev/desktop
화면: 위 저장소 페이지를 2026-11-05에 다시 찍은 것
영상: AItoZ 쇼츠 https://youtube.com/shorts/2yWoiU8xYK8