deskpilot 0.2.0__tar.gz

deskpilot-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "deskpilot",
+  "description": "deskpilot: desktop control for agents on Hyprland, without taking the user's pointer.",
+  "owner": {
+    "name": "Cillian Berragan",
+    "url": "https://github.com/cjber"
+  },
+  "plugins": [
+    {
+      "name": "deskpilot",
+      "description": "Click, scroll and type in Hyprland windows from a screenshot, in Wayland, XWayland and Wine apps, while the user keeps their pointer and focus.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

deskpilot-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "deskpilot",
+  "version": "0.2.0",
+  "description": "Desktop control for agents on Hyprland: screenshot a window, then click, scroll and type at points in it while the user keeps their own pointer and keyboard focus. Works in native Wayland, XWayland and Wine apps, games included.",
+  "author": {
+    "name": "Cillian Berragan",
+    "url": "https://github.com/cjber"
+  },
+  "homepage": "https://github.com/cjber/deskpilot",
+  "repository": "https://github.com/cjber/deskpilot",
+  "license": "MIT",
+  "keywords": ["agent-skills", "hyprland", "wayland", "desktop-automation", "computer-use", "mcp"]
+}

deskpilot-0.2.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,29 @@
+name: Bug
+description: deskpilot did the wrong thing
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: The command you ran, what you expected, and what happened instead. A click or key that reached the wrong window is the most serious kind of bug, so say so.
+    validations:
+      required: true
+  - type: textarea
+    id: window
+    attributes:
+      label: Target window
+      description: The window's entry from `deskpilot --json windows`, and whether it is native Wayland, XWayland or Wine.
+      render: json
+  - type: input
+    id: hyprland
+    attributes:
+      label: Hyprland version
+      description: Output of `hyprctl version | head -1`.
+    validations:
+      required: true
+  - type: input
+    id: plugin
+    attributes:
+      label: Plugin status
+      description: Output of `deskpilot plugin status`.

deskpilot-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: https://github.com/cjber/deskpilot/security/advisories/new
+    about: Report vulnerabilities privately.

deskpilot-0.2.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,16 @@
+name: Feature
+description: Suggest an action or a change
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What an agent cannot do today, and in which app.
+    validations:
+      required: true
+  - type: textarea
+    id: user
+    attributes:
+      label: What the user must keep
+      description: How the user's own pointer, focus and typing should be affected while it runs.

deskpilot-0.2.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: daily
+    cooldown:
+      default-days: 1
+    groups:
+      dependencies:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+    cooldown:
+      default-days: 1
+    groups:
+      actions:
+        patterns: ["*"]

deskpilot-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What changed and why
+
+<!-- One or two sentences. Link the issue it fixes: "Fixes #123". -->
+
+## Evidence
+
+<!-- How you checked it. For a change to clicks or keys, name the clients you tried (Wayland, XWayland, Wine). -->
+
+## Checklist
+
+- [ ] The checks in `AGENTS.md` pass
+- [ ] `CHANGELOG.md` has a line under Unreleased, if a user would notice the change
+- [ ] `README.md` and `skills/deskpilot/SKILL.md` match any command or flag change

deskpilot-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.18"
+          python-version: "3.13"
+          enable-cache: false
+      - run: uv sync --locked
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync ty check
+      - name: Check CHANGELOG.md
+        run: python3 scripts/changelog.py --check
+
+  test:
+    name: Test Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python: ["3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.18"
+          python-version: ${{ matrix.python }}
+          enable-cache: false
+      - run: uv sync --locked
+      - run: uv run --no-sync pytest -q
+
+  workflows:
+    name: Workflow checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.18"
+          enable-cache: false
+      - name: Check workflow syntax
+        env:
+          ACTIONLINT_SHA256: 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+        run: |
+          curl --fail --silent --show-error --location \
+            https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz \
+            --output "$RUNNER_TEMP/actionlint.tar.gz"
+          printf '%s  %s\n' "$ACTIONLINT_SHA256" "$RUNNER_TEMP/actionlint.tar.gz" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/actionlint.tar.gz" -C "$RUNNER_TEMP" actionlint
+          "$RUNNER_TEMP/actionlint" -color
+      - name: Check workflow security
+        run: uvx zizmor==1.30.1 --offline --pedantic .github/workflows
+
+  secrets:
+    name: Secret scanning
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Scan repository history
+        env:
+          GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+        run: |
+          curl --fail --silent --show-error --location \
+            https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz \
+            --output "$RUNNER_TEMP/gitleaks.tar.gz"
+          printf '%s  %s\n' "$GITLEAKS_SHA256" "$RUNNER_TEMP/gitleaks.tar.gz" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/gitleaks.tar.gz" -C "$RUNNER_TEMP" gitleaks
+          "$RUNNER_TEMP/gitleaks" git --redact --no-banner --log-opts="--all" .

deskpilot-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+# Pushing a vX.Y.Z tag publishes a GitHub release whose notes are that version's CHANGELOG.md entry, then uploads
+# the package to PyPI through trusted publishing. The tag must be on main, where CI has already checked the commit.
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: GitHub release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write # create the release
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check the tag is on main and matches both versions
+        run: |
+          set -euo pipefail
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+          version=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          plugin=$(jq -r .version .claude-plugin/plugin.json)
+          if [ "v$version" != "$GITHUB_REF_NAME" ] || [ "$plugin" != "$version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME, pyproject.toml $version and plugin.json $plugin must match"
+            exit 1
+          fi
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+
+      - name: GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          python3 scripts/changelog.py "$VERSION" > "$RUNNER_TEMP/notes.md"
+          # A rerun finds the release already there and leaves it.
+          if ! gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md"
+          fi
+
+  pypi:
+    name: PyPI
+    needs: release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/deskpilot/
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.18"
+          enable-cache: false
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

deskpilot-0.2.0/.github/zizmor.yml

@@ -0,0 +1,5 @@
+rules:
+  # Dependabot waits one day before proposing a release; zizmor's default floor is seven.
+  dependabot-cooldown:
+    config:
+      days: 1

deskpilot-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

deskpilot-0.2.0/.mergepatrol/mergepatrol.yml

@@ -0,0 +1,20 @@
+# Mergepatrol reads this file from the default branch. The dashboard opens a PR to change it.
+version: 1
+label: mergepatrol
+batch_size: 4
+resolver:
+  provider: anthropic
+  model: claude-opus-5-5
+  effort: medium
+# Run in Mergepatrol's sandbox after an agent resolves a conflict or commits a fix, before anything is pushed.
+# They mirror CI's lint and test jobs. The job image has no uv, so the first command installs the version CI uses.
+verify:
+  - curl -LsSf https://astral.sh/uv/0.12.18/install.sh | sh
+  - ~/.local/bin/uv sync --locked
+  - ~/.local/bin/uv run --no-sync ruff check .
+  - ~/.local/bin/uv run --no-sync ruff format --check .
+  - ~/.local/bin/uv run --no-sync ty check
+  - ~/.local/bin/uv run --no-sync pytest -q
+fix_ci:
+  enabled: true
+  attempts: 2

deskpilot-0.2.0/AGENTS.md

@@ -0,0 +1,50 @@
+# deskpilot
+
+Desktop control for agents on Hyprland: screenshot a window, click or type at a point in it, and leave the user's
+own pointer and keyboard focus where they were. The CLI and the MCP server are thin layers over the same `Desk`.
+
+## Checks
+
+```sh
+uv sync --locked
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+uv run pytest
+python3 scripts/changelog.py --check
+claude plugin validate --strict .   # if the Claude Code CLI is installed
+```
+
+CI also runs actionlint, zizmor and gitleaks. The plugin is not built in CI: it needs the exact Hyprland it loads
+into, so check a change to `plugin/deskpilot.cpp` with `deskpilot plugin load` on a real session.
+
+## Layout
+
+- `src/deskpilot/cli.py`: argument parsing and output; every command calls `Desk`
+- `src/deskpilot/mcp_server.py`: the same actions as MCP tools over stdio, one `Desk` for the session
+- `src/deskpilot/desk.py`: the actions an agent takes, shared by the CLI and the MCP server
+- `src/deskpilot/hypr.py`: hyprctl: windows, monitors, focus, the cursor, and picking the live instance
+- `src/deskpilot/plugin.py`: builds, loads and talks to the compositor plugin
+- `src/deskpilot/plugin/deskpilot.cpp`: the Hyprland plugin that runs each click, scroll and keystroke inside the
+  compositor and puts the user's pointer and focus back
+- `src/deskpilot/screen.py`: grim toplevel screenshots, shot ids, and the mapping from shot pixels back to the screen
+- `src/deskpilot/overlay.py`: the agent cursor, drawn by `cua-driver`
+- `src/deskpilot/uinput.py`: the virtual mouse and keyboard behind `--take-pointer` and `--take-focus`
+- `src/deskpilot/keys.py`: key names, chords and US-layout text to Linux key codes
+
+## Rules
+
+- The user's pointer and focus are theirs. Only `--take-pointer`, `--take-focus` and `--show` may move them; every
+  other action goes through the plugin, which must restore both and replay input the user made meanwhile. A window
+  that is not on screen is an error, never a reason to focus it.
+- A point is resolved against a recorded shot. A shot is of one window at one size; any other use is refused.
+- A plugin build loads only into the Hyprland it was built against. Builds are named after the Hyprland commit and
+  the plugin source hash, so a changed source or an upgrade rebuilds rather than reusing a stale build.
+- Each dispatcher tries Hyprland 0.57's Lua form first and falls back to the string form. Keep both working.
+- A window name that matches several windows is an error listing them, and a point outside the window or under
+  another window is refused. Never guess a target.
+- The agent cursor is feedback, never input: any overlay failure turns it off and the action goes ahead.
+- Text is typed on a US layout. A character it cannot type is an error, never skipped.
+- Tests never touch the real compositor, `/dev/uinput`, `grim` or `cua-driver`. Pass fakes into `Desk` and
+  `Hyprland`, as `tests/test_core.py` does.
+- Every user-visible change gets a line under `## [Unreleased]` in `CHANGELOG.md`, and a command or flag change
+  updates `README.md` and `skills/deskpilot/SKILL.md` too.

deskpilot-0.2.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+What changed in each release, in the terms someone using deskpilot would notice. Dates are UTC.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each version's entry is also its GitHub release notes.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-10
+
+- **Install from PyPI.** Each release is published to PyPI, so `uv tool install deskpilot` installs it.
+- **Windows off screen are refused, not focused.** `shot`, `click`, `move` and `scroll` on a window on a hidden
+  workspace or scrolled off its monitor used to focus it, switching your workspace. They now refuse it, and
+  `--show` brings it into view on request. `windows` reports `visible` for each window.
+- **Screenshots of the window itself.** `shot` captures the window by its toplevel, so a window on top no longer
+  shows in the image, and reads its scale from the image, so scaled outputs map clicks correctly.
+- **Shot ids.** Each `shot` has an id; `--shot ID` (or `shot` over MCP) ties a click to that image, and a window
+  resized since is refused instead of clicked in the wrong place. The MCP `shot` tool returns the id with the image.
+- **MCP errors say why.** A refused or failed action over MCP returned only `Error executing tool <name>`; it now
+  returns the reason, such as the window covering the point or the names an ambiguous window matched.
+- **The plugin loads itself.** The first action after Hyprland restarts or upgrades builds and loads the plugin.
+- **Clicks keep your keyboard focus.** A click or scroll no longer focuses or raises the target window while it runs,
+  so keys you type meanwhile stay in your own window. An XWayland app that asks to be activated when clicked is not
+  given focus while deskpilot acts on it.
+- **Agents can act at the same time.** Clicks, scrolls and keys from several callers queue and run in turn instead of
+  failing with `busy`. Up to 32 wait at once; past that an action is refused with a clear error.
+- **Typed text arrives whole.** `deskpilot type` and the MCP `type_text` send the text as one action, so another
+  agent's keys never land in the middle of it, and long text works. `--delay` now sets how long each key is held as
+  well as the gap before the next.
+- **Typing leaves your window alone.** Keys go only to the target app, so the window you are using no longer sees
+  its keyboard focus leave and return, and its pointer no longer flickers while an agent types.
+- **Scrolling ignores your compositor settings.** A scroll reaches the app as plain wheel notches, without your
+  Hyprland mouse binds or scroll factors acting on it.
+- **Clicks check what is on top before every press.** Each press and wheel notch asks Hyprland what is at the point,
+  so a window, bar or popup that appears mid-click is refused instead of clicked.
+
+## [0.1.0] - 2026-11-09
+
+- **Clicks that leave your pointer alone.** `deskpilot click`, `scroll` and keys sent with `--window` run inside
+  Hyprland through the deskpilot plugin: your pointer and keyboard focus go back where they were, and any mouse
+  motion you made meanwhile is applied. Native Wayland, XWayland and Wine windows all receive a real click.
+- **Screenshot coordinates.** `deskpilot shot` saves a window's screenshot and remembers its scale, so `click`,
+  `move` and `scroll` take a point straight from the image. A point outside the window, or under another window, is
+  refused.
+- **No guessed windows.** A window is named by address, class, or part of its class or title, and a name that
+  matches several windows is an error listing them.
+- **Typing.** `deskpilot type` and `deskpilot key` type US-layout text and chords. `--delay` spaces keys for games,
+  which read input once per frame.
+- **Taking over when an app needs it.** `--take-pointer` and `--take-focus` move your own pointer or focus and press
+  through a virtual input device, for a hover the app must see or an app that ignores keys while unfocused.
+- **An agent cursor.** With `cua-driver` installed, an overlay arrow glides to each point deskpilot acts on.
+- **Plugin management.** `deskpilot plugin load` builds the plugin for the running Hyprland and loads it; run it
+  again after each Hyprland upgrade.
+- **MCP server.** `deskpilot mcp` serves the same actions over stdio, keeping one input device and one agent cursor
+  open for the session.
+- **Works with Hyprland 0.57 and older.** Each dispatcher tries the Lua form first and falls back to the string
+  form, and a shell with a stale `HYPRLAND_INSTANCE_SIGNATURE` reaches the one live Hyprland.

deskpilot-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Bug reports and pull requests are welcome. [AGENTS.md](AGENTS.md) has the layout and the rules a change must keep.
+
+## Before you start
+
+- **Bugs:** open an issue with the command you ran, the target window from `deskpilot --json windows`, your
+  Hyprland version and `deskpilot plugin status`. A click or key that reached the wrong window is the most serious
+  kind of bug, so say so in the title.
+- **New actions and larger changes:** open an issue first, so we can agree how the user's pointer and focus are
+  kept.
+- **Security issues:** report them privately, as [SECURITY.md](SECURITY.md) describes.
+
+## Making a change
+
+Run the checks in [AGENTS.md](AGENTS.md#checks). A change needs:
+
+- passing checks
+- a test for each new refusal, including the case that must refuse
+- a line under Unreleased in `CHANGELOG.md` if a user would notice it
+- matching updates to `README.md` and `skills/deskpilot/SKILL.md` if a command or flag changed
+
+Tests must never touch the real desktop. Pass fakes into `Desk` and `Hyprland` as `tests/test_core.py` does. A change
+to the plugin also needs a manual check on a running Hyprland, with the clients you tried named in the PR.
+
+Keep PRs to one idea and use [Conventional Commits](https://www.conventionalcommits.org/) for titles.
+
+## Releasing
+
+Bump `version` in `pyproject.toml` and `.claude-plugin/plugin.json`, run `uv lock`, move the Unreleased lines under
+a new `## [X.Y.Z] - YYYY-MM-DD` heading, and merge. Then tag the merged commit `vX.Y.Z` and push the tag. The release
+workflow checks the tag is on main and matches both versions, and publishes a GitHub release whose notes are that
+version's changelog entry.

deskpilot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cillian Berragan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deskpilot-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: deskpilot
+Version: 0.2.0
+Summary: Desktop control for agents on Hyprland: window-relative clicks that leave the user's pointer alone, and typing
+Project-URL: Homepage, https://github.com/cjber/deskpilot
+Project-URL: Repository, https://github.com/cjber/deskpilot
+Project-URL: Issues, https://github.com/cjber/deskpilot/issues
+Project-URL: Changelog, https://github.com/cjber/deskpilot/blob/main/CHANGELOG.md
+Author-email: Cillian Berragan <cjberragan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: evdev>=1.7
+Requires-Dist: mcp>=2.3
+Requires-Dist: pillow>=10
+Description-Content-Type: text/markdown
+
+# deskpilot
+
+Desktop control for agents on Hyprland. An agent takes a screenshot of a window, picks a point in it, and clicks
+or types there, in any app: native Wayland, XWayland and Wine programs such as the Battle.net launcher and games.
+
+The user keeps their own pointer and keyboard focus. Clicks, scrolls and keys run inside the compositor through
+the deskpilot Hyprland plugin: in one step it holds the user's mouse input, delivers the event to the target window
+through the user's own seat, then puts the pointer back where it was, applying any mouse motion the user made
+meanwhile. Only pointer focus moves, so keyboard focus stays on the user's window and the target is not raised, even
+with `focus_on_activate` set. Wayland, XWayland and Wine clients all receive the press as a real click. The plugin refuses
+a click when another window covers the point.
+
+An agent cursor shows where deskpilot acts: [cua-driver](https://github.com/trycua/cua)'s overlay arrow glides to
+each point, drawn above every window and separate from the user's pointer. Without `cua-driver` on `PATH`, or with
+`DESKPILOT_CURSOR=off`, actions run without it.
+
+Keys sent to a window (`--window`) go to that window only, with each stroke complete before focus returns, and
+the user's modifiers never leak into them. X11 apps take keys only from the window with X input focus, so an
+XWayland target gets X focus for each stroke and sees a focus-in and focus-out around it; Hyprland's own focus
+does not move.
+
+`--take-pointer` and `--take-focus` use a virtual input device made with `/dev/uinput` instead, which the
+compositor treats as real hardware. Tools that synthesize input another way, such as `xdotool` (XTest) or `wtype`
+(the virtual keyboard protocol), are ignored by some clients: Battle.net drops `xdotool` clicks, and a game drops
+`wtype` keys.
+
+## Requirements
+
+- Hyprland, with `hyprctl` on `PATH`. Version 0.57's Lua dispatchers and the older string ones both work.
+- The plugin build tools: a C++26 compiler, `make`, Hyprland's headers (`pkg-config hyprland`, shipped with
+  Arch's `hyprland` package), `libxcb` and `libxkbcommon`.
+- Optional: `cua-driver` for the agent cursor.
+- `grim` for screenshots.
+- For `--take-pointer`, `--take-focus` and keys without `--window`: write access to `/dev/uinput`, usually through
+  the `input` group or a udev ACL. Check with `test -w /dev/uinput`.
+- Python 3.12 or later and `uv`.
+
+## Install
+
+```sh
+uv tool install deskpilot
+```
+
+The agent skill, which teaches an agent the steps below, installs in Claude Code with:
+
+```text
+/plugin install deskpilot --marketplace cjber/deskpilot
+```
+
+## Use
+
+```sh
+deskpilot windows                         # every window: address, class, title, geometry, whether on screen
+deskpilot shot battle.net.exe             # screenshot; prints its id, image path and scale
+deskpilot click battle.net.exe 920 367 --shot ID    # a point in that screenshot
+deskpilot type "/reload" --window wow.exe --delay 0.12
+deskpilot key ctrl+a --window kitty
+deskpilot wait-for wow.exe --timeout 120
+```
+
+A window is named by its address, its class, or a substring of its class or title. A name that matches more
+than one window is an error listing them, so a click never lands on a guessed window.
+
+`shot` captures the window itself, so a window on top does not show in it, and saves it under an id. `move`,
+`click` and `scroll` take pixels in the shot named by `--shot`, or the window's latest one, whatever scale it was
+taken at. A window resized since that shot is refused, as is a point outside the window. Pass `--scale 1` to give
+window pixels instead.
+
+A window on a hidden workspace or scrolled off its monitor is reported as `"visible": false`, and `shot`, `move`,
+`click` and `scroll` refuse it rather than move the user's view. `--show` focuses it to bring it on screen first.
+
+The first action that needs the plugin builds and loads it for the running Hyprland, so it comes back by itself
+after Hyprland restarts or upgrades. `deskpilot plugin load` does the same ahead of time.
+
+`move` only shows the agent cursor. Pass `--take-pointer` to `move`, `click` or `scroll` to move the user's own
+pointer there and press through the input device instead, for a hover the app must see.
+
+A shell started before Hyprland restarted keeps a stale `HYPRLAND_INSTANCE_SIGNATURE`. deskpilot then talks to
+the one instance whose socket answers, and with several live instances it stops and names them.
+
+`key` and `type` without `--window` press keys into whatever has focus. `--take-focus` focuses the window and
+leaves it focused, for an app that ignores keys while unfocused.
+
+Games read keys once per frame, so type into them with `--delay 0.1` or more: each key is held that long, with the
+same gap before the next.
+
+Clicks, scrolls and keys from several agents at once run one after another in the order they arrive, so one `type`
+is never interleaved with another's keys. Up to 32 wait behind the running one; past that an action is refused.
+
+## MCP
+
+`deskpilot mcp` serves the same actions over stdio: `windows`, `focus`, `shot` (returns the image and its shot
+id), `click`, `move`, `scroll`, `key`, `type_text` and `wait_for`. `click`, `move` and `scroll` take `shot`, `show`
+and `take_pointer`; `key` and `type_text` take `take_focus`. It keeps one input
+device and one agent cursor open for the session.
+
+```sh
+claude mcp add deskpilot -- deskpilot mcp
+```
+
+## Limits
+
+- Text is typed on a US layout; a character that layout cannot type is an error rather than skipped.
+- Hyprland plugins load only into the exact Hyprland they were built against, so `deskpilot plugin load` builds
+  one per Hyprland commit and plugin source under `~/.local/share/deskpilot`, and replaces a loaded build of
+  other source.
+- Each CLI action that uses the input device opens a new one and waits about a second for libinput to add it. The MCP server
+  avoids that wait.
+- Hyprland only, Linux only.
+
+## Development
+
+[AGENTS.md](AGENTS.md) has the checks, the layout and the rules a change must keep, and
+[CONTRIBUTING.md](CONTRIBUTING.md) how to report a bug or send a change.