Computer-use — Control de escritorio (macOS)

Theus puede ver tu pantalla y operarla: captura, mouse y teclado. Es una implementación propia, sin addons compilados — se apoya en herramientas nativas del sistema (screencapture, sips, cliclick, osascript). Es opt-in, solo macOS, y los permisos TCC del sistema son la barrera real.

Qué hace

Con computer-use activo, cualquier turno del agente puede tomar un screenshot, razonar sobre la imagen y actuar sobre la pantalla: clicks, arrastres, texto, combinaciones de teclas y scroll. Sirve para automatizar apps de escritorio, verificar visualmente una UI o completar flujos que no son alcanzables por terminal.

Activación

brew install cliclick                     # única dependencia externa
theus --theus-computer-use-selftest       # certifica captura + control en tu Mac
THEUS_COMPUTER_USE=1 theus                # arranca la sesión con computer-use montado

Computer-use nunca se monta solo: requiere la variable THEUS_COMPUTER_USE=1 (acepta 1, true, yes, on). Con ella activa, Theus registra en la sesión el servidor MCP theus-computer-use (por stdio, proceso theus --theus-computer-use-mcp) y sus 12 herramientas aparecen junto a las nativas.

swiftc (las Command Line Tools de Xcode) es opcional: sin él, solo la herramienta scroll queda deshabilitada; todo lo demás funciona.

Permisos macOS necesarios

Debes otorgar dos permisos al app que corre Theus — es decir, a tu terminal (Terminal, iTerm2, etc.) — en Ajustes del Sistema → Privacidad y seguridad:

Grabación de pantalla — necesaria para screenshot. Activa el interruptor de tu terminal en la lista.
Accesibilidad — necesaria para mouse y teclado (cliclick/osascript). Activa el interruptor de tu terminal en la lista.

macOS suele pedir reiniciar el terminal tras otorgarlos. Sin los permisos, las herramientas no rompen el turno: devuelven un error accionable que indica exactamente qué permiso falta y dónde activarlo. La herramienta permissions y el self-test verifican ambos en cualquier momento.

El self-test

theus --theus-computer-use-selftest

Certifica computer-use en tu equipo con un reporte PASS/FAIL accionable: verifica las herramientas del sistema, los dos permisos TCC, la geometría lógica de la pantalla y una captura real (guarda una imagen de prueba en ~/.theus/cu/selftest-shot.jpg). Es no destructivo: mueve el cursor y lo devuelve a su sitio; no teclea ni hace click en ninguna app. Córrelo una vez tras otorgar los permisos.

Las 12 herramientas MCP

Nombres completos: mcp__theus-computer-use__<tool>.

Herramienta	Qué hace
`screenshot`	Captura la pantalla y la devuelve como imagen. Se usa antes de cualquier acción (ver el estado) y después (verificar el resultado). Las coordenadas de las demás tools son píxeles dentro de esta imagen.
`left_click`	Click izquierdo en (x, y), coordenadas en píxeles del último screenshot.
`double_click`	Doble click izquierdo en (x, y).
`right_click`	Click derecho en (x, y).
`mouse_move`	Mueve el cursor a (x, y) sin hacer click.
`left_click_drag`	Arrastra con el botón izquierdo desde (from_x, from_y) hasta (to_x, to_y).
`type`	Escribe el texto dado en el foco actual, como si lo teclearas.
`key`	Pulsa una tecla o combinación: `return`, `tab`, `escape`, `cmd+a`, `ctrl+shift+t`, `arrow-down`… Modificadores: `cmd`, `ctrl`, `alt`, `shift`.
`scroll`	Scroll en la dirección dada (`up`/`down`/`left`/`right`); `amount` es la intensidad (por defecto 3).
`cursor_position`	Posición actual del cursor (en puntos lógicos).
`wait`	Espera N segundos para que la UI reaccione (máximo 10).
`permissions`	Verifica si Grabación de pantalla y Accesibilidad están otorgados; devuelve un diagnóstico accionable.

Cómo trabaja el agente

El ciclo es siempre el mismo: screenshot → razonar → actuar → screenshot de verificación. El modelo trabaja en el espacio de píxeles del último screenshot — «el botón está en (840, 512)» — y el servidor mapea esas coordenadas a los puntos lógicos de la pantalla antes de mover o hacer click (en pantallas Retina la imagen tiene más píxeles que puntos lógicos; el mapeo es automático y las coordenadas se acotan a los límites de la pantalla). Junto a cada captura, el servidor reporta las dimensiones de la imagen y qué app está al frente.

Seguridad

Opt-in explícito — sin THEUS_COMPUTER_USE=1 el servidor no se monta y las herramientas no existen en la sesión.
Permisos TCC como barrera real — las dos capacidades sensibles (captura y control) están detrás de permisos del sistema que solo el dueño del equipo puede otorgar, app por app. Theus no puede auto-otorgárselos.
Fallos accionables, no silenciosos — sin permisos, cada herramienta devuelve un error que explica qué falta; nunca rompe el turno ni actúa a medias.
Sin binarios propios de control — el control usa herramientas del sistema (cliclick instalado por ti vía Homebrew, osascript, screencapture): auditables y visibles.

Theus — agente de código local-first y multimodelo · Hecho en Perú