pi-computer-use 소개
AI 에이전트가 실제 업무를 처리하려면 파일이나 API, 터미널 명령만으로는 부족할 때가 많습니다. 사내 전용 프로그램이나 오래된 데스크톱 앱처럼 프로그래밍 인터페이스가 없고 화면(GUI)만 제공하는 소프트웨어가 여전히 많기 때문입니다. 이런 앱을 자동화하려면 사람이 하듯 화면을 보고, 버튼과 글자를 이해한 뒤, 직접 클릭하고 입력해야 합니다. 이것이 최근 주목받는 컴퓨터 유즈(computer use)입니다.
pi-computer-use는 AI 에이전트 런타임인 Pi의 확장(extension)으로, macOS와 Windows에서 에이전트가 데스크톱 앱을 다룰 수 있게 해 줍니다. 설치하면 Pi 에이전트는 열린 앱과 창을 찾고, 창 안에 무엇이 보이는지 관찰하고, 특정 텍스트나 버튼을 검색·검사한 뒤, 클릭·입력·스크롤·대기 같은 행동 을 수행하는 도구를 갖게 됩니다. 한마디로 에이전트에게 데스크톱 소프트웨어를 조작하는 통제된 방법을 제공합니다.
이 확장은 macOS에서는 접근성(Accessibility)과 화면 기록(Screen Recording) 권한을 사용하는 헬퍼 앱으로, Windows에서는 플랫폼 접근성 API로 동작합니다(macOS 14 이상 필요). 데스크톱 창뿐 아니라 CDP로 제어하는 브라우저 페이지도 같은 방식으로 다룰 수 있습니다. 이 글에서는 pi-computer-use가 무엇을 하는 도구인지, 어떤 동작 루프로 앱을 조작하는지, 그리고 설치와 권한 설정을 정리합니다.
pi-computer-use를 언제 쓰면 좋은가
저자들은 pi-computer-use가 앱 API나 MCP 서버를 대체하는 도구가 아니라는 점을 분명히 합니다. 앱에 믿을 만한 직접 연동 수단이 있다면 그것을 먼저 쓰는 편이 안정적입니다. 컴퓨터 유즈는 화면에 떠 있는 앱이 유일한 인터페이스일 때, 즉 API도 MCP도 없는 소프트웨어를 다뤄야 할 때 가장 쓸모가 있습니다. 도구의 성격과 한계를 먼저 짚어 두는 이 안내는 과장 없이 적용 범위를 좁혀 준다는 점에서 오히려 신뢰를 줍니다.
pi-computer-use의 동작 루프
pi-computer-use의 기본 흐름은 관찰과 행동의 반복입니다. 먼저 find_roots 로 데스크톱 창이나 브라우저 페이지 같은 루트(root)를 찾고, observe_ui 로 그 루트를 관찰해 UI 아웃라인과 함께 stateId 를 얻습니다. 이후 search_ui, expand_ui, inspect_ui 로 그 상태를 검색·확장·검사하고, 같은 stateId 를 사용해 act_ui 로 행동을 실행합니다. 아래 그림은 이 다섯 단계 루프를 정리한 것입니다.
여기서 핵심은 관찰이 불변(immutable) 상태로 고정된다 는 점입니다. observe_ui 가 돌려준 stateId 와 요소 참조(@e12 같은)는 그 상태 안에서만 유효하고, 오래된 상태로 조작을 시도하면 stale로 거부됩니다. 이렇게 하면 화면이 그새 바뀌었는데도 낡은 좌표를 클릭하는 사고를 줄일 수 있습니다.
행동은 항상 트랜잭션 형태입니다. 하나 이상의 의도를 act_ui 에 넘기고, 완료 신호가 있다면 같은 트랜잭션에 조건을 붙여 전달 여부를 검증하게 할 수 있습니다.
act_ui({
stateId,
actions: [{ action: "press", ref: "@e12" }],
expect: { text: "Archive completed", until: "present", timeoutMs: 3000 }
})
이 경우 Pi는 플랫폼의 변경 알림 경로를 기다렸다가, 앱이 이벤트를 삼켰다면 실행을 postcondition_failed 로 표시합니다. 검증 결과는 verified, preexisting, failed 로 구분해 보고합니다. 데스크톱뿐 아니라 브라우저를 다룰 때는 launch_browser, navigate_browser, evaluate_browser 도구가 함께 제공됩니다. 전체 도구 레퍼런스는 저장소의 docs/usage.md 에 정리되어 있습니다.
pi-computer-use 설치와 권한
설치는 Pi의 확장 설치 명령으로 진행합니다.
pi install npm:@injaneity/pi-computer-use
설치 후 Pi를 실행하고 플랫폼 설정 흐름을 완료합니다. macOS에서는 헬퍼 앱(~/Applications/pi-computer-use.app)에 접근성과 화면 기록 권한을 부여해야 하며, 설정 흐름이 헬퍼를 먼저 등록하므로 두 권한 창에 항목이 이미 나타나 있습니다. 토글을 켠 뒤 다시 확인(Recheck)을 선택하면 됩니다. Windows에서는 대화형 데스크톱 세션에서 사용하며, macOS 헬퍼 앱이나 권한 흐름 없이 플랫폼 접근성 API를 씁니다. Pi 안에서 /computer-use 를 실행하면 현재 활성 설정과 그 출처를 확인할 수 있습니다.
pi-computer-use의 라이선스
pi-computer-use는 MIT 라이선스로 공개되어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
pi-computer-use 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 