agent-desktop이 하는 일: 스크린샷 없는 컴퓨터 유즈
AI에게 컴퓨터를 맡기는 기능을 흔히 컴퓨터 유즈라고 부릅니다. 지금까지 많이 쓰인 방식은 화면을 사진으로 찍어 모델에게 보여 주고, 모델이 사진을 보고 어디를 누를지 좌표로 고르는 식이었습니다. 버튼이 조금만 움직여도 엉뚱한 곳을 누르기 쉽고, 매번 큰 이미지를 모델에 넘겨야 해서 느립니다.
버셀 랩스가 공개한 agent-desktop은 다른 길을 택했습니다. 운영체제는 원래 시각장애인용 화면 낭독기를 위해 창 안의 버튼, 입력칸, 메뉴 이름을 목록으로 내주는데, 이것을 접근성 트리라고 합니다. agent-desktop은 이 목록을 JSON으로 꺼내 요소마다 ref라는 번호표를 붙여 줍니다. 에이전트는 사진을 보는 대신 '버튼, 이름은 일치, 번호표 e26' 같은 글을 읽고 그 번호표로 누릅니다.
중요한 점은 이 도구 안에 AI 모델이 없다는 것입니다. 무엇을 누를지 판단하는 일은 여전히 클로드 코드, 코덱스 같은 에이전트나 사람이 짠 스크립트가 맡고, agent-desktop은 읽기와 누르기만 합니다. 그래서 도구 자체는 무료이고 계정도 필요 없지만, 에이전트를 붙여 쓰면 그 에이전트의 사용량은 따로 듭니다.
저장소는 2월에 만들어졌고 11월 5일 기준 깃허브 별이 1만 5천 개를 넘었습니다. 최근 며칠 깃허브 트렌딩 상위에 계속 올라 있고, 11월 5일에 MCP 서버 기능을 넣은 1.2.0이 나왔습니다. 라이선스는 Apache 2.0입니다.
agent-desktop 설치 방법과 지원 운영체제
설치는 npm 한 줄입니다. Node 18 이상이 있으면 어느 운영체제든 같은 패키지를 받고, 패키지 안에 맥, 윈도우, 리눅스용 실행 파일이 함께 들어 있습니다. 설치 뒤에는 version과 status로 명령이 잡히는지, 권한이 있는지부터 봅니다.
맥은 손쉬운 사용 권한을 따로 켜야 해서 permissions --guide가 설정 화면까지 안내합니다. 윈도우는 권한 창이 없고 터미널과 같은 권한 수준의 앱이면 바로 읽힙니다. 실제로 윈도우 11에서 status를 실행하니 accessibility가 granted로 나왔고, 따로 누른 것은 없었습니다.
npm이 설치 스크립트를 막아 두었다면 경고가 한 줄 뜹니다. 그래도 동작은 하지만, 공식 설치 문서에 따르면 이때는 매번 Node 실행기를 거쳐서 명령마다 100ms 넘게 느려집니다. 빠르게 쓰려면 --allow-scripts=agent-desktop을 붙여 다시 설치하라고 안내합니다. 맥과 리눅스는 brew install agent-desktop도 되고, 윈도우용 Scoop 패키지는 없습니다.
윈도우에서 한 가지 더 알아 둘 것이 있습니다. 실행 파일에 코드 서명이 없어서 브라우저로 직접 받으면 SmartScreen 경고가 뜰 수 있고, 백신이 격리하거나 새로 설치한 윈도우 11의 스마트 앱 컨트롤이 막을 수 있다고 공식 문서에 적혀 있습니다. npm으로 받으면 이 단계를 덜 겪지만, 회사 PC라면 보안 정책부터 보는 편이 좋습니다.
| 운영체제 | 필요 조건 | 읽는 방식 |
|---|---|---|
| macOS | macOS 13 이상, 인텔과 애플 실리콘 | AX API, 손쉬운 사용 권한 필요 |
| Windows | Windows 10 1809 이상 또는 Server 2019 이상, x64와 ARM64 | UI Automation, 로그인한 사용자 화면에서만 |
| Linux | Ubuntu 24.04 이상, X11이나 Wayland | AT-SPI |
README와 윈도우 안내 문서에 나온 지원 조건.
npm install -g agent-desktop
agent-desktop version
agent-desktop status # 운영체제, 권한, 지원 화면 종류
agent-desktop permissions --guide # 맥에서 손쉬운 사용 권한 안내
# 설치 스크립트가 막혀 느릴 때
npm install -g agent-desktop --allow-scripts=agent-desktop윈도우 계산기를 버튼 이름으로 눌러 본 결과
처음 해 본 것은 계산기입니다. launch calc로 계산기를 띄우고 snapshot --app CalculatorApp.exe -i로 누를 수 있는 요소만 읽었더니 39개가 나왔습니다. 숫자 버튼은 1, 2, 3 그대로, 연산 버튼은 곱, 더하기, 일치처럼 윈도우 한국어 화면에 쓰인 이름 그대로 잡혔고, 결과 칸은 '표시는 0'이라는 글로 읽혔습니다.
그다음 1, 2, 곱, 3, 4, 일치 버튼의 번호표를 차례로 click에 넘겼습니다. 여섯 번 모두 ok가 돌아왔고, 다시 읽은 결과 칸은 '표시는 408'로 바뀌어 있었습니다. 계산기 창에도 12 x 34 = 408이 그대로 떠 있었습니다. 기본 설정에서는 마우스 포인터를 옮기지 않고 창 포커스도 가져가지 않아서, 그 사이 다른 창을 써도 됩니다.
기본 동작이 헤드리스라서 그렇습니다. 포인터를 옮겨 누르는 게 아니라 운영체제에 이 버튼을 눌러 달라고 요청하는 방식이라, 계산기가 다른 창 뒤에 있어도 눌립니다. 공식 문서도 다른 창에 가려진 창은 조작할 수 있고, 최소화된 창은 모든 요소가 화면 밖으로 잡혀 restore로 되살린 뒤 다시 읽으라고 안내합니다.
속도는 부르는 방법에 따라 꽤 달랐습니다. npx로 부르면 명령 하나에 4초 안팎이 걸려 클릭 여섯 번에 23.6초가 들었습니다. 같은 스냅샷을 패키지 안의 실행 파일로 바로 부르면 약 1.0초, npx로는 약 6.0초였습니다. 에이전트에 붙여 오래 쓸 생각이면 전역 설치로 실행 파일을 바로 부르는 쪽이 낫습니다.
메모장 글 입력은 type 대신 set-value
두 번째로 메모장에 글을 넣어 봤습니다. 메모장을 읽으면 본문 입력칸이 '텍스트 편집기'라는 이름의 textfield로 나오고, 굵게, 기울임꼴, 테이블 같은 새 메모장의 서식 버튼도 이름으로 잡힙니다. 여기에 type 명령으로 글을 치게 했더니 POLICY_DENIED 오류가 나며 거절됐습니다.
윈도우 안내 문서를 보면 이유가 나옵니다. 윈도우에서 type은 키보드를 실제로 두드리는 방식이라 --headed 옵션을 켜야 하고, 기본 헤드리스 상태에서는 set-value로 글을 넣으라고 적혀 있습니다. 실제로 set-value에 같은 입력칸 번호표와 두 줄짜리 글을 넘기니 약 1.8초 만에 메모장에 그대로 들어갔고, 탭 제목도 첫 줄로 바뀌었습니다.
set-value는 키를 하나씩 누르는 게 아니라 입력칸의 값을 통째로 바꿉니다. 그래서 원래 있던 글은 지워지고 새 글로 바뀌니, 이어 쓰기가 필요하면 기존 값을 먼저 읽어 붙여서 넘겨야 합니다. 비밀번호처럼 남에게 보이면 안 되는 글은 --stdin으로 넘겨 명령 인자에 드러나지 않게 하라는 안내도 README에 있습니다.
PowerShell을 쓰면 번호표를 꼭 작은따옴표로 감싸야 합니다. PowerShell은 @로 시작하는 낱말을 다른 뜻으로 읽어서, 따옴표 없이 넘기면 agent-desktop에 닿기도 전에 사라지고 INVALID_ARGS가 납니다. 이 글의 명령도 모두 따옴표를 붙여 실행했습니다.
agent-desktop launch notepad
agent-desktop snapshot --app notepad.exe -i --compact
# 헤드리스에서는 거절됨 (POLICY_DENIED)
agent-desktop type '@s37y0t69zb1v3g:e1' "hello"
# 입력칸 값을 통째로 바꾸는 쪽은 동작함
agent-desktop set-value '@s37y0t69zb1v3g:e1' "hello"클로드 코드와 코덱스에 붙이는 법: MCP와 스킬
명령을 사람이 하나씩 치는 건 시험용이고, 실제로는 에이전트가 읽고 누르고 다시 읽는 반복을 돌리게 됩니다. 붙이는 길은 세 가지입니다. 가장 간단한 건 에이전트 설정 파일인 AGENTS.md에 agent-desktop을 쓰라는 문장을 넣는 것이고, README에 그대로 복사할 문단이 있습니다.
두 번째는 스킬 설치입니다. npx skills add 명령으로 agent-desktop 스킬을 넣으면 에이전트가 쓰는 순서와 재시도 규칙을 함께 읽습니다. 실행 파일 안에도 같은 안내가 들어 있어서 agent-desktop skills get desktop과 skills get platform을 실행하면 지금 운영체제에 맞는 주의점이 나옵니다.
세 번째가 1.2.0에서 새로 생긴 MCP 서버입니다. agent-desktop mcp를 실행하면 모든 명령이 desktop_snapshot, desktop_click 같은 MCP 도구로 열립니다. MCP를 지원하는 에이전트라면 설정 파일에 아래 몇 줄만 넣으면 되고, --session이나 --headed 같은 옵션을 mcp 뒤에 붙이면 모든 호출에 같이 적용됩니다.
에이전트가 쓸 때 지켜야 할 규칙도 정해져 있습니다. 번호표는 그 스냅샷에서만 유효해서 화면이 바뀌면 STALE_REF가 나고, 그때는 새로 읽어야 합니다. 실패한 명령은 결과 JSON의 retry 값이 safe일 때만 다시 시도하라고 README가 안내합니다. 같은 동작을 무작정 반복해서 엉뚱한 버튼을 두 번 누르는 일을 막으려는 장치입니다.
{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }쓰기 전에 알아 둘 제한과 개인정보
agent-desktop이 읽은 스냅샷에는 창에 떠 있는 글이 그대로 들어갑니다. 메일 제목, 메신저 대화, 파일 이름까지 JSON에 담기고, 그 내용이 에이전트를 거쳐 모델 회사로 넘어갈 수 있습니다. README 첫 부분에도 스냅샷, 클립보드, 스크린샷, 디버그 파일에 개인 화면 내용이 들어갈 수 있으니 공개 로그나 업로드에 섞지 말라는 경고가 있습니다.
윈도우에서는 되는 화면과 안 되는 화면이 꽤 분명합니다. 로그인한 사용자의 일반 화면에서만 동작하고, 잠긴 화면, 로그인 화면, UAC 확인 창, 서비스로 도는 세션은 지원하지 않습니다. 관리자 권한으로 실행된 앱은 일반 터미널에서 읽을 수는 있어도 누를 수는 없어서, 같은 권한의 터미널에서 실행해야 합니다.
크롬이나 일렉트론으로 만든 앱은 처음 읽을 때 요소가 몇 개 안 나올 수 있습니다. 공식 문서는 처음 띄운 뒤 10초에서 25초쯤 지나야 전체 목록이 나온다고 하고, 스냅샷 대기 시간을 늘리라고 권합니다. alt+f4, win+r 같은 단축키는 --force 없이는 거절되고, 컨트롤 알트 딜리트는 아예 보낼 수 없습니다.
버튼 이름을 읽는 방식이라 앱이 접근성 정보를 잘 내줘야 제 몫을 합니다. 이번에 써 본 계산기와 메모장은 이름이 깔끔하게 나왔지만, 공식 문서도 일부 앱 종류에서는 메뉴를 찾지 못할 수 있다고 적어 두었습니다. 화면에 그림만 그리는 프로그램이라면 스크린샷 방식 컴퓨터 유즈가 여전히 필요할 수 있습니다.
스크린샷 방식 컴퓨터 유즈와의 차이
클로드나 챗GPT의 컴퓨터 유즈는 모델이 화면 사진을 보고 직접 판단하는 완성품에 가깝습니다. agent-desktop은 그 사이에서 눈과 손 역할만 하는 부품입니다. 화면 대신 버튼 목록을 주니 모델이 읽을 양이 글 몇 줄로 줄고, 누를 곳을 좌표가 아니라 이름으로 고르니 창 크기나 위치가 바뀌어도 같은 버튼을 찾습니다.
대신 판단은 전부 붙인 에이전트 몫입니다. 무엇을 누를지, 결과가 맞는지 다시 읽어 확인하는 반복을 에이전트가 해야 하고, 그 에이전트의 사용량과 요금도 따로 듭니다. 혼자서 일을 끝내 주는 앱이 아니라, 이미 쓰는 클로드 코드나 코덱스에 데스크톱 앱을 다룰 손을 달아 주는 도구로 보면 맞습니다.
써 볼 만한 사람은 분명합니다. 매일 같은 순서로 누르는 사내 프로그램, 엑셀이나 메모장으로 정리하는 반복 작업, 웹이 아니라 설치형 프로그램에서만 되는 일이 있는 사람입니다. 먼저 계산기처럼 망가질 게 없는 앱에서 snapshot과 click으로 손에 익힌 뒤, 중요한 프로그램은 결과를 매번 사람이 보는 방식으로 시작하는 편이 안전합니다.
근거 [1]