🖥️ screen-use

browser-use, 하지만 데스크톱 전체를 위한.

Windows에서 모든 AI 에이전트에게 눈 👀과 손 🖐️을 부여하세요 — Claude, Kimi, Cursor 또는 자신의 에이전트가 화면을 보고, UI 요소를 찾고, 자연어를 통해 모든 데스크톱 앱을 조작할 수 있게 합니다. 셀렉터가 필요 없습니다. UI가 변경되면 깨지는 스크립트도 없습니다.

👆 계산기에서 123 + 456을 계산한 후 결과를 메모장에 붙여넣는 AI 에이전트 — 두 개의 앱, 하드코딩된 셀렉터 없음, 완전 자율.

왜 필요한가

전통적인 RPA는 셀렉터를 기록하지만 — 페이지가 변경되는 순간 깨집니다. browser-use (32k⭐)는 브라우저에서 이 문제를 해결했습니다. screen-use는 동일한 아이디어를 전체 데스크톱으로 확장합니다: Excel, SAP 클라이언트, ERP 소프트웨어, 심지어 레거시 Win32 프로그램까지.

작동 방식

Your Agent (Claude / Kimi / Cursor / custom)   ← does the planning
        │  MCP or Python SDK
        ▼
┌─────────────────────────────────────────────┐
│ screen-use                                  │
│  Visual Loop ──► observe→think→act→verify   │
│  Introspection──► difficulty playbook        │
│  Meta-learning──► experience & vocab memory  │
│  Perception ──► UIA tree + screenshots (SoM)│
│  Locating   ──► strategy chain:             │
│                 ⓪ learned vocab mapping     │
│                 ① UIA text match (0 cost)   │
│                 ② Set-of-Mark + VLM         │
│  Action     ──► mouse / keyboard            │
└─────────────────────────────────────────────┘

VLM은 선택 사항이며 필수가 아닙니다. 위치 찾기 전략 체인은 순수 접근성 트리 텍스트 매칭으로 대부분의 대상을 찾습니다 — 모델 호출 없음, 밀리초 지연. 비전 모델(클라우드 또는 Ollama를 통한 로컬)은 UIA를 인식하지 못하는 UI에서만 작동합니다.

빠른 시작

git clone https://github.com/tongriyaotxt/screen-use.git
cd screen-use
pip install -r requirements.txt

MCP 서버로 사용 (권장)

claude_desktop_config.json(또는 MCP 호환 에이전트의 구성)에 추가하세요:

{
  "mcpServers": {
    "screen-use": {
      "command": "python",
      "args": ["-m", "screen_use.mcp_server"],
      "cwd": "path/to/screen-use"
    }
  }
}

그런 다음 에이전트에게 말하기만 하면 됩니다: "계산기를 열고 123 × 456을 계산해."

Python SDK로 사용

from screen_use import ScreenUse

tools = ScreenUse()

tools.click_element("Save")            # locate + click, one call
tools.type_text("Hello, 你好")          # Unicode-safe (clipboard paste)
tools.hotkey("ctrl", "s")

# Atomic tools for vision-capable agents:
elements = tools.list_ui_elements()    # id, name, type, bbox — no model needed
shot = tools.screenshot(annotate=True) # Set-of-Mark annotated screenshot
tools.click(500, 300)

자율 작업 루프

한 번의 호출로 완전한 자율성 — 에이전트가 보고, 결정하고, 행동하고, 스스로 수정합니다:

tools.run_task("打开计算器，算 25 乘以 4")   # observe → think → act → verify

Introspection (困难分类反思): 루프가 막히면 난이도를 분류합니다 — 효과 없음 / 루프 반복 / 연속 실패 / 요소 누락 / 예상치 못한 팝업 — 그리고 대상 프롬프트 플레이북으로 반성한 후 전략을 조정합니다.

Meta-learning (元学习): 성공적인 실행이 기억됩니다. 유사한 과거 작업이 경험 힌트로 회상되고, 학습된 어휘 매핑(예: "乘号" → Multiply by)이 전략 체인의 새로운 첫 번째 레벨이 됩니다. 사용할수록 실제로 더 좋아집니다. 메모리는 ~/.screen_use/에 저장됩니다.

도구 (14)

원자적 (모델 의존성 없음): screenshot · list_ui_elements · click · double_click · right_click · click_element_id · type_text · hotkey · press · scroll

고수준: find_element (전략 체인 위치 찾기) · click_element (위치 찾기 + 클릭) · read_screen (VLM 화면 Q&A) · run_task (자율 시각 루프)

비전 모델 (선택 사항)

에이전트에 비전이 없고 대상 앱이 UIA를 인식하지 못하는 경우에만 필요합니다. .env.example을 .env로 복사하세요:

VLM이 구성되지 않아도 원자적 도구와 UIA 매칭은 완전히 작동합니다.

안전

• 🚨 안전장치: 마우스를 왼쪽 상단 모서리로 밀어 즉시 중단

• ✅ 모든 작업을 승인하는 confirm_callback 훅 (SDK)

• 🧪 ScreenUse(dry_run=True)는 실행 없이 작업을 기록

로드맵

• UIA + SoM 위치 찾기 전략 체인

• MCP 서버 (14개 도구)

• 로컬 VLM 지원 (Ollama)

• 자율 시각 루프 (run_task)

• 반성 플레이북 및 메타러닝 메모리

• wait_for_element / 자동 검증 프리미티브

• 드래그 앤 드롭

• VLM 원시 좌표 폴백 + OpenCV 템플릿 매칭 (UIA 인식 불가 앱)

• macOS (접근성 API) 및 Linux 지원

• PyPI 릴리스

기여를 환영합니다 — 좋은 첫 작업은 issues를 확인하세요.

개발

pytest tests -q                        # 61 unit tests, no desktop/VLM needed
python examples/demo_calculator.py     # end-to-end demo (real clicks!)
python examples/mcp_client_demo.py     # MCP handshake + tool list

라이선스

MIT

screen-use = 데스크톱 버전 browser-use: 모든 AI 에이전트가 화면을 보고 데스크톱 앱을 조작할 수 있는 능력을 부여합니다.

• 전통적인 RPA가 아님: 셀렉터를 기록하지 않고, 접근성 트리 + 비전 모델로 UI를 이해하므로 인터페이스가 변경되어도 걱정 없음

• 모든 데스크톱 앱 지원: Excel, SAP, ERP 클라이언트, 레거시 Win32 프로그램

• 자연어 구동: click_element("保存按钮") 한 마디로 해결

• VLM 선택 사항: 전략 체인의 첫 번째 레벨은 순수 UIA 텍스트 매칭(모델 없음, 밀리초), 비전 모델은 맹점에서만 보조, 개인정보 보호를 위한 로컬 Ollama 지원

통합 방법, 도구 목록, 보안 구성은 위의 영어 버전과 동일합니다.