mirror of
https://github.com/harivansh-afk/deskctl.git
synced 2026-04-15 07:04:46 +00:00
handwrite docs
This commit is contained in:
parent
95d4f9d401
commit
481880effa
4 changed files with 20 additions and 166 deletions
|
|
@ -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.
|
||||
|
|
@ -8,68 +8,43 @@ import DocLayout from "../layouts/DocLayout.astro";
|
|||
<img src="/favicon.svg" alt="" width="40" height="40" />
|
||||
</header>
|
||||
|
||||
<p class="tagline">non-interactive desktop control for AI agents</p>
|
||||
<p class="tagline">non-interactive desktop control cli for AI agents</p>
|
||||
|
||||
<p class="lede">
|
||||
<code>deskctl</code> 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.
|
||||
</p>
|
||||
|
||||
<pre><code>{`npm install -g deskctl
|
||||
deskctl doctor
|
||||
deskctl snapshot --annotate`}</code></pre>
|
||||
|
||||
<h2>Start</h2>
|
||||
|
||||
<p>
|
||||
Install the CLI, verify the runtime, then run the core observe -> wait
|
||||
-> act -> verify loop.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/installation">Installation</a> - install paths, runtime requirements,
|
||||
and first-run checks
|
||||
<a href="/installation">Installation</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/quick-start">Quick start</a> - the minimal workflow for real desktop
|
||||
control
|
||||
<a href="/quick-start">Quick start</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2>Reference</h2>
|
||||
|
||||
<p>
|
||||
Read the command surface, the daemon/runtime model, and the stable JSON
|
||||
contract.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/commands">Commands</a> - grouped reads, waits, actions, selectors,
|
||||
and global flags
|
||||
<a href="/commands">Commands</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/architecture">Architecture</a> - client/daemon model, sessions, sockets,
|
||||
and support boundary
|
||||
</li>
|
||||
<li>
|
||||
<a href="/runtime-contract">Runtime contract</a> - stable JSON fields, errors,
|
||||
and best-effort text behavior
|
||||
<a href="/runtime-contract">Runtime contract</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2>Links</h2>
|
||||
|
||||
<p>
|
||||
The repo is the source of truth for the CLI, the skill, and the release
|
||||
assets.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<a href="https://github.com/harivansh-afk/deskctl">GitHub</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://www.npmjs.com/package/deskctl">npm</a>
|
||||
</li>
|
||||
</ul>
|
||||
</DocLayout>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue