remorses/usecomputer

usecomputer – AI 에이전트를 위한 데스크톱 자동화 CLI

무엇인가요 – usecomputer는 크로스플랫폼 명령줄 도구(및 npm 라이브러리)로, AI 에이전트가 실제 컴퓨터 화면과 상호작용할 수 있게 해줍니다. 스크린샷 캡처, 마우스 이동, 클릭, 드래그, 스크롤, 텍스트 입력, 단축키 입력, 심지어 전역 입력 이벤트 스트리밍까지 가능합니다. 무거운 작업은 네이티브 Zig 백엔드에서 처리되므로 설치 후 Node.js 런타임 없이도 실행됩니다.

AI에게 왜 중요한가요 – 현대의 '컴퓨터 사용 에이전트'(Claude, OpenAI, Anthropic, OpenCode 등)는 인지-행동 루프를 안정적으로 닫을 수 있는 방법이 필요합니다:

1. 캡처: 화면(또는 특정 창)을 캡처 → 이미지를 비전 모델에 전달.
2. 결정: 모델의 출력에 따라 무엇을 할지 결정.
3. 실행: 마우스 이동, 클릭, 입력 등 수행.
4. 반복. usecomputer는 이 루프에 정확히 부합하는 CLI 명령어와 TypeScript API를 제공하며, 스크린샷 픽셀 좌표를 실제 화면 좌표로 정확히 변환하는 coord-map 시스템도 제공해 흔한 '몇 픽셀 오차' 문제를 해결합니다.

주요 기능

• 스크린샷: 전체 데스크톱 또는 창 범위에서 캡처, 자동 스케일링(최대 1568px) 및 스크린샷 공간과 화면 공간 간 매핑을 기록하는 coordMap 문자열 제공.
• 마우스: 이동, 클릭(단일/더블), 드래그(직선 또는 2차 베지어 곡선), 스크롤.
• 키보드: type(옵션 지연, stdin 스트리밍, 청크 처리 가능) 및 단일 키 또는 조합 단축키 입력용 press.
• 관찰: 모든 마우스/키보드 이벤트를 Server-Sent Events(SSE)로 스트리밍 – 사용자의 행동을 감시해야 하는 에이전트에 유용.
• 네이티브 Zig 백엔드 – npm install -g usecomputer 후 Node.js 런타임 필요 없음.
• 크로스플랫폼 – macOS, Linux(X11/XWayland), Windows(인터랙티브 데스크톱만 지원). 현재 전역 이벤트 observe 명령은 macOS 전용.
• 에이전트 친화적 그래픽: AGENT_GRAPHICS=kitty로 설정하면 스크린샷이 Kitty Graphics Protocol를 통해 인라인으로 출력되어 OpenCode 같은 에이전트가 별도 파일 읽기 없이 이미지를 받을 수 있음.
• 라이브러리 API – npm 패키지는 CLI의 네이티브 함수(screenshot, click, mouseMove, type, press, observe 등)를 반영하고, 강력한 에디터 지원을 위한 TypeScript 타입을 제공.

일반적인 워크플로우

# 1️⃣ 화면(또는 창) 캡처 및 coord-map 획득
usecomputer screenshot ./screen.png --json
# → {"path":"./screen.png","coordMap":"0,0,1600,900,1568,882",…}

# 2️⃣ PNG를 비전 모델(예: Claude, OpenAI 등)에 전달
#    모델은 행동을 반환 (예: (400,220)에서 클릭)

# 3️⃣ 동일한 coord-map을 사용해 행동 실행
usecomputer click -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"

이 패턴은 드래그, 스크롤, 입력에도 동일하게 적용 가능합니다.

설치

npm install -g usecomputer   # CLI와 TypeScript 라이브러리 설치

macOS에서는 터미널에 접근성 및 입력 모니터링 권한을 부여해야 하며, Linux에서는 X11 DISPLAY가 설정되어 있어야 하며, Windows에서는 인터랙티브 데스크톱 세션에서 실행해야 합니다.

코드에서 사용하기 (TypeScript 예제)

import * as usecomputer from 'usecomputer'

const shot = await usecomputer.screenshot({ path: './tmp.png', display: null, window: null, region: null, annotate: null })
const map = usecomputer.parseCoordMapOrThrow(shot.coordMap)
const point = usecomputer.mapPointFromCoordMap({ point: { x: 400, y: 220 }, coordMap: map })
await usecomputer.click({ point, button: 'left', count: 1 })

모든 함수는 선택적 네이티브 필드에 null을 허용하며, CLI의 인수 구조를 정확히 반영합니다.

누가 사용해야 할까

• 데스크톱을 제어해야 하는 AI 에이전트를 개발하는 개발자 (컴퓨터 사용 도구, 자율 보조, RPA 스타일 봇).
• GUI에서 동작하는 비전-언어 모델을 실험하는 연구자.
• 무거운 UI 자동화 프레임워크 없이도 가볍고 스크립트 가능한 방식으로 macOS/Linux/Windows를 자동화하고 싶은 사람.

관련 생태계

• npx skills add remorses/usecomputer는 OpenCode 같은 에이전트에 스킬을 등록해 스크린샷 → 행동 → 스크린샷 루프를 가르칩니다.
• kitty-graphics-agent 플러그인은 자동으로 AGENT_GRAPHICS=kitty를 설정해 스크린샷을 LLM의 컨텍스트 창에 직접 표시할 수 있게 합니다.
• README에는 OpenAI, Anthropic, OpenCode용 예제 통합이 제공되어 모델의 도구 호출을 usecomputer 액션으로 변환하는 방법을 보여줍니다.

---

위 모든 세부 정보는 리포지토리의 README에서 직접 가져온 것으로, 추가 기능은 추측되지 않았습니다.