Integrations Python

Python Client

Use Deskbrid from Python applications.

Installation

pip install deskbrid

Or install from source:

git clone https://github.com/coe0718/deskbrid
cd deskbrid/clients/python
pip install -e .

Quick Start

from deskbrid import Deskbrid

# Connect to daemon
client = Deskbrid()

# List windows
windows = client.list_windows()
for w in windows:
    print(f"{w.app_id}: {w.title}")

# Focus VS Code
client.focus_window(app_id="code")

# Type something
client.type_text("Hello from Python!")

Async Client

from deskbrid import AsyncDeskbrid
import asyncio

async def main():
    async with AsyncDeskbrid() as client:
        windows = await client.list_windows()
        print(f"Found {len(windows)} windows")

asyncio.run(main())

Client Types

SyncDeskbrid

Blocking synchronous client:

from deskbrid import SyncDeskbrid

client = SyncDeskbrid()
windows = client.list_windows()  # Blocks until response

AsyncDeskbrid

Async context manager:

from deskbrid import AsyncDeskbrid

async with AsyncDeskbrid() as client:
    windows = await client.list_windows()

Shared Async/Sync Client

The main Deskbrid class provides both:

client = Deskbrid()

# Sync methods (blocking)
windows = client.list_windows()
client.type_text("sync text")

# Internal async client for mixing modes
async def some_async_func():
    async with client._client() as async_client:
        await async_client.type_text("async text")

Available Methods

Windows

client.list_windows()           # List all windows
client.focus_window(app_id="code")  # Focus by app ID
client.focus_window(title="Terminal")  # Focus by title
client.activate_or_launch("firefox")  # Launch or focus
client.tile_window(window_id, preset="left")

Input

client.type_text("Hello!")
client.send_keys(["Ctrl_L", "c"])
client.mouse_click(x=100, y=200)
client.mouse_move(x=500, y=300)
client.mouse_scroll(dy=3)

Clipboard

content = client.clipboard_read()  # Returns ClipboardContent
client.clipboard_write("New text")
history = client.clipboard_history(limit=10)

Screenshots

path = client.screenshot()  # Returns screenshot path
result = client.screenshot_ocr()  # Returns dict with text
diff = client.screenshot_diff("/before.png", "/after.png")

System

info = client.info()  # Returns DaemonInfo object
battery = client.battery()  # Returns dict with battery info
client.system_power("suspend")

Media

players = client.mpris_list()
client.mpris_control("play")
client.mpris_control("next")

Terminals

result = client.terminal_create()
term_id = result["terminal_id"]
client.terminal_write(term_id, "ls -la\n")
output = client.terminal_read(term_id)
client.terminal_kill(term_id)

Error Handling

from deskbrid.errors import DeskbridError

try:
    client.focus_window(app_id="nonexistent")
except DeskbridError as e:
    print(f"Error: {e.code} - {e.message}")

Connection Options

from deskbrid import Deskbrid

# Custom socket path
client = Deskbrid(socket_path="/tmp/custom.sock")

# With reconnect delay
client = Deskbrid(reconnect_delay=2.0)

Running Multiple Clients

# Each client has its own connection
client1 = Deskbrid()
client2 = Deskbrid()

# Use different clients for different tasks concurrently

Integration with AI Frameworks

LangChain

from langchain.tools import tool
from deskbrid import Deskbrid

client = Deskbrid()

@tool
def type_text_tool(text: str) -> str:
    """Type text into the focused window."""
    client.type_text(text)
    return f"Typed: {text}"

LlamaIndex

from llama_index.core.tools import FunctionTool
from deskbrid import Deskbrid

client = Deskbrid()

def take_screenshot() -> str:
    """Take a screenshot and return the path."""
    result = client.screenshot()
    return result.path

screenshot_tool = FunctionTool.from_defaults(
    fn=take_screenshot,
    name="take_screenshot",
    description="Take a screenshot of the desktop"
)

Method Reference

All methods return objects (not raw dicts), with synchronous wrappers provided via SyncDeskbrid:

Windows

client.list_windows()           # Returns list[WindowInfo]
client.focus_window(app_id="code")  # None
client.activate_or_launch(app_id, command=None, workdir=None, env=None)  # Returns dict
client.tile_window(window_id, preset, monitor=None, padding=None)  # Returns dict

Input

client.type_text("Hello!")      # None (fire-and-forget)
client.send_keys(["Ctrl_L", "c"])  # None
client.mouse_click(x=100, y=200, button="left")  # None
client.mouse_move(x=500, y=300)  # None
client.mouse_scroll(dy=3)        # None
client.mouse_drag(from_x, from_y, to_x, to_y, button="left", duration_ms=None)  # Returns dict

Clipboard

content = client.clipboard_read()  # Returns ClipboardContent object
client.clipboard_write("New text")  # None
history = client.clipboard_history(limit=10)  # Returns list[dict]

Screenshots

result = client.screenshot(monitor=None)  # Returns ScreenshotResult with .path attribute
result = client.screenshot_ocr(path=None, language=None, monitor=None, region=None)  # Returns dict
result = client.screenshot_diff("/before.png", "/after.png")  # Returns dict

System

info = client.info()  # Returns DaemonInfo object
battery = client.battery()  # Returns dict
backlight = client.backlight_get()  # Returns dict
client.backlight_set(percent=0.5)  # Returns dict
thermal = client.thermal()  # Returns dict
freq = client.cpu_frequency()  # Returns dict
gov = client.cpu_governor()  # Returns dict
client.cpu_set_governor("performance")  # Returns dict

# Session/system control
inhibit = client.inhibit_system("suspend", who="backup", why="backup running")
client.release_inhibit(inhibit["inhibitor_id"])
sessions = client.list_sessions()
client.lock_session()
client.switch_user("alice")
auth = client.check_auth("system.power")
client.elevate("system.power", reason="rebooting")
conf = client.confinement()

Services

client.service_status(name)
client.service_start(name)
client.service_stop(name)
client.service_restart(name)
client.service_enable(name, runtime=False)
client.service_disable(name, runtime=False)
client.service_list(unit_type=None)

Timers

client.timer_list()
client.timer_start(name)
client.timer_stop(name)

Audit

client.audit_log(limit=None, action_type=None, status=None)  # Returns list[dict]
client.audit_clear()  # Returns dict

Wait For

client.wait_for(condition, params=None, timeout_ms=30000, interval_ms=None)  # Returns dict