Deskbrid

HAL de escritorio Linux para agentes de IA.

Documentación

deskbrid

mcp-name: io.github.coe0718/deskbrid

📖 Documentación | Referencia de API | Arquitectura | Notas de la versión v1.0.0

El HAL que les falta a tus agentes de escritorio Linux.

Deskbrid es un único binario de Rust que detecta automáticamente tu entorno de escritorio y lo envuelve en un protocolo JSON sobre socket Unix. GNOME, Hyprland, KDE, COSMIC, Sway, Niri, Wayfire, Labwc, Cinnamon, MATE — un demonio, un protocolo, un binario.

# Human
deskbrid windows list
deskbrid clipboard read

# Agent (same socket)
{"action": "windows.list"}  →  [{"title": "VS Code", "app_id": "code", ...}]

Por qué Deskbrid

Todos los grandes laboratorios de IA están compitiendo por lanzar agentes de escritorio. AppleScript les da a los agentes de macOS control nativo. Windows tiene UI Automation. Linux tiene xdotool — que se rompe en Wayland, el protocolo de visualización predeterminado en todas las principales distribuciones.

Deskbrid llena ese vacío. Detecta automáticamente tu compositor y carga el backend correcto — GNOME (Mutter RemoteDesktop DBus), Hyprland (hyprctl + ydotool + grim), KDE (KWin D-Bus + ydotool + spectacle), compositores estilo wlroots, o X11 compartido. Mismo binario, mismo protocolo, mismo socket.

Demo: agent focuses VS Code window and types a command via deskbrid

Panel de control

Deskbrid incluye un panel web integrado en localhost:20129 — información del sistema, monitores, ventanas, red, audio, portapapeles y un registro de auditoría de las acciones del agente, todo en vivo:

🔴 Demo en vivo →

Deskbrid Dashboard — Hyprland, system overview with SSE-connected live data

Escritorios compatibles

Escritorio	Sesión	Estado	Backend
GNOME 46–50	Wayland	✅ Núcleo	Mutter RemoteDesktop + Shell Extension
KDE Plasma	Wayland	✅ Núcleo	KWin D-Bus + ydotool + spectacle
Hyprland	Wayland	✅ Núcleo	hyprctl + ydotool + grim
Sway	Wayland	✅ Núcleo	swaymsg + ydotool + grim
Labwc	Wayland	⚠️ Parcial	wlrctl + ydotool + grim + wlr-randr
COSMIC	Wayland	⚠️ Parcial	cosmic-helper + cosmic-randr + ydotool + grim
Niri	Wayland	🔲 Sin probar	niri msg + ydotool + grim + wlr-randr
Wayfire	Wayland	🔲 Sin probar	wf-ipc + ydotool + grim + wlr-randr
Cinnamon	X11	🔲 Sin probar	xdotool + wmctrl + xclip + import
MATE	X11	🔲 Sin probar	xdotool + wmctrl + xclip + import
X11 (genérico)	X11	🔲 Sin probar	xdotool + wmctrl + xclip + import

Cobertura honesta: Deskbrid funciona bien en GNOME, KDE, Hyprland y Sway — probado en hardware real (Turtle, una laptop Haswell de 2014). Los otros siete backends tienen código pero cero verificación en tiempo de ejecución. Incluso dentro de los backends principales, el soporte es desigual: Hyprland carece de windows.minimize y monitor.set_primary, COSMIC carece de mover/redimensionar ventanas y mosaico, Labwc carece de mover/redimensionar, minimizar, mosaico y control del monitor principal. Las acciones simuladas (ui.tree.get, ui.element.click, bluetooth.pair) devuelven "no soportado". Esto es automatización de escritorio Linux amplia pero parcial, no control universal entre escritorios. Consulta la Matriz de pruebas de DE completa para el detalle por acción y por compositor.

Instalación

Instalación de una línea (recomendada):

