agent-desktop이란? 코딩 에이전트가 맥, 윈도우 앱을 직접 누르게 하는 Vercel 무료 CLI

• agent-desktop은 Claude Code, Codex 같은 코딩 에이전트가 맥, 윈도우, 리눅스 데스크톱 앱을 직접 읽고 누를 수 있게 해 주는 명령줄 도구임. Vercel Labs가 10월 31일 공개함

• 무료(Apache-2.0)이고 npm install -g agent-desktop 한 줄로 설치함. 에이전트를 돌리는 모델 비용만 따로 듦

• 화면을 찍어 좌표를 짐작하는 대신, 운영체제가 화면 낭독기용으로 내주는 버튼 목록을 읽어서 이름으로 누름. 그래서 빠르고 토큰을 덜 씀

• 쓸 만한 곳은 내가 만든 데스크톱 앱 테스트, API 없는 업무 프로그램 반복 입력임. 게임이나 그림 위주 앱처럼 버튼 정보를 안 내주는 앱은 못 다룸

• 공개 나흘 만에 GitHub 스타가 약 9천 개 늘었음. 다만 독립 성능 평가는 아직 없고, 권한을 넓게 주는 만큼 보안 걱정도 함께 나옴

agent-desktop이란

에이전트에게 데스크톱 앱을 다룰 손을 달아 주는 도구임. 스스로 판단하는 AI는 들어 있지 않음.

• 웹 브라우저를 다루는 Vercel의 agent-browser를 데스크톱 전체로 넓힌 도구임. 발표 문구도 "agent-browser, for your whole computer"였음

• 에이전트는 셸 명령으로 부름. 명령 하나가 JSON 결과를 한 번 내고 끝나서 어느 에이전트에서나 쓸 수 있음

• 명령은 60개임. 앱 실행과 창 관리, 클릭과 입력, 알림 읽기, 클립보드, 스크린샷까지 다룸

• Rust로 만든 실행 파일 하나라 따로 깔 것이 없음. 프로그램 안에서 직접 부를 수 있는 C 라이브러리도 함께 줌

스크린샷 방식과 무엇이 다른가

Claude나 OpenAI의 컴퓨터 유즈(AI가 사람처럼 화면을 보고 마우스를 움직이는 기능)는 대부분 화면을 찍고 좌표를 짐작해 누름. agent-desktop은 버튼 이름표를 읽고 누름.

• 운영체제는 시각장애인용 화면 낭독기를 위해 창마다 버튼, 입력칸, 메뉴 목록을 내줌. 이 목록을 접근성 트리라고 부름

• agent-desktop은 이 목록을 읽어 누를 수 있는 요소마다 @s8f3k2p9:e8 같은 번호표를 붙여 줌

• 에이전트는 번호표로 누르고, 목록을 다시 읽어 결과를 확인함. 해상도, 테마, 창 위치가 바뀌어도 덜 틀림

• 기본 동작은 백그라운드임. 마우스 포인터를 움직이지 않고 창 포커스도 뺏지 않아서 사람이 옆에서 계속 일할 수 있음

• 복잡한 앱은 큰 틀만 먼저 읽고 필요한 영역만 펼쳐 봄. 개발자는 이 방식으로 토큰을 78~96% 아낀다고 밝혔지만 독립 측정은 아님

설치와 사용법 (Claude Code, Codex)

npm으로 깔고, 에이전트에게 사용 설명서를 먼저 읽히면 됨.

• 설치: npm install -g agent-desktop

• 상태 확인: agent-desktop status로 운영체제, 권한, 쓸 수 있는 기능을 봄

• 에이전트에 가르치기: npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop으로 스킬을 넣거나, CLAUDE.md나 AGENTS.md에 "먼저 agent-desktop skills get desktop을 읽고 따르라"는 한 줄을 적음

• 맥은 손쉬운 사용 권한이 필요함. agent-desktop permissions --guide가 어느 앱에 권한을 줄지 알려 줌

• 기본 흐름은 읽기, 누르기, 다시 읽기임

agent-desktop snapshot --app Finder -i      # 누를 수 있는 요소와 번호표 읽기
agent-desktop click @s8f3k2p9:e8            # 번호표로 누르기
agent-desktop snapshot --app Finder -i      # 다시 읽어 결과 확인

지원 운영체제와 요구 사항

세 운영체제 모두 되지만, 리눅스는 아직 빈 곳이 있음.

• 맥: macOS 13 이상, 인텔과 애플 실리콘

• 윈도우: Windows 10 1809 이상, x64와 ARM64. 터미널과 같은 권한 수준의 앱은 따로 허락이 필요 없음

• 리눅스: Ubuntu 24.04 이상. 접근성 서비스(AT-SPI)가 도는 그래픽 세션이 있어야 함

  • Wayland에서는 마우스 입력과 창 조작이 제한됨

• 키를 누른 채로 두는 명령 4개(key-down, key-up, mouse-down, mouse-up)는 아직 막혀 있음

• 윈도우용 실행 파일은 서명이 없어 SmartScreen이나 백신이 막을 수 있다는 지적이 있음

