mcpField
D
deskctl

deskctl

github.com/harivansh-afkAgent workflows1762 installsUpdated 1w ago
Repository

About deskctl

deskctl is a non-interactive desktop control CLI for Linux X11 agents. It uses an observe, wait, act, and verify loop, with stable JSON output for programmatic use.

Key features

  1. 01Control Linux X11 desktops
  2. 02Observe and annotate screen snapshots
  3. 03Wait for window conditions
  4. 04Select windows by title, class, or ID
  5. 05Stable JSON output for commands

Use cases

  1. 01Automating desktop interactions for an agent
  2. 02Waiting for a specific window before acting
  3. 03Parsing command results programmatically

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/harivansh-afk/deskctl --skill deskctl

After installing, type/deskctlin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
commands.md
runtime-contract.md
workflows/
observe-act.sh
poll-condition.sh

Details

From the project README

deskctl

Non-interactive desktop control CLI for Linux X11 agents.

All output follows the runtime contract defined in references/runtime-contract.md. Every command returns a stable JSON envelope when called with --json. Use --json whenever you need to parse output programmatically.

Quick start

npm install -g deskctl
deskctl doctor
deskctl snapshot --annotate

If deskctl was installed through npm, refresh it later with:

deskctl upgrade --yes

Agent loop

Every desktop interaction follows: observe -> wait -> act -> verify.

deskctl snapshot --annotate        # observe
deskctl wait window --selector 'title=Chromium' --timeout 10  # wait
deskctl click 'title=Chromium'      # act
deskctl snapshot                   # verify

See workflows/observe-act.sh for a reusable script. See workflows/poll-condition.sh for polling loops.

Selectors

ref=w1          # snapshot ref (short-lived)
id=win1         # stable window ID (session-scoped)
title=Chromium   # match by title
class=chromium   # match by WM class
focused         # currently focused window

Bare strings like chromium do fuzzy matching but fail on ambiguity. Prefer explicit selectors.

References

Workflows

Comments

Markdown supported