bash <(curl -fsSL https://deskbrid.patchhive.dev/install.sh)

Detecta automáticamente tu distribución y entorno de escritorio, instala dependencias, configura uinput y descarga el binario.

Instalación manual:

Descarga el tarball de la última versión desde la página de lanzamientos:

ARCH=$(uname -m)
case "$ARCH" in x86_64) ARCH="x86_64-unknown-linux-gnu";; aarch64|arm64) ARCH="aarch64-unknown-linux-gnu";; esac
curl -LO "https://github.com/coe0718/deskbrid/releases/latest/download/deskbrid-${ARCH}.tar.gz"
curl -LO "https://github.com/coe0718/deskbrid/releases/latest/download/deskbrid-${ARCH}.tar.gz.sha256"
sha256sum -c "deskbrid-${ARCH}.tar.gz.sha256"
tar -xzf "deskbrid-${ARCH}.tar.gz"
sudo mv deskbrid /usr/local/bin/
chmod +x /usr/local/bin/deskbrid

O compila desde el código fuente:

git clone https://github.com/coe0718/deskbrid
cd deskbrid
cargo build --release
sudo cp target/release/deskbrid /usr/local/bin/

Configuración del escritorio

GNOME:

sudo apt install -y grim wl-clipboard python3-gi gstreamer1.0-tools gstreamer1.0-pipewire
deskbrid setup

Hyprland (y otros compositores Wayland independientes — Sway, Niri, Wayfire, Labwc):

sudo pacman -S grim wl-clipboard ydotool
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-input.rules
sudo usermod -aG input $USER

⚠️ Los compositores Wayland independientes no incluyen un demonio de notificaciones. El notify send de Deskbrid se colgará sin uno. Instala dunst, mako o swaync y agrégalo al inicio automático de tu compositor.

KDE Plasma:

sudo apt install spectacle imagemagick wl-clipboard ydotool

Inicio rápido

deskbrid daemon &

deskbrid windows list          # List open windows
deskbrid clipboard read        # Read clipboard
deskbrid screenshot            # Take screenshot
deskbrid system info           # Get system info
deskbrid windows focus --app code  # Focus VS Code
deskbrid input keyboard type "Hello!"  # Type text

Características

Ventanas y espacios de trabajo

Acción	Descripción
`windows.list`	Lista todas las ventanas abiertas
`windows.focus`	Enfoca una ventana por app_id o título
`windows.get`	Obtiene detalles de una ventana específica
`windows.close`	Solicita el cierre de una ventana
`windows.minimize/maximize`	Control del estado de la ventana
`windows.move_resize`	Mueve y redimensiona ventanas
`windows.tile`	Mosaico en regiones de la pantalla
`windows.activate_or_launch`	Enfoca o lanza una aplicación
`workspaces.*`	Gestión de espacios de trabajo
`layout_profiles.*`	Guarda/restaura diseños

Entrada y portapapeles

Acción	Descripción
`input.keyboard type`	Escribe texto
`input.keyboard key`	Envía una pulsación de tecla
`input.keyboard combo`	Envía combinaciones de teclas
`input.mouse.*`	Control del ratón
`clipboard.read/write`	Acceso al portapapeles
`clipboard.history`	Historial del portapapeles

Capturas de pantalla y multimedia

Acción	Descripción
`screenshot`	Captura de pantalla
`screenshot.ocr`	Extrae texto mediante Tesseract
`screenshot.diff`	Compara capturas de pantalla
`mpris.*`	Control del reproductor multimedia
`color.pick`	Muestra colores de píxeles

Sistema y servicios

Acción	Descripción
`system.info`	Información del escritorio
`system.battery`	Estado de la batería
`system.idle`	Detección de inactividad
`system.power`	Gestión de energía
`service.*`	Unidades de systemd
`journal.query`	Inspección de registros
`terminal.*`	Sesiones PTY
`monitor.*`	Control de pantalla

