🖥️ screen-use

browser-use, pero para todo el escritorio.

Dale ojos 👀 y manos 🖐️ a cualquier agente de IA en Windows: permite que Claude, Kimi, Cursor o tu propio agente vea la pantalla, encuentre elementos de la interfaz y opere cualquier aplicación de escritorio mediante lenguaje natural. Sin selectores. Sin scripts que se rompan cuando cambia la interfaz.

👆 Autonomía entre aplicaciones: el agente lee el resultado de la Calculadora, activa el Bloc de notas y lo escribe; cada paso lo decide el VLM que observa la pantalla (consulta el flujo de pensamiento en vivo al final).

Bucle de agente de una sola aplicación (el VLM calcula 78 × 9 por sí mismo):

Entre aplicaciones con script (Calculadora → Bloc de notas):

Clic de precisión en una sola aplicación:

Por qué

El RPA tradicional graba selectores y se rompe en cuanto cambia una página. browser-use (32k⭐) resolvió esto para navegadores. screen-use lleva la misma idea a todo el escritorio: Excel, clientes SAP, software ERP, incluso programas Win32 heredados.

Related MCP server: WinPilot Computer Use MCP

Cómo funciona

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            │
└─────────────────────────────────────────────┘

El VLM es opcional, no obligatorio. La cadena de estrategias de localización alcanza la mayoría de los objetivos con coincidencia de texto pura del árbol de accesibilidad: cero llamadas al modelo, latencia de milisegundos. Un modelo de visión (en la nube o local mediante Ollama) solo interviene en interfaces ciegas a UIA.

Inicio rápido

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

Como plugin de Kimi CLI (recomendado)

Un solo comando: Kimi obtiene al instante las 14 herramientas de escritorio:

kimi mcp add --transport stdio screen-use -- <path-to-python.exe> -m screen_use.mcp_server
kimi mcp test screen-use   # verify the connection

Opcionalmente, instala la habilidad de estrategia de uso incluida, que enseña a Kimi el manual óptimo de selección de herramientas:

mkdir -p ~/.kimi/skills/screen-use && cp skills/screen-use/SKILL.md ~/.kimi/skills/screen-use/

Luego solo dile a Kimi: "Abre la Calculadora y calcula 123 × 456" o "Lee lo que hay en mi Bloc de notas".

Como servidor MCP genérico

Añade a claude_desktop_config.json (o a la configuración de cualquier agente compatible con MCP):

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

Luego solo dile a tu agente: "Abre la Calculadora y calcula 123 × 456."

Como SDK de Python

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)

Bucle de tareas autónomo

Una sola llamada, autonomía total: el agente ve, decide, actúa y se autocorrige:

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

Introspección (困难分类反思): cuando el bucle se atasca, clasifica la dificultad — sin efecto / repetir bucle / fallos consecutivos / elementos faltantes / ventana emergente inesperada — y reflexiona con un manual de indicaciones específico, luego ajusta la estrategia.

Meta-aprendizaje (元学习): se recuerdan las ejecuciones exitosas. Las tareas pasadas similares se recuperan como pistas de experiencia, y los mapeos de vocabulario aprendidos (p. ej., "乘号" → Multiply by) se convierten en el nuevo primer nivel de la cadena de estrategias. Literalmente mejora cuanto más lo usas. La memoria vive en ~/.screen_use/.

Herramientas (14)

Atómicas (cero dependencia de modelos): screenshot · list_ui_elements · click · double_click · right_click · click_element_id · type_text · hotkey · press · scroll

De alto nivel: find_element (localización por cadena de estrategias) · click_element (localizar + hacer clic) · read_screen (Q&A de pantalla con VLM) · run_task (bucle visual autónomo)

Modelo de visión (opcional)

Solo es necesario cuando tu agente no tiene visión Y la aplicación objetivo es ciega a UIA. Copia .env.example a .env:

Sin ningún VLM configurado, las herramientas atómicas y la coincidencia con UIA siguen funcionando por completo.

Seguridad

• 🚨 A prueba de fallos: golpea el ratón en la esquina superior izquierda para abortar al instante

• ✅ Gancho confirm_callback para aprobar cada acción (SDK)

• 🧪 ScreenUse(dry_run=True) registra acciones sin ejecutarlas

Extensibilidad

screen-use está diseñado como un conjunto de capas reemplazables: cada nivel se puede extender sin tocar el núcleo:

Los ganchos de seguridad también forman parte de la interfaz: confirm_callback para aprobación humana en el bucle, dry_run para simulación, y el mecanismo a prueba de fallos de PyAutoGUI para detención de emergencia.

Hoja de ruta

• Cadena de estrategias de localización UIA + SoM

• Servidor MCP (14 herramientas)

• Soporte de VLM local (Ollama)

• Bucle visual autónomo (run_task)

• Manual de introspección y memoria de meta-aprendizaje

• wait_for_element / primitivas de verificación automática

• Arrastrar y soltar

• Respaldo de coordenadas brutas con VLM + coincidencia de plantillas con OpenCV (aplicaciones ciegas a UIA)

• Soporte para macOS (API de Accesibilidad) y Linux

• Publicación en PyPI

Las contribuciones son bienvenidas: consulta los issues para buenas primeras tareas.

Desarrollo

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

Licencia

MIT

screen-use = 桌面版 browser-use：让任何 AI Agent 获得看屏幕、操作桌面应用的能力。

• 不是传统 RPA：不录制 selector，通过无障碍树 + 视觉模型理解 UI，界面变了也不怕

• 跨一切桌面应用：Excel、SAP、ERP 客户端、老旧 Win32 程序

• 自然语言驱动：click_element("保存按钮") 一句话搞定

• VLM 可选：策略链第一级是纯 UIA 文本匹配（零模型、毫秒级），视觉模型只在盲区兜底，支持本地 Ollama 保护隐私

接入方式、工具列表、安全配置与上文英文版一致。