harivansh-afk/deskctl
1
1
Fork 0
mirror of https://github.com/harivansh-afk/deskctl.git synced 2026-04-15 10:05:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Desktop control CLI for AI agents https://deskctl.dev
37 commits 13 branches 15 tags 569 KiB
Find a file
Harivansh Rathi 3c08e6003d add tests to CI
2026-03-25 19:04:35 -04:00
.claude openspec init (#2) 2026-03-25 17:31:55 -04:00
.codex/skills openspec init (#2) 2026-03-25 17:31:55 -04:00
.github/workflows add tests to CI 2026-03-25 19:04:35 -04:00
assets Phase 3: screenshot annotation with bounding boxes and @wN labels 2026-03-24 21:28:10 -04:00
docker docker-compose build 2026-03-25 12:40:14 -04:00
openspec init openspec 2026-03-25 18:46:42 -04:00
site favicon 2026-03-25 16:24:27 -04:00
skills mv skills into own dir 2026-03-25 18:36:21 -04:00
src clean out src, move mod into lib, remove trash 2026-03-25 19:04:03 -04:00
tests create tests 2026-03-25 19:04:12 -04:00
.dockerignore docker-compose build 2026-03-25 12:40:14 -04:00
.gitignore openspec init (#2) 2026-03-25 17:31:55 -04:00
.pre-commit-config.yaml pre-commit hook 2026-03-25 19:04:21 -04:00
AGENTS.md Phase 6: utility commands, SKILL.md, AGENTS.md, README.md 2026-03-24 21:40:29 -04:00
Cargo.lock release: v0.1.1 [skip ci] 2026-03-25 22:34:39 +00:00
Cargo.toml release: v0.1.1 [skip ci] 2026-03-25 22:34:39 +00:00
README.md stabilize (#3) 2026-03-25 18:31:08 -04:00

README.md

deskctl

Desktop control CLI for AI agents on Linux X11.

Install

cargo install deskctl

Build a Linux binary with Docker:

docker compose -f docker/docker-compose.yml run --rm build

This writes dist/deskctl-linux-x86_64.

Copy it to an SSH machine where scp is unavailable:

ssh -p 443 deskctl@ssh.agentcomputer.ai 'cat > ~/deskctl && chmod +x ~/deskctl' < dist/deskctl-linux-x86_64

Run it on an X11 session:

DISPLAY=:1 XDG_SESSION_TYPE=x11 ~/deskctl --json snapshot --annotate

Local source build requirements:

cargo build

At the moment there are no extra native build dependencies beyond a Rust toolchain.

Quick Start

# Diagnose the environment first
deskctl doctor

# See the desktop
deskctl snapshot

# Click a window
deskctl click @w1

# Type text
deskctl type "hello world"

# Focus by name
deskctl focus "firefox"

Architecture

Client-daemon architecture over Unix sockets (NDJSON wire protocol). The daemon starts automatically on first command and keeps the X11 connection alive for fast repeated calls.

Runtime Requirements

  • Linux with X11 session
  • Rust 1.75+ (for build)

The binary itself only links the standard glibc runtime on Linux (libc, libm, libgcc_s).

For deskctl to be fully functional on a fresh VM you still need:

  • an X11 server and an active DISPLAY
  • XDG_SESSION_TYPE=x11 or an equivalent X11 session environment
  • a window manager or desktop environment that exposes standard EWMH properties such as _NET_CLIENT_LIST_STACKING and _NET_ACTIVE_WINDOW
  • an X server with the extensions needed for input simulation and screen metadata, which is standard on normal desktop X11 setups

If setup fails, run:

deskctl doctor

Contract Notes

  • @wN refs are short-lived handles assigned by snapshot and list-windows
  • --json output includes a stable window_id for programmatic targeting within the current daemon session
  • list-windows is a cheap read-only operation and does not capture or write a screenshot

Support Boundary

deskctl supports Linux X11 in this phase. Wayland and Hyprland are explicitly out of scope for the current runtime contract.

Acknowledgements