Red y Bluetooth

Acción	Descripción
`network.*`	Estado/conexión WiFi
`bluetooth.*`	Emparejamiento/control de dispositivos

Voz y salida de audio

Acción	Descripción
`speech.speak`	Lee texto en voz alta (spd-say / espeak-ng)
`speech.stop`	Cancela locuciones en curso
`speech.voices`	Lista las voces disponibles

Protocolo

Deskbrid usa JSON sobre socket Unix. Consulta PROTOCOL.md para la especificación completa.

→ {"action": "windows.list"}
← {"type": "response", "status": "ok", "data": [{"title": "VS Code", ...}]}

→ {"action": "windows.focus", "window_id": "code"}
← {"type": "response", "status": "ok"}

Eventos

Suscríbete a actualizaciones en tiempo real:

{"action": "subscribe", "events": ["file.*"]}

Cliente Python

from deskbrid import Deskbrid

client = Deskbrid()

# List and focus VS Code
windows = client.windows_list()
code_window = next((w for w in windows if w.app_id == 'code'), None)
if code_window:
    client.focus_window(app_id='code')
    client.type_text("Fixed the bug!\n")

# Subscribe to events
@client.on("file.*")
def on_file_change(event):
    print(f"File changed: {event['path']}")

Integración MCP

Deskbrid expone un servidor completo de Model Context Protocol para herramientas de codificación con IA:

deskbrid mcp

Agente Hermes (habilidad integrada)

Deskbrid incluye una habilidad de Hermes para configuración con un solo comando. En cualquier sesión de Hermes:

/deskbrid-hermes-mcp

O desde la terminal:

hermes mcp add deskbrid --command "deskbrid mcp"
hermes mcp test deskbrid
# → ✓ deskbrid: connected

Después de reiniciar la sesión (/reset), el agente obtiene más de 100 herramientas de control del escritorio Linux.

Claude Desktop

~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "deskbrid": {
      "command": "/usr/local/bin/deskbrid",
      "args": ["mcp"]
    }
  }
}

Codex / Cursor / cualquier cliente MCP

Configura el servidor MCP con el comando deskbrid mcp — el protocolo es JSON-RPC estándar sobre stdio.

Herramientas MCP disponibles (más de 100 en 20 categorías): ventanas, entrada, portapapeles, capturas de pantalla, sistema, accesibilidad AT-SPI, terminal PTY, archivos, audio, red, MPRIS, impresión, notificaciones, llavero, reglas, confirmación, mensajería de agente, búsqueda, macros, capacidades, voz.

Comparación con alternativas

Herramienta	Wayland	Nativo para agentes	JSON	Ventanas	Entrada	Portapapeles	Captura de pantalla	Bluetooth	Audio
deskbrid	✅	✅	✅	✅	✅	✅	✅	✅	✅
xdotool	❌	❌	❌	✅	✅	❌	❌	❌	❌
ydotool	✅	❌	❌	❌	✅	❌	❌	❌	❌
grim	✅	❌	❌	❌	❌	❌	✅	❌	❌
wl-clipboard	✅	❌	❌	❌	❌	✅	❌	❌	❌

Licencia

MIT

Cómo empezó esto

Deskbrid comenzó con Tuck — un agente autónomo que necesitaba controlar un escritorio Linux real. Cuando la comunidad pidió soporte para Hyprland, Tuck le pidió a Jeremy una máquina Arch Linux básica con SSH y sudo. Él mismo instaló Hyprland y construyó el backend desde dentro del entorno que acababa de configurar.

La primera demo funcional fue un mensaje de Telegram: Tuck enfocó una ventana y escribió "Hola desde el otro lado" en menos de 60 segundos. Ese momento — un agente controlando un escritorio real a través de un socket Unix — se convirtió en Deskbrid. Está construido para agentes primero: mismo protocolo para humanos en la CLI, mismo socket para IAs, un binario que funciona en todas partes.