Home

Deskbrid Documentation

The HAL your Linux desktop agents are missing.

Deskbrid is a single Rust binary that auto-detects your desktop environment and provides a unified JSON-over-Unix-socket protocol for desktop automation on Linux. One daemon, one protocol, one binary — works across GNOME, Hyprland, KDE, wlroots compositors, and X11.

Quick Links

• Installation - Install Deskbrid on your system
• Quick Start - Get running in 5 minutes
• Protocol Overview - JSON protocol specification
• Python Client - Python integration guide

Features

Core Features

Feature	Description	Documentation
Windows & Workspaces	List, focus, move, resize, and tile windows; manage workspaces	windows-workspaces.md
Input Control	Keyboard typing, key combos, mouse movement, clicks, scroll	input.md
Clipboard	Read/write, history, monitoring	clipboard.md
Screenshots	Capture, OCR, diff comparison	screenshots.md

System Features

Feature	Description	Documentation
System Info	Desktop info, battery, idle, power actions	system.md
Media Control	MPRIS player integration	media.md
Audio	Sink listing and volume control	audio.md
Network	WiFi status and connections	network.md
Bluetooth	Device discovery and pairing	bluetooth.md
Services	systemd unit management	services.md
Terminals	Interactive PTY sessions	terminals.md
Monitors	Display configuration	monitors.md

Advanced Features

Feature	Description	Documentation
Notifications	Desktop notification API	notifications.md
Files	File search and watching	files.md
Layout Profiles	Save and restore workspace layouts	layout-profiles.md
Accessibility	AT-SPI tree inspection	accessibility.md

Protocol

Document	Description
Overview	JSON protocol fundamentals
Events	Real-time event subscription
MCP Integration	Model Context Protocol server

Integrations

Integration	Description
Python Client	Python library usage
AI Agents	Claude Code, Cursor, etc.

Development

Document	Description
Architecture	System design deep dive

Supported Desktops

Desktop	Status	Notes
GNOME 46-50	✅ Full	Requires Shell extension
Hyprland	✅ Full	Requires ydotool
KDE Plasma	✅ Full	Requires ydotoold
Sway	✅ Full	Requires ydotool
Niri	✅ Partial	Geometry degraded
Wayfire	✅ Partial	No move/resize
Labwc	✅ Partial	No move/resize
COSMIC	⚠️ Partial	Some limitations
Cinnamon / MATE	✅ Full	X11 shared backend

Example Usage

CLI

# List windows
deskbrid windows list

# Focus a window
deskbrid windows focus --app code

# Type text
deskbrid input keyboard type "Hello, world!\n"

# Take screenshot
deskbrid screenshot --output ./screenshot.png

Python

from deskbrid import Deskbrid

client = Deskbrid()
windows = client.windows_list()
client.focus_window(app_id='code')
client.type_text("Fixed the bug!\n")

MCP (AI Agents)

// In your AI coding tool's MCP config
{
  "mcpServers": {
    "deskbrid": {
      "command": "deskbrid",
      "args": ["mcp"]
    }
  }
}