diff --git a/site/src/pages/architecture.mdx b/site/src/pages/architecture.mdx deleted file mode 100644 index 070b73b..0000000 --- a/site/src/pages/architecture.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -layout: ../layouts/DocLayout.astro -title: Architecture -toc: true ---- - -# Architecture - -`deskctl` is not trying to be a desktop environment abstraction layer. The -design goal is a small, unsurprising Linux X11 control primitive that agents -can discover and compose progressively. - -## Public model - -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 and daemon - -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 boundary - -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. diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index 21936ee..b914e16 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -8,68 +8,43 @@ import DocLayout from "../layouts/DocLayout.astro"; -

non-interactive desktop control for AI agents

+

non-interactive desktop control cli for AI agents

- deskctl is a thin X11 control primitive for agent loops: diagnose - the runtime, observe the desktop, wait for state transitions, act deterministically, - then verify. + A thin X11 control primitive for agent loops: diagnose the runtime, observe + the desktop, wait for state transitions, act deterministically, then verify.

- 
{`npm install -g deskctl
-deskctl doctor
-deskctl snapshot --annotate`}
-

Start

-

- Install the CLI, verify the runtime, then run the core observe -> wait - -> act -> verify loop. -

-

Reference

-

- Read the command surface, the daemon/runtime model, and the stable JSON - contract. -

-

Links

-

- The repo is the source of truth for the CLI, the skill, and the release - assets. -

- diff --git a/site/src/pages/installation.mdx b/site/src/pages/installation.mdx index 2f13ac3..e35f4eb 100644 --- a/site/src/pages/installation.mdx +++ b/site/src/pages/installation.mdx @@ -22,23 +22,15 @@ downloading the matching GitHub Release asset for the supported runtime target. This path does not require a Rust toolchain. The installed command is always `deskctl`, even though the release asset itself is target-specific. -## Quick try without a global install +## Skill install + +The repo skill lives under `skills/deskctl`, so you can install it +directly uring `skills.sh` ```sh -npx deskctl --help +npx skills add harivansh-afk/deskctl ``` -This is useful when you only need a temporary run or want to smoke-test a -machine before deciding how to install it permanently. - -## What the npm install does - -- downloads the matching GitHub Release asset for the current supported target -- exposes the public command as `deskctl` -- keeps the install path operator-friendly: no source build, no manual rename - -Today the npm distribution is aimed at Linux x64 X11 environments. - ## Other install paths ### Nix @@ -48,7 +40,7 @@ nix run github:harivansh-afk/deskctl -- --help nix profile install github:harivansh-afk/deskctl ``` -### Build from source +### Rust ```sh git clone https://github.com/harivansh-afk/deskctl @@ -62,17 +54,6 @@ Source builds on Linux require: - `pkg-config` - X11 development libraries such as `libx11-dev` and `libxtst-dev` -## Skill install - -The repo skill lives under `skills/deskctl`, so `skills` can install it -directly from this GitHub repo. It is designed around the same observe -> wait --> act -> verify loop as the CLI. `-g` installs it globally; omit that flag if -you want a project-local install. - -```sh -npx skills add harivansh-afk/deskctl -s deskctl -``` - ## Runtime requirements - Linux with an active X11 session @@ -83,9 +64,9 @@ npx skills add harivansh-afk/deskctl -s deskctl The binary itself only depends on the standard Linux glibc runtime. -## First troubleshooting step +## Verification -If setup fails, start here: +If setup fails for any reason start here: ```sh deskctl doctor diff --git a/site/src/pages/quick-start.mdx b/site/src/pages/quick-start.mdx index ac51600..7ecf5a7 100644 --- a/site/src/pages/quick-start.mdx +++ b/site/src/pages/quick-start.mdx @@ -6,8 +6,7 @@ toc: true # Quick start -The fastest way to use `deskctl` is to follow the same four-step loop every -time: observe, wait, act, verify. +The fastest way to use `deskctl` is to follow the same four-step loop : observe, wait, act, verify. ## 1. Install and diagnose @@ -16,7 +15,7 @@ npm install -g deskctl deskctl doctor ``` -Use `deskctl doctor` first. It checks X11 connectivity, basic enumeration, +Run `deskctl doctor` first. It checks X11 connectivity, basic enumeration, screenshot viability, and socket health before you start driving the desktop. ## 2. Observe the desktop