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

Desktop

Feature	Description	Documentation
Windows & Workspaces	List, focus, move, resize, 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
Screen Recording	PipeWire-based capture, web dashboard	docs
Screencast	Video recording with GStreamer/PipeWire	docs
System Info	Desktop info, battery, idle, power actions, pressure	docs
Audio	Sink listing, volume control, mute	docs
Network	WiFi status, connections, scanning	docs
Bluetooth	Device discovery, pairing, management	docs
Monitors	Display configuration, resolution, arrangement	docs
Terminals	Interactive PTY sessions	docs
Notifications	Desktop notification API, history	docs
Files	File search, read, write, watch	docs
Apps	Application listing and launching	docs
Desktop Settings	gsettings read/write, schema discovery	docs
Color Picker	Screen color sampling	docs
Hotkeys	Global keyboard shortcuts	docs
Keyboard Layouts	List, switch, save/restore layout profiles	docs

Media & Hardware

Feature	Description	Documentation
Media Control	MPRIS player integration	docs
Media	Media device listing and control	docs
Monitor	Individual monitor properties and control	docs
System Tray	Tray icon with notifications and quick actions	docs
Self-Update	Automatic binary updates from GitHub	docs
Systemd Units & Timers	systemd journal, unit control, timers	docs
Services	systemd unit management	docs

Interop

Feature	Description	Documentation
D-Bus	D-Bus method calls and signal subscriptions	docs
Desktop Portal	XDG Desktop Portal integration	docs
Browser CDP	Chrome DevTools Protocol for browser control	docs
Location	Geolocation services	docs
Accessibility	AT-SPI tree inspection	docs

Automation

Feature	Description	Documentation
Rules Engine	Event-driven automation with cooldowns	docs
Macros	Record and replay action sequences	docs
Macro Recording	Interactive macro capture and playback	docs
Cron	Schedule actions at intervals	docs
Schedule	One-shot and recurring scheduled tasks	docs
Sessions	Named sessions with isolated state	docs
Blackboard	Namespace-scoped KV store for coordination	docs
Agent Messaging	Inter-agent mailbox with TTL and broadcasts	docs
Connections	Connection management and multiplexing	docs

Security & Audit

Feature	Description	Documentation
Confirmations	Explicit approval for destructive actions	docs
Audit Log	Full action history with filtering	docs
Secrets (Keyring)	Secret Service credential storage	docs
Lock/Mutex	Distributed locking primitives	docs

Infrastructure

Feature	Description	Documentation
Process Management	Spawn, signal, list, wait for processes	docs
Unified Search	Cross-surface search with relevance scoring	docs
Persistence	SQLite-backed clipboard, audit, blackboard, rules	docs
Clients	Client library support and bindings	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)

{
  "mcpServers": {
    "deskbrid": {
      "command": "deskbrid",
      "args": ["mcp"]
    }
  }
}

---

Documentation by Quill · Built with 🦊 by Tuck · Part of the Deskbrid project