agent-desktop: 접근성 트리로 PC 화면을 조작하는 에이전트용 CLI
운영체제의 접근성 트리를 JSON으로 읽고 UI 요소를 참조해 클릭·입력하는 AI 에이전트용 데스크톱 제어 CLI·C 라이브러리예요.
주요 기능
- 앱 화면의 조작 가능한 요소에 스냅샷별 참조를 붙여 좌표 추측 대신 대상으로 지정해요.
- 클릭·입력·스크롤, 창 관리, 알림·클립보드 조회와 화면 캡처 명령을 제공해요.
- JSON 결과와 오류 정보를 반환하며 Rust 네이티브 CLI 또는 C ABI를 통해 다른 프로그램에 통합해요.
구조
Rust workspace는 공통 코어와 macOS·Windows·Linux 어댑터, CLI·FFI로 나뉩니다. CLI 진입점은 운영체제에 맞는 어댑터를 구성하고 권한·명령 정책을 검사한 뒤 실행 결과를 JSON으로 출력해요. 자체 LLM이나 채팅 화면은 없으며 관찰→행동→검증 판단은 호출하는 에이전트가 맡습니다.
누구에게 쓸모 있나요
기존 AI 에이전트에 데스크톱 앱 조작 기능을 붙이려는 개발자와 OS별 UI 자동화 도구를 검토하는 사용자.
설치 전 준비
- npm 설치 경로 또는 운영체제·CPU에 맞는 공식 네이티브 릴리스가 필요해요.
- 소스 빌드는 Rust 1.89 이상과 OS별 개발 도구가 필요해요. 확인한 Cargo workspace 버전은1.0.2이며 배포 채널 최신 버전과 동일하다고 단정하지 않았어요.
- 실제 사용 전 대상 앱의 접근성 지원과 OS 권한을 확인해야 해요.
- macOS·Windows·Linux, 공식 패키지는 x64·ARM64를 안내해요.
- macOS: 접근성 권한, 화면 캡처 시 화면 기록 권한 등이 필요해요.
- Windows: 터미널과 같은 권한 수준 앱은 별도 접근성 허가 없이 동작하도록 설계됐어요.
- Linux: 사용자 그래픽 세션과 AT-SPI가 필요하며 GNOME/X11/Wayland별 기능 차이가 있어요.
설치 방법
공식 npm 경로
문서상 설치 예시예요. 이번 등록에서는 실행하지 않았어요. 설치 스크립트 허용이나 운영체제 권한 부여는 별도 검토가 필요해요.
npm install -g agent-desktop
agent-desktop version사용 방법
- 처음에는 status·permissions 등 상태 조회로 지원 기능과 권한을 확인해요.
- 대상 앱을 선택해 snapshot을 읽고 반환된 참조로 필요한 UI 동작을 요청한 뒤 다시 관찰해요.
- 화면이 바뀌어 참조가 오래됐거나 대상이 모호하면 새 스냅샷으로 대상을 다시 지정해요.
비용과 API 키
Apache-2.0 공개 도구예요. 이를 호출하는 AI 모델·에이전트 서비스 비용은 별도이며 구독 제공이나 무료 모델 호출을 포함하지 않습니다.
라이선스
루트 LICENSE와 Cargo manifest에서 Apache-2.0을 확인했어요. 배포 시 라이선스와 해당 고지 조건을 준수해야 하며 상표권·무보증 조건은 별도예요.
주의사항과 알려진 이슈
- Windows 바이너리는 미서명이며 공식 문서도 SmartScreen·백신·Smart App Control에서 경고나 차단 가능성을 설명해요. 보안 기능을 끄거나 경고를 우회하는 설치 지침은 제공하지 않습니다.
- 관리자 권한 앱에 입력하려면 상승된 실행 권한이 필요하다고 문서에 나옵니다. 모든 앱을 제어할 수 있다는 뜻이 아니며 불필요한 권한 확대를 피해야 해요.
- 접근성 트리·창 제목·클립보드·알림·스크린샷·추적 파일에 개인정보가 포함될 수 있어요. 공개 로그·업로드를 피하고 보관 범위를 제한해야 해요.
- 네이티브 CLI와 선택 JEV 보조 기능을 구분해야 해요. JEV는 화면 설명을 설정된 모델 공급자에게 보낼 수 있어 외부 전송 검토가 필요해요.
- 기본 접근성 동작과 물리 입력을 허용하는 headed 모드는 달라요. 앱·플랫폼별 미지원 기능과 실제 클릭 결과는 별도 검증해야 해요.
확인 범위
확인 날짜: 2026-11-03
확인 커밋: 9eb9b296192fcb70bda25e918cd6dd66abfa3d0d
확인한 범위: 공식 GitHub 커밋·README·Cargo manifest·설치 및 개인정보 문서·라이선스·CLI 진입 코드를 정적으로 확인했어요. 기존30개 저장소와 정규화 비교 후 신규 등록했어요.
확인 한계: 대상 프로그램 설치·실행·권한 승인·계정 연결·모델 호출은 하지 않았어요. 앱별 호환성·성능·전체 보안 감사·최신 릴리스 채널은 미검증이에요.