agent-desktop 활용법, 어디에 쓰면 좋은가

브라우저 밖에 있는데 API가 없는 일에 가장 잘 맞음.

• 내가 만든 데스크톱 앱 테스트: 코딩 에이전트가 고친 뒤 앱을 직접 켜서 눌러 보고 결과까지 확인함

  • 일렉트론, 크롬 계열 앱은 agent-desktop이 디버깅 포트를 열어 띄우고, 안쪽 웹 화면은 agent-browser가 맡는 식으로 나눠 씀

• API 없는 업무 프로그램 반복 입력: 사내 윈도우 프로그램이나 오래된 업무용 앱에 같은 값을 여러 번 넣는 일. 기존 RPA 도구 대신 쓸 수 있음

• 개발 중 잔일: 시스템 설정 확인, 알림 읽고 닫기, 파일 대화상자에서 파일 고르기처럼 터미널 밖으로 나가야 하던 일

• 여러 에이전트 동시 작업: 에이전트마다 화면에 자기 커서를 띄우고 서로 다른 앱을 나눠 맡길 수 있음 (session start --cursor --multi-agent)

• 자기 프로그램에 넣기: C 라이브러리를 Python, Swift, Go 등에서 바로 불러 자동화 기능을 붙임

쓰기 어려운 곳과 보안 주의점

버튼 정보를 내주지 않는 화면은 보이지 않음. 권한도 넓게 주는 만큼 쓰는 기기를 골라야 함.

• 게임, 캔버스로 직접 그리는 앱, 접근성을 꺼 둔 일렉트론 앱은 거의 못 다룸

  • 해커뉴스에서는 줌(Zoom) 회의 화면처럼 자체 제작한 버튼은 이름표가 없거나 엉망이라는 사례가 나옴

• 클릭은 정확해도 화면에 제대로 보이는지는 확인 못 함. 흰 바탕에 흰 글씨 같은 문제는 여전히 스크린샷으로 봐야 한다는 지적이 있음

• 값이 바뀌었다고 저장까지 된 것은 아님. 텍스트 편집기 칸에 글을 넣어도 파일은 그대로였다는 실험 후기가 있음

• 맥에서는 손쉬운 사용 권한이 터미널 앱 통째로 들어감. 그 터미널에서 도는 다른 프로그램도 같은 힘을 갖게 됨

• 읽어 온 화면 목록, 클립보드, 스크린샷에 개인 정보가 그대로 담김. 공식 문서도 공개 로그에 남기지 말라고 함

• 메일, 비밀번호 관리자가 있는 평소 기기보다 테스트용 가상 머신에서 쓰라는 후기가 있음. 맥 가상 머신 격리 기능은 개발 중임

커뮤니티 반응

관심은 크지만, 아직 써 보고 평가한 글보다 소개 글이 훨씬 많음.

• GitHub 스타는 10,844개(11월 3일 확인)이고, 공개 뒤 나흘 동안 하루 1,300~2,700개씩 늘며 Rust 트렌딩 1위에 올랐음

• 원래는 개인 개발자가 2월에 시작한 프로젝트였음. 5월 해커뉴스 소개글이 99점을 받았고, 10월 말 Vercel Labs 저장소로 옮겨지며 1.0이 나옴

• 그때 해커뉴스 반응은 갈렸음

  • "처음부터 스크린샷 말고 이 목록을 썼어야 했다"며 반기는 의견이 많았음

  • 리눅스는 앱마다 접근성 지원이 들쭉날쭉해서 믿고 쓰기 어렵다는 반론이 나옴

  • 같은 이름, 같은 방식의 도구를 만들었다는 개발자도 나왔음. 비슷한 시도가 여럿임

• X에서는 Vercel CEO 기예르모 라우치가 "모든 데스크톱에 에이전트를"이라며 공유함. 반면 Cua Driver나 마이크로소프트 Mage와 비교해 달라, 믿을 만한 성능 평가를 내놓으라는 요구가 이어짐

• 어떤 에이전트가 어느 앱까지 만질 수 있는지 통제할 방법을 묻는 목소리도 나옴. 앱별로 허용 범위를 정하는 정책 기능이 개발 중임

• 국내에는 5월 PyTorch 한국 사용자 모임에 올라온 소개글 하나 말고는 아직 정리된 글이 없음

자주 묻는 질문

• agent-desktop은 무료인가: 무료임. Apache-2.0이라 회사에서도 쓸 수 있음

• agent-browser와 뭐가 다른가: agent-browser는 웹 페이지, agent-desktop은 데스크톱 앱을 다룸. 일렉트론 앱은 둘을 함께 씀

• Claude Code에서 쓸 수 있나: 쓸 수 있음. 셸 명령을 부를 수 있는 에이전트면 다 됨

• MCP 서버가 필요한가: 필요 없음. 셸 명령과 스킬 문서로 씀

• 한국어 앱에서도 되나: 공식 문서에 한국어 입력이나 국내 앱 지원 언급은 없음. 앱이 접근성 정보를 얼마나 내주느냐에 달림