harivansh-afk/deskctl
1
1
Fork 0
mirror of https://github.com/harivansh-afk/deskctl.git synced 2026-04-15 04:03:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Desktop control CLI for AI agents https://deskctl.dev
28 commits 13 branches 15 tags 568 KiB
Find a file
Harivansh Rathi a6ea5cc9e8 changes (detect paths + calculate version) 
|
build [cargo, docker]  (parallel matrix)
|
update-manifests (bump Cargo.toml, commit, tag)
|
release (GitHub release + checksums)
2026-03-25 16:54:11 -04:00
.github/workflows changes (detect paths + calculate version) 2026-03-25 16:54:11 -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
site favicon 2026-03-25 16:24:27 -04:00
src gitignore and comment 2026-03-25 15:16:42 -04:00
.dockerignore docker-compose build 2026-03-25 12:40:14 -04:00
.gitignore gitignore 2026-03-25 16:25:14 -04:00
AGENTS.md Phase 6: utility commands, SKILL.md, AGENTS.md, README.md 2026-03-24 21:40:29 -04:00
Cargo.lock Rewrite X11 backend to drop xcap 2026-03-25 12:28:23 -04:00
Cargo.toml rename 2026-03-25 12:28:38 -04:00
README.md Acknowledgements 2026-03-25 16:31:15 -04:00
SKILL.md rename 2026-03-24 22:59:21 -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

# 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

Wayland Support

Coming soon. The trait-based backend design means adding Hyprland/Wayland support is a single trait implementation with zero refactoring of the core which is good.

Acknowledgements