mirror of
https://github.com/harivansh-afk/deskctl.git
synced 2026-04-15 08:03:43 +00:00
98 lines
2.7 KiB
Text
98 lines
2.7 KiB
Text
---
|
|
layout: ../layouts/DocLayout.astro
|
|
title: Architecture
|
|
toc: true
|
|
---
|
|
|
|
# Architecture
|
|
|
|
## Public model
|
|
|
|
`deskctl` is a thin, non-interactive X11 control primitive for agent loops.
|
|
The public flow is:
|
|
|
|
- diagnose with `deskctl doctor`
|
|
- observe with `snapshot`, `list-windows`, and grouped `get` commands
|
|
- wait with grouped `wait` commands instead of shell `sleep`
|
|
- act with explicit selectors or coordinates
|
|
- verify with another read or snapshot
|
|
|
|
The tool stays intentionally narrow. It does not try to be a full desktop shell
|
|
or a speculative Wayland abstraction.
|
|
|
|
## Client-daemon architecture
|
|
|
|
The CLI talks to an auto-managed daemon over a Unix socket. The daemon keeps
|
|
the X11 connection alive so repeated commands stay fast and share the same
|
|
session-scoped window identity map.
|
|
|
|
Each CLI invocation sends one request, reads one response, and exits.
|
|
|
|
## Runtime contract
|
|
|
|
Requests and responses are newline-delimited JSON (NDJSON) over a Unix socket.
|
|
|
|
All commands share the same JSON envelope:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {},
|
|
"error": null
|
|
}
|
|
```
|
|
|
|
For window payloads, the public identity is `window_id`, not an X11 handle.
|
|
That keeps the contract backend-neutral even though the current support
|
|
boundary is X11-only.
|
|
|
|
The complete stable-vs-best-effort policy lives on the
|
|
[runtime contract](/runtime-contract) page.
|
|
|
|
## Sessions and sockets
|
|
|
|
Each session gets its own socket path, PID file, and live window mapping.
|
|
|
|
Public socket resolution order:
|
|
|
|
1. `--socket`
|
|
2. `DESKCTL_SOCKET_DIR/{session}.sock`
|
|
3. `XDG_RUNTIME_DIR/deskctl/{session}.sock`
|
|
4. `~/.deskctl/{session}.sock`
|
|
|
|
Most users should let `deskctl` manage this automatically. `--session` is the
|
|
main public knob when you need isolated daemon instances.
|
|
|
|
## Diagnostics and failure handling
|
|
|
|
`deskctl doctor` runs before daemon startup and checks:
|
|
|
|
- display/session setup
|
|
- X11 connectivity
|
|
- basic window enumeration
|
|
- screenshot viability
|
|
- socket directory and stale-socket health
|
|
|
|
Selector and wait failures are structured in `--json` mode so clients can
|
|
recover without scraping text.
|
|
|
|
## Backend notes
|
|
|
|
The backend is built around a `DesktopBackend` trait and currently ships with
|
|
an X11 implementation backed by `x11rb`.
|
|
|
|
The important public guarantee is not "portable desktop automation." The
|
|
important guarantee is "a correct and unsurprising Linux X11 runtime contract."
|
|
|
|
## X11 support boundary
|
|
|
|
This phase supports Linux X11 only.
|
|
|
|
That means:
|
|
|
|
- EWMH/window-manager properties matter
|
|
- monitor naming and some ordering details are best-effort
|
|
- Wayland and Hyprland are out of scope for the current contract
|
|
|
|
The runtime documents those boundaries explicitly instead of pretending the
|
|
surface is broader than it is.
|