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	docs
Input Control	Keyboard typing, key combos, mouse movement, clicks, scroll	docs
Clipboard	Read/write, history, monitoring	docs
Screenshots	Capture, OCR, diff comparison	docs

System Features

Feature	Description	Documentation
System Info	Desktop info, battery, idle, power actions	docs
Media Control	MPRIS player integration	docs
Audio	Sink listing and volume control	docs
Network	WiFi status and connections	docs
Bluetooth	Device discovery and pairing	docs
Services	systemd unit management	docs
Terminals	Interactive PTY sessions	docs
Monitors	Display configuration	docs
Screen Recording	PipeWire-based capture, web dashboard	docs
Self-Update	Automatic binary updates from GitHub	docs
System Tray	Tray icon with update notifications and quick actions	docs

Advanced Features

Feature	Description	Documentation
Notifications	Desktop notification API	docs
Files	File search and watching	docs
Layout Profiles	Save and restore workspace layouts	docs
Accessibility	AT-SPI tree inspection	docs
Persistence	SQLite-backed clipboard history, audit log, blackboard, rules, sessions	docs
Rules Engine	Event-driven automation with cooldown and max_fires	docs
Sessions	Named sessions with isolated variable namespaces	docs
Blackboard	Namespace-scoped KV store for multi-agent coordination	docs
Macros	Record and replay action sequences	docs
Cron	Schedule actions at intervals	docs

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"]
    }
  }
}