{"id":49759117,"url":"https://github.com/coe0718/deskbrid","last_synced_at":"2026-05-31T21:00:50.205Z","repository":{"id":355823376,"uuid":"1229755072","full_name":"coe0718/deskbrid","owner":"coe0718","description":"Linux desktop HAL for AI agents. One daemon, one socket, every desktop action. GNOME, KDE, Hyprland, X11. Ships in one command.","archived":false,"fork":false,"pushed_at":"2026-05-31T04:08:10.000Z","size":3976,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T04:14:35.326Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coe0718.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"coe0718"}},"created_at":"2026-05-05T10:58:40.000Z","updated_at":"2026-05-31T04:08:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coe0718/deskbrid","commit_stats":null,"previous_names":["coe0718/deskbrid"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/coe0718/deskbrid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fdeskbrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fdeskbrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fdeskbrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fdeskbrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coe0718","download_url":"https://codeload.github.com/coe0718/deskbrid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coe0718%2Fdeskbrid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33748607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-11T02:55:12.334Z","updated_at":"2026-05-31T21:00:50.198Z","avatar_url":"https://github.com/coe0718.png","language":"Rust","funding_links":["https://github.com/sponsors/coe0718"],"categories":[],"sub_categories":[],"readme":"# deskbrid\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.png\" alt=\"deskbrid logo\" width=\"280\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/coe0718/deskbrid/actions\"\u003e\u003cimg src=\"https://github.com/coe0718/deskbrid/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.rust-lang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/rust-2024%20edition-orange.svg\" alt=\"Rust 2024\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/coe0718/deskbrid/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/coe0718/deskbrid?color=06b6d4\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/Hs4ryPwEs\"\u003e\u003cimg src=\"https://img.shields.io/badge/discord-join%20server-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nicklaunches.com/products/deskbrid/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Nick%20Launches-featured-8b5cf6\" alt=\"Nick Launches\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://deskbrid.patchhive.dev\"\u003e\u003cstrong\u003edeskbrid.patchhive.dev\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**[📖 Documentation](docs/wiki/INDEX.md) | [API Reference](docs/API.md) | [Architecture](docs/ARCHITECTURE.md)**\n\n---\n\nThe HAL your Linux desktop agents are missing.\n\nDeskbrid is a single Rust binary that auto-detects your desktop environment and wraps it into a JSON-over-Unix-socket protocol. GNOME, Hyprland, KDE, COSMIC, Sway, Niri, Wayfire, Labwc, Cinnamon, MATE — one daemon, one protocol, one binary.\n\n```bash\n# Human\ndeskbrid windows list\ndeskbrid clipboard read\n\n# Agent (same socket)\n{\"action\": \"windows.list\"}  →  [{\"title\": \"VS Code\", \"app_id\": \"code\", ...}]\n```\n\n## Table of Contents\n\n- [Why Deskbrid](#why-deskbrid)\n- [Supported Desktops](#supported-desktops)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Protocol](#protocol)\n- [Python Client](#python-client)\n- [MCP Integration](#mcp-integration)\n\n## Why Deskbrid\n\nEvery major AI lab is racing to ship desktop agents. AppleScript gives macOS agents native control. Windows has UI Automation. Linux has `xdotool` — which breaks on Wayland, the default display protocol for every major distro.\n\nDeskbrid fills that gap. It auto-detects your compositor and loads the right backend — GNOME (Mutter RemoteDesktop DBus), Hyprland (hyprctl + ydotool + grim), KDE (KWin D-Bus + ydotool + spectacle), wlroots-style compositors, or shared X11. Same binary, same protocol, same socket.\n\n![Demo: agent focuses VS Code window and types a command via deskbrid](docs/assets/demo.gif)\n\n### Dashboard\n\nDeskbrid ships with a built-in web dashboard at `localhost:20129` — system info, monitors, windows, network, audio, clipboard, and an audit log of agent actions, all live:\n\n**[🔴 Live Demo →](https://deskbrid.patchhive.dev/live)**\n\n![Deskbrid Dashboard — Hyprland, system overview with SSE-connected live data](docs/assets/dashboard.png)\n\n## Supported Desktops\n\n| Desktop | Session | Status | Backend |\n|---------|---------|--------|---------|\n| **GNOME 46–50** | Wayland | ✅ Supported | Mutter RemoteDesktop + Shell Extension |\n| **Hyprland** | Wayland | ✅ Supported (v0.3.0) | hyprctl + ydotool + grim |\n| **KDE Plasma** | Wayland | ✅ Supported (v0.4.0) | KWin D-Bus + ydotool + spectacle |\n| **COSMIC** | Wayland | ⚠️ Partial | cosmic-helper + cosmic-randr + ydotool + grim |\n| **Sway** | Wayland | ✅ Supported | swaymsg + ydotool + grim |\n| **Niri** | Wayland | ✅ Partial | niri msg + ydotool + grim + wlr-randr |\n| **Wayfire** | Wayland | ✅ Supported (no move/resize) | wf-ipc + ydotool + grim + wlr-randr |\n| **Labwc** | Wayland | ✅ Supported (no move/resize) | wlrctl + ydotool + grim + wlr-randr |\n| Cinnamon | X11 | ✅ Supported (shared X11) | xdotool + wmctrl + xclip + import |\n| MATE | X11 | ✅ Supported (shared X11) | xdotool + wmctrl + xclip + import |\n| X11 (generic) | X11 | ✅ Supported (shared X11) | xdotool + wmctrl + xclip + import |\n\nDeskbrid auto-detects your desktop at startup (`$XDG_CURRENT_DESKTOP` → process scan → GNOME fallback). No config files, no flags.\n\nSee **[DE Test Matrix](docs/DE_TEST_MATRIX.md)** for per-action compatibility across all desktops — every action, every compositor, tested on real hardware.\n\n## Installation\n\n**One-liner install (recommended):**\n\n```bash\nbash \u003c(curl -fsSL https://deskbrid.patchhive.dev/install.sh)\n```\n\nAuto-detects your distro and desktop environment, installs dependencies, sets up uinput, and downloads the binary.\n\n**Manual installation:**\n\nDownload the latest release binary from the [releases page](https://github.com/coe0718/deskbrid/releases):\n\n```bash\ncurl -LO https://github.com/coe0718/deskbrid/releases/latest/download/deskbrid\nchmod +x deskbrid\nsudo mv deskbrid /usr/local/bin/\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/coe0718/deskbrid\ncd deskbrid\ncargo build --release\nsudo cp target/release/deskbrid /usr/local/bin/\n```\n\n### Desktop Setup\n\n**GNOME:**\n```bash\nsudo apt install -y grim wl-clipboard python3-gi gstreamer1.0-tools gstreamer1.0-pipewire\ndeskbrid setup\n```\n\n**Hyprland (and other standalone Wayland compositors — Sway, Niri, Wayfire, Labwc):**\n```bash\nsudo pacman -S grim wl-clipboard ydotool\necho 'KERNEL==\"uinput\", GROUP=\"input\", MODE=\"0660\"' | sudo tee /etc/udev/rules.d/99-input.rules\nsudo usermod -aG input $USER\n```\n\n\u003e ⚠️ Standalone Wayland compositors don't ship a notification daemon. Deskbrid's `notify send` will hang without one. Install **dunst**, **mako**, or **swaync** and add it to your compositor's autostart.\n\n**KDE Plasma:**\n```bash\nsudo apt install spectacle imagemagick wl-clipboard ydotool\n```\n\n## Quick Start\n\n```bash\ndeskbrid daemon \u0026\n\ndeskbrid windows list          # List open windows\ndeskbrid clipboard read        # Read clipboard\ndeskbrid screenshot            # Take screenshot\ndeskbrid system info           # Get system info\ndeskbrid windows focus --app code  # Focus VS Code\ndeskbrid input keyboard type \"Hello!\"  # Type text\n```\n\n## Features\n\n### Windows \u0026 Workspaces\n\n| Action | Description |\n|--------|-------------|\n| `windows.list` | List all open windows |\n| `windows.focus` | Focus a window by app_id or title |\n| `windows.get` | Get details for a specific window |\n| `windows.close` | Request window close |\n| `windows.minimize/maximize` | Window state control |\n| `windows.move_resize` | Move and resize windows |\n| `windows.tile` | Tile to screen regions |\n| `windows.activate_or_launch` | Focus or launch app |\n| `workspaces.*` | Workspace management |\n| `layout_profiles.*` | Save/restore layouts |\n\n### Input \u0026 Clipboard\n\n| Action | Description |\n|--------|-------------|\n| `input.keyboard type` | Type text |\n| `input.keyboard key` | Send keypress |\n| `input.keyboard combo` | Send key combinations |\n| `input.mouse.*` | Mouse control |\n| `clipboard.read/write` | Clipboard access |\n| `clipboard.history` | Clipboard history |\n\n### Screenshots \u0026 Media\n\n| Action | Description |\n|--------|-------------|\n| `screenshot` | Screen capture |\n| `screenshot.ocr` | Extract text via Tesseract |\n| `screenshot.diff` | Compare screenshots |\n| `mpris.*` | Media player control |\n| `color.pick` | Sample pixel colors |\n\n### System \u0026 Services\n\n| Action | Description |\n|--------|-------------|\n| `system.info` | Desktop information |\n| `system.battery` | Battery status |\n| `system.idle` | Idle detection |\n| `system.power` | Power management |\n| `service.*` | systemd units |\n| `journal.query` | Log inspection |\n| `terminal.*` | PTY sessions |\n| `monitor.*` | Display control |\n\n### Network \u0026 Bluetooth\n\n| Action | Description |\n|--------|-------------|\n| `network.*` | WiFi status/connect |\n| `bluetooth.*` | Device pairing/control |\n\n## Protocol\n\nDeskbrid uses JSON-over-Unix-socket. See [PROTOCOL.md](docs/PROTOCOL.md) for the complete specification.\n\n```json\n→ {\"action\": \"windows.list\"}\n← {\"type\": \"response\", \"status\": \"ok\", \"data\": [{\"title\": \"VS Code\", ...}]}\n\n→ {\"action\": \"windows.focus\", \"window_id\": \"code\"}\n← {\"type\": \"response\", \"status\": \"ok\"}\n```\n\n### Events\n\nSubscribe to real-time updates:\n\n```json\n{\"action\": \"subscribe\", \"events\": [\"file.*\"]}\n```\n\n## Python Client\n\n```python\nfrom deskbrid import Deskbrid\n\nclient = Deskbrid()\n\n# List and focus VS Code\nwindows = client.windows_list()\ncode_window = next((w for w in windows if w.app_id == 'code'), None)\nif code_window:\n    client.focus_window(app_id='code')\n    client.type_text(\"Fixed the bug!\\n\")\n\n# Subscribe to events\n@client.on(\"file.*\")\ndef on_file_change(event):\n    print(f\"File changed: {event['path']}\")\n```\n\n## MCP Integration\n\nDeskbrid exposes a full Model Context Protocol server for AI coding tools:\n\n```bash\ndeskbrid mcp\n```\n\n**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"deskbrid\": {\n      \"command\": \"/usr/local/bin/deskbrid\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n**Available MCP tools (20+):**\n- `list_windows`, `focus_window`\n- `type_text`, `press_keys`, `mouse_move`, `mouse_click`\n- `screenshot`, `clipboard_read`, `clipboard_write`\n- `list_apps`, `get_accessibility_tree`\n- `perform_action`, `set_element_value`, `get_element_text`, `click_element`\n- `doctor`, `setup_accessibility`, `capabilities`\n\n## Compared to Alternatives\n\n| Tool | Wayland | Agent-native | JSON | Windows | Input | Clipboard | Screenshot | Bluetooth | Audio |\n|------|---------|--------------|------|---------|-------|-----------|------------|-----------|-------|\n| **deskbrid** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| xdotool | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| ydotool | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| grim | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |\n| wl-clipboard | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |\n\n## License\n\nMIT\n\n## How This Started\n\nDeskbrid began with Tuck — an autonomous agent that needed to control a real Linux desktop. When the community asked for Hyprland support, Tuck asked Jeremy for a bare Arch Linux box with SSH and sudo. He installed Hyprland himself and built the backend from inside the environment he just configured.\n\nThe first working demo was a Telegram message: Tuck focused a window and typed \"Hello from the other side\" in under 60 seconds. That moment — an agent controlling a real desktop through a Unix socket — became Deskbrid. It's built for agents first: same protocol for humans on the CLI, same socket for AIs, one binary that works everywhere.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoe0718%2Fdeskbrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoe0718%2Fdeskbrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoe0718%2Fdeskbrid/lists"}