deskbrid: Instructions file for Codex

Deskbrid

Deskbrid bridges AI agents to any Linux desktop over a Unix socket. Control windows, inject keystrokes, take screenshots, manage clipboards — on GNOME, KDE, Hyprland, COSMIC, Sway, Niri, Wayfire, Labwc, or X11.

Install

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

Auto-detects distro + DE, installs deps, sets up uinput, downloads binary.

Quick Start

deskbrid daemon                               # start daemon
deskbrid windows list                         # CLI: list windows
deskbrid clipboard read                       # CLI: read clipboard
deskbrid screenshot                           # CLI: screenshot

# Socket (agent-native)
echo '{"type":"system.info","id":"1"}' | nc -U $XDG_RUNTIME_DIR/deskbrid.sock -w 2
echo '{"type":"windows.list","id":"2"}' | nc -U $XDG_RUNTIME_DIR/deskbrid.sock -w 2

Features

• Windows & Workspaces — list, focus, close, minimize, maximize, tile, move/resize
• Input — keyboard typing, key combos, mouse control
• Clipboard — read/write with history
• Screenshots — capture, OCR, diffing
• System — info, battery, idle, power management, pressure (PSI)
• Audio — volume, mute, sink management
• Network & Bluetooth — WiFi, device pairing
• Vision — element detection, text recognition, state detection via Tesseract OCR (vision.find_element, vision.find_by_text, vision.detect_state)
• Storage — disk usage stats and filesystem scanning (storage.usage, storage.scan)
• Monitor DDC/CI — brightness, contrast, input source, power over I2C without compositor
• MPRIS — media player control
• Terminal — PTY sessions
• Files — search, read, write, watch
• Notifications — send, dismiss, history
• Speech — text-to-speech via spd-say/espeak-ng (speech.speak, speech.stop, speech.voices)
• Keyboard Layouts — list, switch, add, remove
• Desktop Settings — gsettings read/write, schema discovery (GNOME, KDE, X11, Hyprland, Sway, COSMIC, Labwc, Niri, Wayfire)
• Backlight — list, get, set brightness via sysfs (all backends)
• Print — list printers, set default, list/cancel/pause/resume jobs, send files to printer (CUPS)
• Self-update — deskbrid update pulls latest from GitHub releases
• Confirmation Mode — require explicit approval for destructive actions before execution
• Agent Messaging — inter-agent mailbox for message passing between sessions
• Unified Search — cross-surface search (windows, apps, files, clipboard, audit log) with relevance scoring
• Keyring Access — Secret Service integration for secure credential storage and retrieval
• Rate Limiting — per-namespace, per-agent token bucket limits (configurable via permissions.toml)
• Sandboxed Profiles — named agent profiles with allow/deny/confirm gates, profile-scoped rate limits
• Auto-Suspend — dangerous command blocking, burst detection, heartbeat timeout canary suspension
• Locks — distributed resource locks for multi-agent coordination with token-based ownership
• Region Watching — screen region monitoring with text-change detection
• Agent Registry — session and agent tracking for multi-agent coordination