<div align="center">
<h1>computer-use-linux</h1>
<p><strong>AI 에이전트를 위한 네이티브 Linux 데스크톱 제어 기능 — MCP, Pi 네이티브 도구 및 CLI를 통해 제공됩니다.</strong></p>
<p>
<a href="https://github.com/agent-sh/computer-use-linux/actions/workflows/ci.yml"><img src="https://github.com/agent-sh/computer-use-linux/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://crates.io/crates/computer-use-linux"><img src="https://img.shields.io/crates/v/computer-use-linux.svg" alt="crates.io"></a>
<a href="https://www.npmjs.com/package/@agent-sh/computer-use-linux"><img src="https://img.shields.io/npm/v/@agent-sh/computer-use-linux.svg" alt="npm"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>
</div>
회사용 모델을 운영하고 계신가요? Tiyuvta는 하드웨어 또는 클라우드 계정에서 모델 선택, 배포 및 최적화, 그리고 파인튜닝(fine-tuning)에 도움을 줍니다.
computer-use-linux는 AI 에이전트에게 로컬 Linux 데스크톱에 대한 실제적이고 구조화된 제어 기능을 제공합니다. 여기에는 의미론적 AT-SPI 접근성 트리(semantic AT-SPI accessibility trees), 경계가 지정된 스크린샷(bounded screenshots), 합성기 인식 창 타겟팅(compositor-aware window targeting), Wayland/X11 입력 합성(input synthesis), 단일 왕복 후속 조치 검증(single-round-trip post-action verification), 그리고 GNOME, KDE Plasma/KWin, Hyprland, niri, COSMIC, i3, X11/EWMH 전반에 걸친 클릭 가능한 온스크린 활동 표시기(click-through on-screen activity indicator)가 포함됩니다.
빠른 시작 (Quick start)
사용하는 에이전트 또는 셸 워크플로우에 맞는 설정을 선택하세요:
| 호스트 / 워크플로우 | 설치 명령어 |
|---|
| Claude Code (플러그인 + 스킬) | claude plugin marketplace add agent-sh/computer-use-linux && claude plugin install computer-use-linux@computer-use-linux |
| ... | |
데스크톱 준비 상태를 셸에서 확인하세요 (npm install -g @agent-sh/computer-use-linux, ./install.sh, 또는 cargo install computer-use-linux를 통해 CLI를 PATH에 설치한 후): | |
computer-use-linux doctor | jq .readiness
computer-use-linux setup
computer-use-linux setup-window-targeting
플러그인 전용 또는 Pi 전용 설치 시: Claude Code / Codex 플러그인 런처와 pi install은 개인 캐시된 바이너리를 관리하며, computer-use-linux를 PATH에 추가하지 않습니다. 따라서 에이전트에서 MCP의 doctor / setup_accessibility / setup_window_targeting 도구(또는 Pi에서는 computer_use_linux_doctor)를 직접 실행하거나, 셸 서브커맨드를 PATH에 추가하고 싶을 때 위 CLI도 함께 설치해야 합니다.
이 Rust 크레이트는 computer-use-linux로, 그리고 npm 패키지는 @agent-sh/computer-use-linux로 게시되었습니다. 사전 구축된 x86_64 및 aarch64 리눅스 바이너리는 최신 릴리스와 함께 제공됩니다.
에이전트가 실제 마우스, 키보드 또는 포커스된 창에 절대 접근하지 않는 격리된(isolated) 데스크톱이 필요한가요? 이 프로젝트와 함께 형제 프로젝트인 agent-workspace-linux를 사용하세요.
개요 (What this is)
computer-use-linux는 리눅스 데스크톱 제어를 위한 Rust MCP 서버 및 CLI입니다. 이 도구는 세 가지 바이너리를 제공합니다. 주요 computer-use-linux 서버/CLI, COSMIC용 Wayland 최상위(toplevel) 헬퍼인 computer-use-linux-cosmic, 그리고 클릭을 통과하는 활동 오버레이인 computer-use-linux-indicator입니다. 모든 MCP 호스트(Claude Code, Codex CLI, Codex Desktop의 리눅스 빌드, Pi Coding Agent, Hermes Agent, Claude Desktop 또는 사용자 자체 클라이언트)는 이를 실행하여 접근성 트리(accessibility trees)를 검사하고, 창을 나열 및 포커스하며, 스크린샷을 찍고, 클릭하고, 드래그하고, 스크롤하고, 타이핑하며, 의미론적 접근성 액션(semantic accessibility actions)을 호출할 수 있습니다.
대부분의 computer-use MCP 서버는 macOS 전용입니다 (AppKit, AXUIElement, CGEvent에 의존합니다). 리눅스를 대상으로 하는 소수의 도구들은 X11 루트 창을 대상으로 xdotool을 구동하거나 스크린샷을 이용한 OCR(광학 문자 인식)을 수행하는 방식으로 작동합니다. 이 도구를 차별화하는 다섯 가지 특징은 다음과 같습니다:
- Wayland가 실제로 작동합니다. 포인터 동작은 Wayland에서
/dev/uinput 또는 org.freedesktop.portal.RemoteDesktop을 사용하며, 폴백(fallback)으로는 ydotool / ydotoold를 사용합니다. 문자열 텍스트는 Plasma의 KDE 클립보드 통합, 호환 가능한 Wayland 컴포지터에서의 wtype, 그리고 ydotool이 설치된 GNOME을 포함한 다른 Wayland 세션에서의 포털 키심(keysyms)을 선호합니다. 포털 텍스트 시작 또는 변환 오류는 ydotool을 통해 텍스트를 재전송하지 않고 호출에 실패합니다. 순수 ydotool 텍스트는 인쇄 가능한 ASCII, 탭, 줄 바꿈만 허용하며, 물리적인 US 키 위치가 활성 레이아웃 하에서 다른 텍스트를 생성할 수 있습니다. 스크린샷은 GNOME Shell DBus 스크린샷 방법을 사용하고, 그렇지 않으면 org.freedesktop.portal.Screenshot을 사용합니다. 이후 네이티브 X11 세션에서는 루트 창의 GetImage(디바이스 픽셀, 툴킷 스케일링 없음)를 사용하며, 마지막으로 DBus 경로가 거부되는 백그라운드/systemd 컨텍스트용으로는 gnome-screenshot을 실행합니다.
- 창 타겟팅이 컴포지터 인식적입니다(compositor-aware). 창 레지스트리는 GNOME Shell 확장, GNOME Shell Introspect, COSMIC Wayland helper, KWin DBus 스크립팅, Hyprland의
hyprctl, niri IPC 소켓, i3 IPC, 그리고 일반적인 X11/EWMH 순서로 시도한 후, 어떤 백엔드가 성공했는지 또는 각 백엔드가 실패한 이유를 정확하게 보고합니다. 터미널 창은 제어하는 TTY와 포그라운드 프로세스로 풍부해져 에이전트가 "pytest를 실행 중인 터미널"을 직접 타겟팅할 수 있습니다.
- 우선 의미론적 선택자(Semantic selectors)를 사용하고, 필요할 때만 픽셀 좌표를 사용합니다.
click, perform_action, set_value와 같은 도구는 AT-SPI 기반의 role / name / text / states 선택자 또는 element_index 값을 허용하며, 모든 변경(mutating) 도구는 동일한 왕복 과정에서 작업 후 스크린샷과 업데이트된 접근성 트리(accessibility tree)를 반환할 수 있습니다.
픽셀 좌표는 렌더링 전용 표면(캔버스, 게임, ATK가 없는 X 클라이언트)에서 계속 사용할 수 있습니다.
- 인간에게는 보이지만 스크린샷에는 보이지 않습니다. 에이전트가 작동하는 동안
computer-use-linux-indicator는 개별 에이전트 커서 이동(per-agent cursor glide), 클릭 리플, 키캡/타이핑 배너, 화면 가장자리 빛(screen-edge glow), 상태 알약(status pill)을 포함한 클릭 투명 오버레이를 렌더링하며 — 스크린샷이 읽히기 전에 공유 캡처 잠금(shared capture lock) 하에 자동으로 숨겨집니다.
- 단일 JSON 준비 상태 보고서.
computer-use-linux doctor는 플랫폼, 포털(portals), AT-SPI, 창 관리(windowing), 입력(input)을 다루고 명시적인 차단 요소(blockers)와 권장 다음 단계가 포함된 readiness 요약을 담은 구조화된 문서를 반환합니다. MCP 호스트는 이 내용을 구문 분석(parsing prose) 없이 사용자에게 렌더링하거나 표시할 수 있습니다.
이 크레이트(crate)는 네이티브 컴퓨터 사용 기능(Computer Use feature)을 위해 이 백엔드를 번들링하는 codex-desktop-linux (Codex Desktop의 Linux 배포판)에서 추출되었습니다. 이 독립형 레포지토리(repo)가 상위 스트림(upstream)입니다.
MCP 도구 및 기능
| 카테고리 | 도구 | 기능 설명 |
|---|
| 진단 및 설정 | doctor | 단일 샷(Single-shot) JSON 준비 상태 보고서 (플랫폼, 포털, 접근성, 창 관리, 입력, 준비 상태 요약 및 기능 지도). |
| ... | | |
원 트립(one round trip) 내 후속 조치 관찰
모든 상태 변경 도구(click, drag, scroll, press_key, type_text, perform_action, set_value, activate_window, move_window, resize_window)는 선택적 후속 조치 관찰 매개변수(optional post-action observation parameters)를 받아, 하나의 MCP 도구 호출 내에서 동작과 그 검증이 완료되도록 합니다.
screenshot_after: true | "screen" | "window" | false — 액션이 전송되고 표시기 오버레이가 숨겨진 후 캡처를 수행합니다 (true 또는 "screen"은 전체 데스크톱을 의미하며, "window"는 액션의 대상 창에 맞춰 잘리거나 대상이 지정되지 않은 경우 포커스된 창을 기준으로 자릅니다).format, quality, scale, max_width, max_height, max_bytes — screenshot 및 get_app_state와 동일한 스크린샷 페이로드 제어 기능을 사용합니다.include_tree: true — 최신 압축된 AT-SPI 접근성 트리(accessibility tree)를 포함하고 캐시된 element_index 값을 업데이트합니다.
후속 액션 캡처가 성공하면, 이미지는 JSON 액션 요약 및 screenshot 메타데이터와 함께 첫 번째 MCP image 콘텐츠 블록으로 반환됩니다. 만약 액션이 성공적(ok: true)이지만 후속 액션 스크린샷이나 트리 캡처만 실패한 경우, ok는 true를 유지하며 오류는 screenshot_error / accessibility_error에 보고되고 message에 추가됩니다.
스크린샷 크기 조정 및 좌표 스케일링
스크린샷 페이로드는 MCP 호스트로 반환되기 전에 기본적으로 크기가 제한됩니다: 최대 너비/높이 1920px 및 이미지 바이트 2 MiB이며, 호출자가 더 많은 것을 요청하더라도 하드캡(hard caps)이 적용됩니다. 더 많은 세부 정보가 필요한 에이전트는 max_width, max_height, max_bytes, scale, format: "jpeg", 또는 quality를 전달할 수 있으며, 가급적 창 대상 지정이나 자르기 기능을 사용하는 것이 좋습니다. PNG가 기본값으로 유지되며, JPEG는 바이트 제한이 추가적인 크기 조정을 강제하기 전에 호출자가 손실 없는 픽셀(lossless pixels)을 더 작은 페이로드와 교환할 수 있게 합니다. 반환되는 스크린샷 메타데이터에는 coordinate_width, coordinate_height, scale, format, 및 quality가 포함되어 있어, 호출자가 다운스케일된 미리 보기에서 데스크톱 좌표 픽셀로 변환할 수 있습니다.
요소 인덱스 또는 선택자를 통한 일반적인 왼쪽 클릭의 경우, 인식된 네이티브 AT-SPI click, press, 또는 toggle 액션이 경계(bounds)보다 우선합니다. Entry의 activate와 슬라이더의 jump는 반드시 perform_action을 통해 명시적으로 요청되어야 하며, 경계가 누락된 경우에도 포인터 클릭을 대체할 수 없습니다.
이는 요소가 그러한 액션을 노출하는 경우 GTK3 HiDPI 영역 및 GTK4 제로 오리진(zero-origin) 경계에 대한 포인터 변환을 방지합니다. 이러한 선호도 설정은 임의의 액션 이름이 좌표 클릭을 대체한다는 의미는 아닙니다. 명시적인 x/y, 오른쪽 클릭, 그리고 더블/멀티 클릭은 여전히 포인터 시맨틱스(pointer semantics)를 유지합니다. 활성화된 종류에 관계없이 애플리케이션 상태를 재확인해야 합니다.
KDE Wayland 환경에서, 포인터 디스패치(pointer dispatch)가 필요한 요소 클릭은 캐시된 AT-SPI 프레임을 일관성 있는 KWin 창/출력 스냅샷과 일치시키고, 이후 대상을 물리적 캡처 픽셀(uinput) 및 논리적 데스크톱 좌표(portal)로 별도로 매핑합니다. 기기 로컬(Client-local) 및 장식된 프레임, 실제 장식 오프셋(decoration offsets), 그리고 0이 아니거나 음수인 출력 원점은 지오메트리(geometry)와 균일한 출력 스케일이 검증될 때 지원됩니다. 모호한 창, 혼합되거나 알려지지 않은 스케일, 중첩된 출력, 또는 오래된 포인터 지오메트리는 입력 전에 실패합니다.
명시적인 x/y는 기본적으로 coordinate_space: "capture"(원시 스크린샷 픽셀)를 사용합니다. 전역 AT-SPI 화면 포인트를 클릭하려면, 해당 element_index 또는 의미론적 선택자와 함께 coordinate_space: "atspi"를 전달해야 합니다. 그러면 KDE Wayland는 AT-SPI 창 프레임이 기기 로컬인 경우를 포함하여 요소 경계 클릭과 동일한 네이티브 KWin 장식 및 스케일 변환을 적용합니다. 이 모드는 좌표와 요소 식별자(element identity) 둘 다를 요구하며 relative: true와 결합될 수 없습니다. 다른 호출들은 기존의 좌표 동작 방식을 유지합니다.
좌표를 이용한 click 또는 scroll의 경우, relative: true로 설정하면 대상 창(window)을 선택하고 해당 창의 클리핑된 스크린샷 자르기 원점으로부터 측정해야 합니다. 미리보기 x 및 y 값을 반환된 스크린샷 배율(scale)로 나누어 전달해야 합니다. 이 값들은 원시 GDK 표면 또는 위젯 로컬 좌표가 아니며, 장식(decoration)이나 클리핑에 의해 원점이 변경될 수 있습니다. 대상 창이 누락되면 거부됩니다.
X11 텍스트 충실도: xdotool/XTEST는 비(非) 미국식 XKB 레이아웃(브라질어 br/ABNT2로 보고됨)이나 키맵 상태가 변경되는 경우, 심지어 type_text가 ok: true를 반환하더라도 기호를 조용히 대체할 수 있습니다. 성공적인 xdotool 텍스트 전송에는 레이아웃 경고(layout warning)가 포함됩니다. XKB 레이아웃 교체 이벤트, 지속적인 매핑/그룹 변경, 그리고 호출 간에 감지된 키보드 포커스/그랩 전환은 텍스트를 재전송하지 않고 디스패치 후 오류를 반환합니다. 키보드 그랩(Keyboard grab)은 폴링되는 포커스 창 ID를 변경하지 않으면서 문자를 우회시킬 수 있습니다. 모니터링을 시작할 수 없는 경우에도 xdotool는 계속해서 전송하며, 응답에서 레이아웃 변경 및 키보드 가로채기 감지 기능이 사용 불가능했음을 명시적으로 경고합니다. PointerRoot 포커스는 포인터 움직임이 감지 가능한 포커스 이벤트 없이 입력 방향을 바꿀 수 있으므로 지원되지 않습니다. 또한 이는 한 번의 호출 동안 setxkbmap 레이아웃이 변경되고 복원되는 것도 감지합니다. 임시 원시 재매핑(raw remaps)이나 그룹 전환이 호출 내에서 복원된 후 안정적인 맵으로 드롭된 텍스트는 검증되지 않은 상태로 남아 있습니다. Enter를 누르거나, 제출하거나, 전달되었다고 간주하기 전에 실제 텍스트를 다시 관찰하십시오. 애플리케이션이 텍스트를 노출하는 경우 AT-SPI 리드백을 위해 include_tree: true를 사용하거나, 내용을 검사하려면 screenshot_after: true를 사용하십시오. 이러한 관찰은 필드를 요청된 텍스트와 자동으로 비교하지 않습니다. 근거 없이 재시도하지 마십시오.