hypruse 0.1.0__tar.gz

hypruse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q

hypruse-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+# Publishes to PyPI on a version tag via Trusted Publishing (OIDC) — no
+# API token stored anywhere. One-time PyPI setup is documented in
+# RELEASING.md (add a pending publisher for this repo + workflow).
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >
+          gh release create "${GITHUB_REF_NAME}"
+          --title "${GITHUB_REF_NAME}"
+          --notes "See [CHANGELOG.md](CHANGELOG.md)."
+          dist/*

hypruse-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage

hypruse-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Architecture
+
+Ten-minute orientation for contributors.
+
+## Module map
+
+```
+src/hypruse/
+  server.py      MCP wiring: 6 tools, docstrings = the agent-facing API
+  hyprctl.py     all Hyprland IPC (queries + dispatchers), state trimming
+  wire.py        raw Wayland client for zwlr_virtual_pointer_v1
+  input.py       pointer orchestration (movecursor + wire) and wtype keyboard
+  screenshot.py  grim capture: monitor / window / region + coord metadata
+  session.py     discovers HYPRLAND_INSTANCE_SIGNATURE / WAYLAND_DISPLAY
+                 from runtime-dir sockets when the host stripped the env
+  safety.py      activity beacon + kill-switch semantics
+```
+
+Rule of thumb: `server.py` validates and narrates; everything real happens
+in the leaf modules, which stay importable and testable without MCP.
+
+## The coordinate contract
+
+One space rules everything: **Hyprland global logical coordinates** (what
+`hyprctl cursorpos`, client `at`, and `dispatch movecursor` speak).
+
+- `desktop` reports window geometry in it.
+- `pointer` accepts it.
+- `screenshot` captures *pixels* and returns `geometry` + `scale` per
+  capture so callers map back: `global = origin + pixel / scale`.
+
+If you touch anything coordinate-adjacent, preserve this contract; it is
+what keeps multi-monitor and fractional scaling tractable.
+
+## Why input works the way it does
+
+- **Position** via `hyprctl dispatch movecursor x y` — authoritative,
+  global, no per-monitor extent math, immune to
+  [hyprwm/Hyprland#6749](https://github.com/hyprwm/Hyprland/issues/6749).
+- **Buttons/axis** via a virtual pointer created over the raw wire
+  (`wire.py` is ~250 lines: registry scan, bind, button/axis/frame, sync
+  barrier, wl_display.error surfacing). No daemon, no uinput, no root.
+- **Keyboard** via `wtype`: it uploads its own XKB keymap through
+  `zwp_virtual_keyboard_v1`, which is why unicode and non-US layouts work.
+  We shell out instead of reimplementing keymap upload — that wheel is
+  round already.
+
+A press and its release always happen inside one tool call, which is what
+makes `pkill -f hypruse` a safe panic action at any moment.
+
+## Sequence of a typical agent step
+
+1. `desktop` → find `firefox` at `0x…`, workspace 3, geometry.
+2. `hypr focus_window 0x…` (IPC, ~ms) — no vision spent.
+3. `screenshot window=0x…` → crop + `geometry`/`scale`.
+4. `pointer click x y` — computed from image pixel via the contract.
+5. `keyboard type "…"`.
+6. `desktop` again to verify the world changed as expected.
+
+## Testing tiers
+
+1. **Unit** (CI): pure functions — wire encoders/parsers, combo parsing,
+   region parsing, state trimming against fixtures.
+2. **Live seat-safe** (`pytest -m e2e`): real session, zero input events —
+   including a virtual-pointer create/destroy handshake.
+3. **Supervised** (`scripts/e2e_input.py`): the only tier that clicks and
+   types; countdown, self-verifying via kitty remote control, restores
+   focus. Never wire this into anything automatic.

hypruse-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-16
+
+Initial release.
+
+### Added
+- MCP stdio server with six tools: `desktop`, `screenshot`, `pointer`,
+  `keyboard`, `hypr`, `launch`, plus cross-tool guidance in the server
+  `instructions` and terse per-tool schemas for eager client loading.
+- Semantic desktop snapshot over hyprctl IPC (token-lean, fixture-tested).
+- Screenshots via grim: focused monitor, exact window crop, region zoom,
+  with true output dimensions and scale for exact pixel→global mapping.
+  Default returns a saved PNG path (works with hosts that mangle inline
+  image blocks); `HYPRUSE_SCREENSHOT_MODE=image` returns wire-level image
+  content auto-fit to a transport byte budget and long-edge cap
+  (`HYPRUSE_MAX_IMAGE_BYTES`, `HYPRUSE_MAX_IMAGE_EDGE`) by degrading format
+  before resolution, so the API never silently downscales under the model.
+  Coarse-to-fine clicking guidance to counter pixel-estimation error.
+- Pointer input over a raw `zwlr_virtual_pointer_v1` wire client — no
+  ydotool, no uinput, no daemon; positioning via `hyprctl movecursor`.
+- Keyboard input via wtype (XKB keymap upload; unicode/layout-correct),
+  with combo parsing (`ctrl+shift+t`, `super+enter`, bare-mod taps).
+- Workspace/window dispatchers and app launch with new-window detection,
+  including single-instance apps (browsers) whose window is relocated to
+  the requested workspace.
+- Session discovery: finds `HYPRLAND_INSTANCE_SIGNATURE` / `WAYLAND_DISPLAY`
+  from runtime sockets when the host launches the server with a stripped
+  environment (dbus/systemd-activated desktop apps).
+- Activity beacon + Waybar kill-switch indicator module.
+- Unit suite, seat-safe live e2e, MCP stdio round-trip tests, supervised
+  input verification script, CI.

hypruse-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Contributions are welcome — especially the roadmap items marked
+`help wanted` (sway/niri support is the big one: `wire.py` already speaks
+the wlr protocols; what's missing is an IPC layer equivalent to
+`hyprctl.py` for those compositors).
+
+## Setup
+
+```sh
+git clone https://github.com/IlyasKhallouki/hypruse
+cd hypruse
+uv sync --group dev
+```
+
+## Before you push
+
+```sh
+uv run ruff check .
+uv run pytest          # must stay green without a compositor
+```
+
+If your change touches live behaviour, also run `uv run pytest -m e2e
+--override-ini addopts=` inside a Hyprland session, and
+`scripts/e2e_input.py` if it touches input (supervised — it takes the
+seat for ~10 seconds).
+
+## Ground rules
+
+- Conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `ci:`, `chore:`).
+- Unit tests accompany features; anything pure gets tested pure.
+- Never make input tests automatic. The supervised script stays supervised.
+- Keep the coordinate contract (see ARCHITECTURE.md) intact.
+- No new runtime dependencies without an issue discussion first — the
+  zero-daemon, near-zero-dep footprint is a feature.

hypruse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilyas Khallouki
+
+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.

hypruse-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: hypruse
+Version: 0.1.0
+Summary: Computer use for Hyprland — an MCP server that gives AI agents native hands on your Wayland desktop
+Project-URL: Homepage, https://github.com/IlyasKhallouki/hypruse
+Project-URL: Issues, https://github.com/IlyasKhallouki/hypruse/issues
+Author-email: Ilyas Khallouki <khalloukielias@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,automation,claude,computer-use,hyprland,mcp,wayland
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Desktop Environment :: Window Managers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Description-Content-Type: text/markdown
+
+# hypruse
+
+**Computer use for [Hyprland](https://hypr.land).** An [MCP](https://modelcontextprotocol.io) server that gives AI agents native hands on your Wayland desktop — workspaces, windows, mouse, keyboard, screenshots.
+
+No ydotool daemon. No root. No portals. No X11.
+
+<!-- demo: assets/demo.gif goes here before launch -->
+
+## Why
+
+Computer use exists on macOS and Windows. On Linux there is effectively nothing: the Claude Desktop Linux beta explicitly ships **without** screen control, Anthropic's reference implementation is an X11 container, and the existing Wayland attempts lean on setuid uinput hacks or GNOME-only portals.
+
+Meanwhile Hyprland already exposes everything an agent needs, better than any accessibility bridge: a complete IPC surface for state and window management, and first-class Wayland protocols for input. hypruse just wires them to MCP:
+
+- **Semantic first.** `desktop` returns the real window/workspace tree — addresses, classes, titles, geometry — in one call. The agent switches workspaces and focuses windows the way you do (instantly, over IPC), not by squinting at pixels.
+- **Vision when it matters.** Screenshots of a monitor, an exact window crop, or a zoomed region, with the geometry/scale metadata to map any pixel back to a clickable coordinate.
+- **Native input.** Clicks and scrolls are spoken directly over the Wayland wire (`zwlr_virtual_pointer_v1`); typing goes through `wtype`'s virtual keyboard with a proper XKB keymap — unicode-safe on any layout.
+
+## How it works
+
+```
+agent (Claude Code, or any MCP client)
+   │ stdio
+   ▼
+hypruse
+   ├── hyprctl -j ········▶ desktop state: monitors, workspaces, windows
+   ├── hyprctl dispatch ··▶ focus / move / close / launch / movecursor
+   ├── grim ··············▶ screenshots: monitor, window crop, region
+   ├── wtype ·············▶ keyboard (zwp_virtual_keyboard_v1, real XKB keymap)
+   └── raw Wayland wire ··▶ click & scroll (zwlr_virtual_pointer_v1)
+```
+
+Design choices, defended:
+
+- **No ydotool / uinput.** That path needs a daemon, udev rules or root, and types US scancodes that break on other layouts. hypruse is just another Wayland client of your compositor — same standing as `wlrctl`.
+- **No portals.** `xdg-desktop-portal-hyprland` does not implement the RemoteDesktop portal (InputCapture is capture, not injection), so anything built on libei/portals silently degrades on Hyprland. hypruse doesn't try.
+- **Cursor positioning via `hyprctl dispatch movecursor`** (global logical coordinates, exact on any monitor layout), with only button/axis events on the virtual pointer — sidestepping the known multi-monitor bugs of absolute virtual-pointer motion ([hyprwm/Hyprland#6749](https://github.com/hyprwm/Hyprland/issues/6749)).
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `desktop` | One-call semantic snapshot: monitors, workspaces, windows (address/class/title/geometry), active window, cursor |
+| `screenshot` | Focused monitor, exact window crop by address, or `x,y,WxH` region — returns image + coordinate-mapping metadata |
+| `pointer` | move / click / drag / scroll in global coordinates |
+| `keyboard` | Type literal text (unicode-safe) or press combos: `ctrl+shift+t`, `super+enter`, `F5` |
+| `hypr` | Switch workspace, focus/move/close windows, fullscreen, floating — pure IPC, milliseconds |
+| `launch` | Start an app (optionally silent on another workspace), wait for its window, return its address — detects single-instance apps (browsers) whose window ignores exec rules, and moves it to the requested workspace |
+
+## Install
+
+Requirements: Hyprland, `grim`, `wtype` (most Hyprland setups already have both), and [uv](https://docs.astral.sh/uv/).
+
+Claude Code:
+
+```sh
+claude mcp add -s user hypruse -- uvx hypruse
+```
+
+From a source checkout:
+
+```sh
+claude mcp add -s user hypruse -- uv run --directory /path/to/hypruse hypruse
+```
+
+Any other MCP client: run `uvx hypruse` as a stdio server.
+
+### Claude Desktop (Linux beta)
+
+The Linux beta ships **without** Anthropic's first-party computer use — but stdio MCP servers work in chat, which makes hypruse the workaround. In `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hypruse": {
+      "command": "uvx",
+      "args": ["hypruse"],
+      "env": { "HYPRUSE_SCREENSHOT_MODE": "image" }
+    }
+  }
+}
+```
+
+Two Desktop-specific notes: use `image` mode (Desktop renders inline MCP images and has no file-read tool), and the app must run natively inside your Hyprland session so the server inherits `WAYLAND_DISPLAY`/`HYPRLAND_INSTANCE_SIGNATURE` — from a VM or container it cannot reach your compositor. If your Desktop install bypasses tool-approval prompts, treat the [Waybar indicator + panic keybind](waybar/) as mandatory, not optional.
+
+## Security model
+
+Read this section before installing. **hypruse hands an agent your mouse, your keyboard, your screen contents, and an app launcher.** The layers that keep that sane:
+
+1. **Approval** — MCP clients gate tool calls. In Claude Code, allowlist the read-only tools (`desktop`, `screenshot`) and leave `pointer`/`keyboard`/`hypr`/`launch` on ask-first until you trust a workflow.
+2. **Visibility** — the server maintains an activity beacon (`$XDG_RUNTIME_DIR/hypruse/state.json`); the shipped [Waybar module](waybar/) is invisible when idle and shows 󰚩 while an agent has hands on your desktop.
+3. **Interruption** — click the indicator, or bind a panic key: `bind = SUPER SHIFT, BackSpace, exec, pkill -f hypruse`. Killing it mid-action is safe: button press/release pairs never span tool calls, so it cannot die holding a button.
+4. **The seat is shared.** There is one cursor and one keyboard focus, and Hyprland's focus-follows-mouse means a cursor move alone can retarget keystrokes. Don't type while an agent is driving — watch the indicator.
+5. **Scope** — stdio only (no network listener), no clipboard access, nothing persisted except the beacon. A screenshot sees everything visible: treat an agent session like screen sharing.
+
+## Performance
+
+Measured on a live session (Hyprland 0.55, 1080p, 20 windows): `desktop`
+~30 ms, workspace/window dispatch ~10–20 ms, screenshots ~0.5 s. If tool
+calls *feel* slow, it is almost certainly the MCP **approval prompt** in
+front of each call, not the server — allowlist the tools you trust and the
+latency disappears. Claude Code (`.claude/settings.json`):
+
+```jsonc
+{
+  "permissions": {
+    "allow": [
+      "mcp__hypruse__desktop",
+      "mcp__hypruse__screenshot",
+      "mcp__hypruse__hypr"
+      // add pointer/keyboard/launch once you trust your workflows
+    ]
+  }
+}
+```
+
+## Coordinates
+
+Everything speaks Hyprland's global logical coordinates — the space `hyprctl cursorpos` and window `at` use. Screenshots are pixel-space; each capture returns `geometry` and `scale` so `global = origin + pixel / scale`. On scale 1.0 monitors (most setups) image pixels *are* global coordinates.
+
+In image mode, captures automatically fit the host's result-size limit (Claude Desktop caps tool results at 1 MB): format degrades before resolution — native PNG, then full-res JPEG, then stepped downscale — because full-res JPEG reads UI text better than half-res PNG. The applied scale is folded into the returned metadata, so coordinate mapping stays exact; tune with `HYPRUSE_MAX_IMAGE_BYTES`, or pass `scale` for a deliberate zoom-out.
+
+By default the screenshot tool writes a PNG under `$XDG_RUNTIME_DIR/hypruse/` and returns its path — MCP hosts with a file reader (Claude Code's `Read`) render it natively. This default exists because some hosts (Claude Code ≤ 2.1.x among them) serialize inline MCP image blocks to base64 *text* the model can't see; we verified this empirically rather than trusting the spec. `HYPRUSE_SCREENSHOT_MODE=image` switches to inline image content blocks for hosts that render them correctly.
+
+## Development
+
+```sh
+uv sync --group dev
+uv run pytest            # unit tests, no compositor needed
+uv run pytest -m e2e --override-ini addopts=   # live seat-safe checks
+uv run python scripts/e2e_input.py             # supervised: takes the seat ~10s
+```
+
+The input e2e is deliberately manual — it borrows your cursor and keyboard, counts down, proves click/scroll/type delivery by reading the target terminal's screen back over kitty remote control, and restores your focus.
+
+## Roadmap
+
+**Now — distribution**
+- [ ] PyPI (`uvx hypruse`) and AUR (`hypruse`, `hypruse-git`)
+- [ ] Demo GIF, then `awesome-mcp-servers` / `awesome-hyprland` listings
+
+**Next — trust & accuracy**
+- [ ] `hypruse doctor` — first-run diagnostics (deps, session reachability, virtual-pointer handshake)
+- [ ] Click-by-text via OCR (Tesseract) — click labels, not estimated pixels; works on any app
+- [ ] Read-only mode — disable input tools for a safe first run
+- [ ] Headless-Hyprland CI — real end-to-end tests in GitHub Actions
+
+**Then — breadth & depth**
+- [ ] sway / niri support — the wire client already speaks the wlr protocols; needs an IPC layer alongside `hyprctl.py` (PRs very welcome, `help wanted`)
+- [ ] AT-SPI element tree — click by accessible name, read GTK/Qt UIs without vision
+- [ ] Clipboard (`wl-clipboard`), settle / wait-for-stable, discrete-axis scroll
+- [ ] Multi-monitor and fractional-scaling hardening
+
+## Alternatives, honestly
+
+| project | approach | where it falls short on Hyprland |
+|---|---|---|
+| computer-use-linux | AT-SPI + portals, ydotool fallback | GNOME-first; RemoteDesktop portal is dead on Hyprland, screenshots portal-first |
+| hyprmcp | hyprctl wrapper | no screenshots, no input |
+| wayland-mcp (×2) | setuid evemu + bundled VLM | archived / stale; evemu needs elevated setup |
+| Anthropic computer-use-demo | X11 + xdotool in Docker | a sandboxed demo, not your desktop |
+
+## License
+
+[MIT](LICENSE)

hypruse-0.1.0/README.md

@@ -0,0 +1,165 @@
+# hypruse
+
+**Computer use for [Hyprland](https://hypr.land).** An [MCP](https://modelcontextprotocol.io) server that gives AI agents native hands on your Wayland desktop — workspaces, windows, mouse, keyboard, screenshots.
+
+No ydotool daemon. No root. No portals. No X11.
+
+<!-- demo: assets/demo.gif goes here before launch -->
+
+## Why
+
+Computer use exists on macOS and Windows. On Linux there is effectively nothing: the Claude Desktop Linux beta explicitly ships **without** screen control, Anthropic's reference implementation is an X11 container, and the existing Wayland attempts lean on setuid uinput hacks or GNOME-only portals.
+
+Meanwhile Hyprland already exposes everything an agent needs, better than any accessibility bridge: a complete IPC surface for state and window management, and first-class Wayland protocols for input. hypruse just wires them to MCP:
+
+- **Semantic first.** `desktop` returns the real window/workspace tree — addresses, classes, titles, geometry — in one call. The agent switches workspaces and focuses windows the way you do (instantly, over IPC), not by squinting at pixels.
+- **Vision when it matters.** Screenshots of a monitor, an exact window crop, or a zoomed region, with the geometry/scale metadata to map any pixel back to a clickable coordinate.
+- **Native input.** Clicks and scrolls are spoken directly over the Wayland wire (`zwlr_virtual_pointer_v1`); typing goes through `wtype`'s virtual keyboard with a proper XKB keymap — unicode-safe on any layout.
+
+## How it works
+
+```
+agent (Claude Code, or any MCP client)
+   │ stdio
+   ▼
+hypruse
+   ├── hyprctl -j ········▶ desktop state: monitors, workspaces, windows
+   ├── hyprctl dispatch ··▶ focus / move / close / launch / movecursor
+   ├── grim ··············▶ screenshots: monitor, window crop, region
+   ├── wtype ·············▶ keyboard (zwp_virtual_keyboard_v1, real XKB keymap)
+   └── raw Wayland wire ··▶ click & scroll (zwlr_virtual_pointer_v1)
+```
+
+Design choices, defended:
+
+- **No ydotool / uinput.** That path needs a daemon, udev rules or root, and types US scancodes that break on other layouts. hypruse is just another Wayland client of your compositor — same standing as `wlrctl`.
+- **No portals.** `xdg-desktop-portal-hyprland` does not implement the RemoteDesktop portal (InputCapture is capture, not injection), so anything built on libei/portals silently degrades on Hyprland. hypruse doesn't try.
+- **Cursor positioning via `hyprctl dispatch movecursor`** (global logical coordinates, exact on any monitor layout), with only button/axis events on the virtual pointer — sidestepping the known multi-monitor bugs of absolute virtual-pointer motion ([hyprwm/Hyprland#6749](https://github.com/hyprwm/Hyprland/issues/6749)).
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `desktop` | One-call semantic snapshot: monitors, workspaces, windows (address/class/title/geometry), active window, cursor |
+| `screenshot` | Focused monitor, exact window crop by address, or `x,y,WxH` region — returns image + coordinate-mapping metadata |
+| `pointer` | move / click / drag / scroll in global coordinates |
+| `keyboard` | Type literal text (unicode-safe) or press combos: `ctrl+shift+t`, `super+enter`, `F5` |
+| `hypr` | Switch workspace, focus/move/close windows, fullscreen, floating — pure IPC, milliseconds |
+| `launch` | Start an app (optionally silent on another workspace), wait for its window, return its address — detects single-instance apps (browsers) whose window ignores exec rules, and moves it to the requested workspace |
+
+## Install
+
+Requirements: Hyprland, `grim`, `wtype` (most Hyprland setups already have both), and [uv](https://docs.astral.sh/uv/).
+
+Claude Code:
+
+```sh
+claude mcp add -s user hypruse -- uvx hypruse
+```
+
+From a source checkout:
+
+```sh
+claude mcp add -s user hypruse -- uv run --directory /path/to/hypruse hypruse
+```
+
+Any other MCP client: run `uvx hypruse` as a stdio server.
+
+### Claude Desktop (Linux beta)
+
+The Linux beta ships **without** Anthropic's first-party computer use — but stdio MCP servers work in chat, which makes hypruse the workaround. In `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hypruse": {
+      "command": "uvx",
+      "args": ["hypruse"],
+      "env": { "HYPRUSE_SCREENSHOT_MODE": "image" }
+    }
+  }
+}
+```
+
+Two Desktop-specific notes: use `image` mode (Desktop renders inline MCP images and has no file-read tool), and the app must run natively inside your Hyprland session so the server inherits `WAYLAND_DISPLAY`/`HYPRLAND_INSTANCE_SIGNATURE` — from a VM or container it cannot reach your compositor. If your Desktop install bypasses tool-approval prompts, treat the [Waybar indicator + panic keybind](waybar/) as mandatory, not optional.
+
+## Security model
+
+Read this section before installing. **hypruse hands an agent your mouse, your keyboard, your screen contents, and an app launcher.** The layers that keep that sane:
+
+1. **Approval** — MCP clients gate tool calls. In Claude Code, allowlist the read-only tools (`desktop`, `screenshot`) and leave `pointer`/`keyboard`/`hypr`/`launch` on ask-first until you trust a workflow.
+2. **Visibility** — the server maintains an activity beacon (`$XDG_RUNTIME_DIR/hypruse/state.json`); the shipped [Waybar module](waybar/) is invisible when idle and shows 󰚩 while an agent has hands on your desktop.
+3. **Interruption** — click the indicator, or bind a panic key: `bind = SUPER SHIFT, BackSpace, exec, pkill -f hypruse`. Killing it mid-action is safe: button press/release pairs never span tool calls, so it cannot die holding a button.
+4. **The seat is shared.** There is one cursor and one keyboard focus, and Hyprland's focus-follows-mouse means a cursor move alone can retarget keystrokes. Don't type while an agent is driving — watch the indicator.
+5. **Scope** — stdio only (no network listener), no clipboard access, nothing persisted except the beacon. A screenshot sees everything visible: treat an agent session like screen sharing.
+
+## Performance
+
+Measured on a live session (Hyprland 0.55, 1080p, 20 windows): `desktop`
+~30 ms, workspace/window dispatch ~10–20 ms, screenshots ~0.5 s. If tool
+calls *feel* slow, it is almost certainly the MCP **approval prompt** in
+front of each call, not the server — allowlist the tools you trust and the
+latency disappears. Claude Code (`.claude/settings.json`):
+
+```jsonc
+{
+  "permissions": {
+    "allow": [
+      "mcp__hypruse__desktop",
+      "mcp__hypruse__screenshot",
+      "mcp__hypruse__hypr"
+      // add pointer/keyboard/launch once you trust your workflows
+    ]
+  }
+}
+```
+
+## Coordinates
+
+Everything speaks Hyprland's global logical coordinates — the space `hyprctl cursorpos` and window `at` use. Screenshots are pixel-space; each capture returns `geometry` and `scale` so `global = origin + pixel / scale`. On scale 1.0 monitors (most setups) image pixels *are* global coordinates.
+
+In image mode, captures automatically fit the host's result-size limit (Claude Desktop caps tool results at 1 MB): format degrades before resolution — native PNG, then full-res JPEG, then stepped downscale — because full-res JPEG reads UI text better than half-res PNG. The applied scale is folded into the returned metadata, so coordinate mapping stays exact; tune with `HYPRUSE_MAX_IMAGE_BYTES`, or pass `scale` for a deliberate zoom-out.
+
+By default the screenshot tool writes a PNG under `$XDG_RUNTIME_DIR/hypruse/` and returns its path — MCP hosts with a file reader (Claude Code's `Read`) render it natively. This default exists because some hosts (Claude Code ≤ 2.1.x among them) serialize inline MCP image blocks to base64 *text* the model can't see; we verified this empirically rather than trusting the spec. `HYPRUSE_SCREENSHOT_MODE=image` switches to inline image content blocks for hosts that render them correctly.
+
+## Development
+
+```sh
+uv sync --group dev
+uv run pytest            # unit tests, no compositor needed
+uv run pytest -m e2e --override-ini addopts=   # live seat-safe checks
+uv run python scripts/e2e_input.py             # supervised: takes the seat ~10s
+```
+
+The input e2e is deliberately manual — it borrows your cursor and keyboard, counts down, proves click/scroll/type delivery by reading the target terminal's screen back over kitty remote control, and restores your focus.
+
+## Roadmap
+
+**Now — distribution**
+- [ ] PyPI (`uvx hypruse`) and AUR (`hypruse`, `hypruse-git`)
+- [ ] Demo GIF, then `awesome-mcp-servers` / `awesome-hyprland` listings
+
+**Next — trust & accuracy**
+- [ ] `hypruse doctor` — first-run diagnostics (deps, session reachability, virtual-pointer handshake)
+- [ ] Click-by-text via OCR (Tesseract) — click labels, not estimated pixels; works on any app
+- [ ] Read-only mode — disable input tools for a safe first run
+- [ ] Headless-Hyprland CI — real end-to-end tests in GitHub Actions
+
+**Then — breadth & depth**
+- [ ] sway / niri support — the wire client already speaks the wlr protocols; needs an IPC layer alongside `hyprctl.py` (PRs very welcome, `help wanted`)
+- [ ] AT-SPI element tree — click by accessible name, read GTK/Qt UIs without vision
+- [ ] Clipboard (`wl-clipboard`), settle / wait-for-stable, discrete-axis scroll
+- [ ] Multi-monitor and fractional-scaling hardening
+
+## Alternatives, honestly
+
+| project | approach | where it falls short on Hyprland |
+|---|---|---|
+| computer-use-linux | AT-SPI + portals, ydotool fallback | GNOME-first; RemoteDesktop portal is dead on Hyprland, screenshots portal-first |
+| hyprmcp | hyprctl wrapper | no screenshots, no input |
+| wayland-mcp (×2) | setuid evemu + bundled VLM | archived / stale; evemu needs elevated setup |
+| Anthropic computer-use-demo | X11 + xdotool in Docker | a sandboxed demo, not your desktop |
+
+## License
+
+[MIT](LICENSE)

hypruse-0.1.0/RELEASING.md

@@ -0,0 +1,53 @@
+# Releasing
+
+The launch and every release after it. Steps marked **[you]** need your
+accounts/credentials; the rest is automated.
+
+## One-time setup
+
+1. **[you] Make the repo public** on GitHub (Settings → General → Danger
+   Zone). The awesome-list PRs and AUR source tarballs depend on this.
+2. **[you] PyPI Trusted Publisher** — on PyPI, add a *pending* publisher so
+   the first `release` workflow run can publish without a token
+   (https://pypi.org/manage/account/publishing/):
+   - Project: `hypruse`
+   - Owner: `IlyasKhallouki`  · Repo: `hypruse`
+   - Workflow: `release.yml`  · Environment: `pypi`
+3. **[you] AUR SSH key** — add your public key at
+   https://aur.archlinux.org/account, if not already done.
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` and move the CHANGELOG `[Unreleased]`
+   entries under the new version.
+2. Tag and push:
+   ```sh
+   git tag -a v0.1.0 -m "v0.1.0"
+   git push origin v0.1.0
+   ```
+   The `release` workflow builds, publishes to PyPI via OIDC, and cuts a
+   GitHub release with the artifacts.
+3. Verify: `uvx hypruse --version`.
+
+## AUR
+
+Stable (`packaging/aur/hypruse/`), after the tag exists:
+
+```sh
+cd packaging/aur/hypruse
+updpkgsums                     # fills the real sha256 for the tag tarball
+makepkg --printsrcinfo > .SRCINFO
+# push to the AUR remote:
+#   git clone ssh://aur@aur.archlinux.org/hypruse.git
+#   copy PKGBUILD + .SRCINFO in, commit, push
+```
+
+`hypruse-git` never needs `updpkgsums` (VCS source); regenerate its
+`.SRCINFO` the same way and push to `ssh://aur@aur.archlinux.org/hypruse-git.git`.
+
+## Listings (after public + first release)
+
+- `awesome-mcp-servers` and `awesome-hyprland` — PR one entry each.
+- The MCP registry.
+
+Test a PKGBUILD locally before pushing: `makepkg -si` in its directory.