winhands 0.3.0__tar.gz

winhands-0.3.0/LICENSE

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

winhands-0.3.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: winhands
+Version: 0.3.0
+Summary: Computer use MCP server for Windows: a11y tree + pixels, code mode, game-grade input
+Author: Rodolfo Obreque
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zredo19/winhands
+Project-URL: Repository, https://github.com/zredo19/winhands
+Project-URL: Issues, https://github.com/zredo19/winhands/issues
+Keywords: mcp,mcp-server,computer-use,windows,uiautomation,claude,claude-code,ai-agents
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.2
+Requires-Dist: uiautomation>=2.0.29
+Requires-Dist: mss
+Requires-Dist: Pillow
+Requires-Dist: numpy
+Requires-Dist: pywin32
+Requires-Dist: opencv-python-headless
+Requires-Dist: winrt-runtime
+Requires-Dist: winrt-Windows.Media.Ocr
+Requires-Dist: winrt-Windows.Graphics.Imaging
+Requires-Dist: winrt-Windows.Storage.Streams
+Requires-Dist: winrt-Windows.Foundation
+Requires-Dist: winrt-Windows.Foundation.Collections
+Requires-Dist: winrt-Windows.Globalization
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# winhands
+
+[![CI](https://github.com/zredo19/winhands/actions/workflows/ci.yml/badge.svg)](https://github.com/zredo19/winhands/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/winhands.svg)](https://pypi.org/project/winhands/)
+
+Computer use for Windows: a small MCP server that lets Claude (or any MCP client)
+operate any desktop app, draw in canvases and drive games.
+
+## Install
+
+Windows 10 2004+ or 11, and Claude Code or any MCP client. In PowerShell:
+
+```powershell
+winget install astral-sh.uv    # once; installs uv, which brings its own Python (check the id with: winget search uv)
+uv tool install winhands
+winhands setup
+```
+
+`winhands setup` registers the MCP server in Claude Code (user scope) and installs the skill into
+`~/.claude/skills/winhands`. If `claude` is not on your PATH it prints the config snippet for other MCP clients instead.
+Then restart Claude Code and ask it: "open Notepad and type hello".
+
+Already have Python 3.11+? `pip install winhands`, then `winhands setup`.
+
+- Update: `uv tool upgrade winhands`
+- Uninstall: `winhands setup --remove`, then `uv tool uninstall winhands`
+- See what `setup` would do without changing anything: `winhands setup --dry-run`
+
+### Alternative: one-line installer
+
+Installs uv if missing, then does the same as the commands above. You can read the
+[script](install.ps1) first; it needs no admin rights.
+
+```powershell
+irm https://raw.githubusercontent.com/zredo19/winhands/main/install.ps1 | iex
+```
+
+To uninstall with it:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zredo19/winhands/main/install.ps1))) -Uninstall
+```
+
+Prefer to do it by hand from the repo? See [Manual install](#manual-install).
+
+![The takeover overlay: edge glow, status banner and agent cursor](docs/img/overlay-states.png)
+*The overlay while Claude controls the PC: edge glow and status banner in four states (acting, thinking, paused, stopped).*
+
+![Agent cursor at 2x in the three palettes](docs/img/overlay-cursor.png)
+*The agent cursor at 2x: idle, moving (trail) and click (ripple), in the Claude, Antigravity and Codex palettes.*
+
+Its design follows the computer-use harness of OpenAI's GPT-6 Astra in the Codex/ChatGPT desktop app,
+and goes past it where that harness is weak (no key holds, no raw mouse, no local control loops):
+
+1. **Accessibility tree first, pixels when needed.** A Codex-style UI Automation tree
+   (`12 button "Save" (focused)`), plus screenshots automatically when a window is canvas-like
+   (games, Paint), OCR, grid rulers, Set-of-Marks and burst montages.
+2. **Code mode.** The model writes Python in a persistent REPL and batches many actions per turn,
+   including local perceive→act loops that run at 10–30 Hz without model round-trips.
+3. **Built-in validation.** Every `run` returns a UI diff (or the full tree of a new dialog).
+4. **Fail closed.** Element ids are bound to the latest snapshot; changed or vanished targets raise
+   `StaleTarget` instead of clicking the wrong thing.
+5. **Takeover UX and safety.** An animated edge glow and status banner (acting, thinking, stopped; with the Ctrl+Alt+Q hint)
+   on the controlled monitor, plus an agent cursor with a motion trail and click ripple where real input lands, all in the
+   client's colour and excluded from screenshots.
+   Ctrl+LeftAlt+Q kill switch, and an automatic abort when the user touches mouse or keyboard.
+   Held inputs are released on abort, risky actions need confirmation, and some windows are denylisted.
+6. **Memory.** Per-app notes and reusable skills (Voyager-style) that persist across sessions.
+
+## Tools (2, ~815 tokens of schema)
+
+| Tool | Modes / helpers |
+|---|---|
+| `observe(target, mode, region, grid, marks, frames, scale)` | `auto` (tree + shot if canvas-like), `tree`, `both`, `diff`, `shot`, `ocr`, `burst`, `windows` |
+| `run(code, timeout, confirm)` | UIA: `click set_value action type key scroll find wait_for focus app windows sh` · Input: `press hold key_down key_up type_keys move move_rel click_at drag wheel release_all` · Vision: `show grab pixel find_color locate save_template ocr find_text click_text click_xy wait_change wait_stable` · Memory: `note notes save_skill skills` |
+
+Input uses `SendInput` with scan codes (DirectInput/raw-input games see real keys) and raw relative
+mouse for game cameras. Window capture uses `PrintWindow(PW_RENDERFULLCONTENT)`, so covered windows
+are read correctly. Apps launched with `app()` survive the MCP session (launched through WMI,
+outside the client's kill-on-close job).
+
+## End-to-end results (real desktop, Windows 10, Spanish UI)
+
+| Test | Result |
+|---|---|
+| Paint: draw a house (shapes by drag, palette swatches found by color, bucket fills), save PNG | 6/6 layout and color checks pass; one `run` of 11 s |
+| Game probe (Chrome, pointer lock): scan codes W/A/S/D/Space/ShiftLeft | all six received as physical key codes |
+| Raw relative mouse under pointer lock | sent (70, 30) → page received DX 70, DY 30 exactly |
+| Buttons / wheel | L, M, R and wheel −3 received |
+| 10 s aim test driven by one local loop (`find_color` → `click_at`) | 88 hits, 6 misses |
+| OCR of known Notepad text | 30/34 words (88%) in 118 ms. Misses: the first glyph touching the edit border, and I/l confusion |
+
+## Benchmark vs Windows-MCP
+
+The same tasks run on the same machine, with each server driven the way an optimal agent would use it.
+There were 3 reps per task. Script: [`bench/bench.py`](bench/bench.py), raw data:
+[`bench/results.json`](bench/results.json).
+
+| Task | Server | Success | Tool calls | Tool time | Tokens returned |
+|---|---|---|---|---|---|
+| Calculator 123×456 | **winhands** | **3/3** | **2** | **8.0 s** | **603** |
+| | Windows-MCP 0.8.5 | 2/3 | 12 | 31.0 s | 6,060 |
+| Notepad: type, Save As, verify file | **winhands** | **3/3** | **3** | **12.9 s** | **2,037** |
+| | Windows-MCP 0.8.5 | 3/3 | 7 | 21.6 s | 8,601 |
+
+The tool schema is sent on every turn: winhands uses about 815 tokens and Windows-MCP about 4,780.
+
+Notes on method:
+- Tokens are estimated: text is chars / 3.5, and images are `ceil(w/28)·ceil(h/28)` per Anthropic's vision docs.
+- Tool time excludes model thinking. Each extra call also costs a model turn in a real agent.
+- Windows-MCP's snapshot lists only interactive elements of the focused window, so reading the
+  calculator result needs a screenshot. Its failed rep missed the calculator in that snapshot.
+- Windows-MCP dropped rapid consecutive clicks. A 1 s pause between its clicks, not counted, mimics agent pacing.
+
+## Manual install
+
+Windows 10 2004+ / 11, Python 3.11+. To run the development version from GitHub with [uv](https://docs.astral.sh/uv/):
+
+```powershell
+uv tool install --compile-bytecode git+https://github.com/zredo19/winhands
+winhands setup
+```
+
+`winhands setup` registers the MCP server and installs the skill (perceive → batch → validate, game guidance, safety
+rules). To do those two steps yourself: `claude mcp add winhands --scope user -- winhands`, and copy
+[`winhands/SKILL.md`](winhands/SKILL.md) to `~/.claude/skills/winhands/SKILL.md`.
+
+Any MCP client works: the server command is just `winhands` (stdio). Set `WINHANDS_OVERLAY=0` to hide the
+overlay, `WINHANDS_LINGER=45` for how long it stays up between actions and `WINHANDS_SHARED=0` for strict mode. From source:
+`pip install -e .` in a venv, then point the client at `python -m winhands`.
+
+## Safety
+
+- **Ctrl + Left Alt + Q** aborts the running action. AltGr+Q still types `@`.
+- Shared mode (default): the user can keep working while a run acts through UIA patterns. Physical input
+  that collides with a run driving the real mouse/keyboard aborts it (`UserInterrupt`); real input waits for
+  the user to go idle first. The tool never fights the user for control. `WINHANDS_SHARED=0` restores strict mode.
+- The low-level keyboard/mouse hooks behind both features exist only while a `run` is acting. Nothing hooks
+  system input while the server idles in a Claude Code session.
+- Keys are only sent to a verified foreground target. All held keys and buttons are released on any abort.
+- `sh()` and clicks on elements named like Send, Buy, Pay, Delete, Install or Allow require `run(..., confirm=True)`.
+- Denylisted windows (password managers, banking) are refused.
+- `run` executes arbitrary Python: the same privilege as Claude Code's shell tool, gated by the client's permission prompts.
+- Online games with anti-cheat: automation may violate their terms and risk a ban. winhands makes
+  no attempt to hide or evade detection.
+
+## Limits
+
+- The harness makes a model faster and cheaper on the desktop. It does not make it smarter.
+- Reflex gameplay needs local loops written by the model, or pausing the game. Model round-trips take seconds.
+- Exclusive-fullscreen games may capture black; use borderless mode. Windows OCR skips isolated single
+  characters and glyphs touching strong borders. Template matching is exact-scale.
+- Elevated (admin) windows ignore input from a non-elevated server (Windows UIPI).
+
+## Tests
+
+```bash
+python -m pytest -q
+```

winhands-0.3.0/README.md

@@ -0,0 +1,159 @@
+# winhands
+
+[![CI](https://github.com/zredo19/winhands/actions/workflows/ci.yml/badge.svg)](https://github.com/zredo19/winhands/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/winhands.svg)](https://pypi.org/project/winhands/)
+
+Computer use for Windows: a small MCP server that lets Claude (or any MCP client)
+operate any desktop app, draw in canvases and drive games.
+
+## Install
+
+Windows 10 2004+ or 11, and Claude Code or any MCP client. In PowerShell:
+
+```powershell
+winget install astral-sh.uv    # once; installs uv, which brings its own Python (check the id with: winget search uv)
+uv tool install winhands
+winhands setup
+```
+
+`winhands setup` registers the MCP server in Claude Code (user scope) and installs the skill into
+`~/.claude/skills/winhands`. If `claude` is not on your PATH it prints the config snippet for other MCP clients instead.
+Then restart Claude Code and ask it: "open Notepad and type hello".
+
+Already have Python 3.11+? `pip install winhands`, then `winhands setup`.
+
+- Update: `uv tool upgrade winhands`
+- Uninstall: `winhands setup --remove`, then `uv tool uninstall winhands`
+- See what `setup` would do without changing anything: `winhands setup --dry-run`
+
+### Alternative: one-line installer
+
+Installs uv if missing, then does the same as the commands above. You can read the
+[script](install.ps1) first; it needs no admin rights.
+
+```powershell
+irm https://raw.githubusercontent.com/zredo19/winhands/main/install.ps1 | iex
+```
+
+To uninstall with it:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zredo19/winhands/main/install.ps1))) -Uninstall
+```
+
+Prefer to do it by hand from the repo? See [Manual install](#manual-install).
+
+![The takeover overlay: edge glow, status banner and agent cursor](docs/img/overlay-states.png)
+*The overlay while Claude controls the PC: edge glow and status banner in four states (acting, thinking, paused, stopped).*
+
+![Agent cursor at 2x in the three palettes](docs/img/overlay-cursor.png)
+*The agent cursor at 2x: idle, moving (trail) and click (ripple), in the Claude, Antigravity and Codex palettes.*
+
+Its design follows the computer-use harness of OpenAI's GPT-6 Astra in the Codex/ChatGPT desktop app,
+and goes past it where that harness is weak (no key holds, no raw mouse, no local control loops):
+
+1. **Accessibility tree first, pixels when needed.** A Codex-style UI Automation tree
+   (`12 button "Save" (focused)`), plus screenshots automatically when a window is canvas-like
+   (games, Paint), OCR, grid rulers, Set-of-Marks and burst montages.
+2. **Code mode.** The model writes Python in a persistent REPL and batches many actions per turn,
+   including local perceive→act loops that run at 10–30 Hz without model round-trips.
+3. **Built-in validation.** Every `run` returns a UI diff (or the full tree of a new dialog).
+4. **Fail closed.** Element ids are bound to the latest snapshot; changed or vanished targets raise
+   `StaleTarget` instead of clicking the wrong thing.
+5. **Takeover UX and safety.** An animated edge glow and status banner (acting, thinking, stopped; with the Ctrl+Alt+Q hint)
+   on the controlled monitor, plus an agent cursor with a motion trail and click ripple where real input lands, all in the
+   client's colour and excluded from screenshots.
+   Ctrl+LeftAlt+Q kill switch, and an automatic abort when the user touches mouse or keyboard.
+   Held inputs are released on abort, risky actions need confirmation, and some windows are denylisted.
+6. **Memory.** Per-app notes and reusable skills (Voyager-style) that persist across sessions.
+
+## Tools (2, ~815 tokens of schema)
+
+| Tool | Modes / helpers |
+|---|---|
+| `observe(target, mode, region, grid, marks, frames, scale)` | `auto` (tree + shot if canvas-like), `tree`, `both`, `diff`, `shot`, `ocr`, `burst`, `windows` |
+| `run(code, timeout, confirm)` | UIA: `click set_value action type key scroll find wait_for focus app windows sh` · Input: `press hold key_down key_up type_keys move move_rel click_at drag wheel release_all` · Vision: `show grab pixel find_color locate save_template ocr find_text click_text click_xy wait_change wait_stable` · Memory: `note notes save_skill skills` |
+
+Input uses `SendInput` with scan codes (DirectInput/raw-input games see real keys) and raw relative
+mouse for game cameras. Window capture uses `PrintWindow(PW_RENDERFULLCONTENT)`, so covered windows
+are read correctly. Apps launched with `app()` survive the MCP session (launched through WMI,
+outside the client's kill-on-close job).
+
+## End-to-end results (real desktop, Windows 10, Spanish UI)
+
+| Test | Result |
+|---|---|
+| Paint: draw a house (shapes by drag, palette swatches found by color, bucket fills), save PNG | 6/6 layout and color checks pass; one `run` of 11 s |
+| Game probe (Chrome, pointer lock): scan codes W/A/S/D/Space/ShiftLeft | all six received as physical key codes |
+| Raw relative mouse under pointer lock | sent (70, 30) → page received DX 70, DY 30 exactly |
+| Buttons / wheel | L, M, R and wheel −3 received |
+| 10 s aim test driven by one local loop (`find_color` → `click_at`) | 88 hits, 6 misses |
+| OCR of known Notepad text | 30/34 words (88%) in 118 ms. Misses: the first glyph touching the edit border, and I/l confusion |
+
+## Benchmark vs Windows-MCP
+
+The same tasks run on the same machine, with each server driven the way an optimal agent would use it.
+There were 3 reps per task. Script: [`bench/bench.py`](bench/bench.py), raw data:
+[`bench/results.json`](bench/results.json).
+
+| Task | Server | Success | Tool calls | Tool time | Tokens returned |
+|---|---|---|---|---|---|
+| Calculator 123×456 | **winhands** | **3/3** | **2** | **8.0 s** | **603** |
+| | Windows-MCP 0.8.5 | 2/3 | 12 | 31.0 s | 6,060 |
+| Notepad: type, Save As, verify file | **winhands** | **3/3** | **3** | **12.9 s** | **2,037** |
+| | Windows-MCP 0.8.5 | 3/3 | 7 | 21.6 s | 8,601 |
+
+The tool schema is sent on every turn: winhands uses about 815 tokens and Windows-MCP about 4,780.
+
+Notes on method:
+- Tokens are estimated: text is chars / 3.5, and images are `ceil(w/28)·ceil(h/28)` per Anthropic's vision docs.
+- Tool time excludes model thinking. Each extra call also costs a model turn in a real agent.
+- Windows-MCP's snapshot lists only interactive elements of the focused window, so reading the
+  calculator result needs a screenshot. Its failed rep missed the calculator in that snapshot.
+- Windows-MCP dropped rapid consecutive clicks. A 1 s pause between its clicks, not counted, mimics agent pacing.
+
+## Manual install
+
+Windows 10 2004+ / 11, Python 3.11+. To run the development version from GitHub with [uv](https://docs.astral.sh/uv/):
+
+```powershell
+uv tool install --compile-bytecode git+https://github.com/zredo19/winhands
+winhands setup
+```
+
+`winhands setup` registers the MCP server and installs the skill (perceive → batch → validate, game guidance, safety
+rules). To do those two steps yourself: `claude mcp add winhands --scope user -- winhands`, and copy
+[`winhands/SKILL.md`](winhands/SKILL.md) to `~/.claude/skills/winhands/SKILL.md`.
+
+Any MCP client works: the server command is just `winhands` (stdio). Set `WINHANDS_OVERLAY=0` to hide the
+overlay, `WINHANDS_LINGER=45` for how long it stays up between actions and `WINHANDS_SHARED=0` for strict mode. From source:
+`pip install -e .` in a venv, then point the client at `python -m winhands`.
+
+## Safety
+
+- **Ctrl + Left Alt + Q** aborts the running action. AltGr+Q still types `@`.
+- Shared mode (default): the user can keep working while a run acts through UIA patterns. Physical input
+  that collides with a run driving the real mouse/keyboard aborts it (`UserInterrupt`); real input waits for
+  the user to go idle first. The tool never fights the user for control. `WINHANDS_SHARED=0` restores strict mode.
+- The low-level keyboard/mouse hooks behind both features exist only while a `run` is acting. Nothing hooks
+  system input while the server idles in a Claude Code session.
+- Keys are only sent to a verified foreground target. All held keys and buttons are released on any abort.
+- `sh()` and clicks on elements named like Send, Buy, Pay, Delete, Install or Allow require `run(..., confirm=True)`.
+- Denylisted windows (password managers, banking) are refused.
+- `run` executes arbitrary Python: the same privilege as Claude Code's shell tool, gated by the client's permission prompts.
+- Online games with anti-cheat: automation may violate their terms and risk a ban. winhands makes
+  no attempt to hide or evade detection.
+
+## Limits
+
+- The harness makes a model faster and cheaper on the desktop. It does not make it smarter.
+- Reflex gameplay needs local loops written by the model, or pausing the game. Model round-trips take seconds.
+- Exclusive-fullscreen games may capture black; use borderless mode. Windows OCR skips isolated single
+  characters and glyphs touching strong borders. Template matching is exact-scale.
+- Elevated (admin) windows ignore input from a non-elevated server (Windows UIPI).
+
+## Tests
+
+```bash
+python -m pytest -q
+```

winhands-0.3.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77"]  # PEP 639: license = "MIT" as an SPDX string
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "winhands"
+version = "0.3.0"
+description = "Computer use MCP server for Windows: a11y tree + pixels, code mode, game-grade input"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Rodolfo Obreque" }]
+keywords = ["mcp", "mcp-server", "computer-use", "windows", "uiautomation", "claude", "claude-code", "ai-agents"]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=2.2",
+    "uiautomation>=2.0.29",
+    "mss",
+    "Pillow",
+    "numpy",
+    "pywin32",
+    "opencv-python-headless",
+    "winrt-runtime",
+    "winrt-Windows.Media.Ocr",
+    "winrt-Windows.Graphics.Imaging",
+    "winrt-Windows.Storage.Streams",
+    "winrt-Windows.Foundation",
+    "winrt-Windows.Foundation.Collections",
+    "winrt-Windows.Globalization",
+]
+
+[project.urls]
+Homepage = "https://github.com/zredo19/winhands"
+Repository = "https://github.com/zredo19/winhands"
+Issues = "https://github.com/zredo19/winhands/issues"
+
+[project.scripts]
+winhands = "winhands.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.setuptools]
+packages = ["winhands"]
+
+[tool.setuptools.package-data]
+winhands = ["SKILL.md"]

winhands-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

winhands-0.3.0/tests/test_cli.py

@@ -0,0 +1,181 @@
+import sys, pathlib, json, importlib
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+import pytest
+
+from winhands import cli
+
+EXE = r"C:\x\Scripts\winhands.exe"
+CLAUDE = r"C:\bin\claude.cmd"
+
+
+class Run:
+    """Fake subprocess.run: records argv, answers returncode per call index (default 0)."""
+    def __init__(self, *codes):
+        self.calls, self.codes = [], list(codes)
+
+    def __call__(self, cmd, **kw):
+        self.calls.append(list(cmd))
+        code = self.codes[len(self.calls) - 1] if len(self.calls) <= len(self.codes) else 0
+        return type("R", (), {"returncode": code})()
+
+
+def _which(**found):
+    return lambda name: found.get(name)
+
+
+@pytest.fixture(autouse=True)
+def no_real_warm_up(monkeypatch):
+    monkeypatch.setattr(cli, "_warm", lambda: None)       # the real one imports the whole server (seconds)
+
+
+def test_setup_warms_up_the_install_so_the_first_mcp_start_is_fast(tmp_path):
+    calls = []
+    cli.setup(home=tmp_path, which=_which(claude=CLAUDE), run=Run(), command=[EXE], out=lambda s: None,
+              warm=lambda: calls.append(1))
+    assert calls == [1]
+
+
+def test_warm_up_is_skipped_for_dry_run_and_remove(tmp_path):
+    def boom():
+        pytest.fail("warmed up")
+    for kw in ({"dry_run": True}, {"remove": True}):
+        assert cli.setup(home=tmp_path, which=_which(), run=Run(), command=[EXE], out=lambda s: None, warm=boom, **kw) == 0
+
+
+def test_a_failing_warm_up_never_fails_setup(tmp_path):
+    def boom():
+        raise RuntimeError("no display")
+    out = []
+    assert cli.setup(home=tmp_path, which=_which(claude=CLAUDE), run=Run(), command=[EXE], out=out.append, warm=boom) == 0
+    assert any("Warm-up skipped" in line and "no display" in line for line in out)
+
+
+def test_no_arguments_starts_the_server_and_never_builds_a_parser(monkeypatch):
+    import argparse
+    monkeypatch.setattr(argparse, "ArgumentParser", lambda *a, **k: pytest.fail("argparse touched"))
+    served = []
+    assert cli.main([], serve=lambda: served.append(1)) == 0
+    assert served == [1]
+
+
+def test_version_prints_the_package_version(capsys):
+    import winhands
+    assert cli.main(["--version"]) == 0
+    assert capsys.readouterr().out.strip() == f"winhands {winhands.__version__}"
+
+
+def test_package_version_falls_back_when_not_installed(monkeypatch):
+    import importlib.metadata as md
+    import winhands
+
+    def missing(name):
+        raise md.PackageNotFoundError(name)
+    monkeypatch.setattr(md, "version", missing)
+    importlib.reload(winhands)
+    try:
+        assert winhands.__version__ == "unknown"
+    finally:
+        monkeypatch.undo()
+        importlib.reload(winhands)
+    assert winhands.__version__ != "unknown"
+
+
+def test_skill_text_is_the_packaged_skill():
+    text = cli.skill_text()
+    assert text.startswith("---") and "name: winhands" in text
+
+
+def test_setup_registers_mcp_and_installs_skill(tmp_path):
+    run, out = Run(), []
+    assert cli.setup(home=tmp_path, which=_which(claude=CLAUDE), run=run, command=[EXE], out=out.append) == 0
+    assert run.calls == [[CLAUDE, "mcp", "remove", "winhands", "--scope", "user"],
+                         [CLAUDE, "mcp", "add", "winhands", "--scope", "user", "--", EXE]]
+    skill = tmp_path / ".claude" / "skills" / "winhands" / "SKILL.md"
+    assert skill.read_text(encoding="utf-8") == cli.skill_text()
+    assert any("Restart Claude Code" in line for line in out)
+
+
+def test_setup_is_idempotent_when_remove_fails(tmp_path):
+    run = Run(1, 0)                                    # the entry did not exist yet: remove fails, add works
+    assert cli.setup(home=tmp_path, which=_which(claude=CLAUDE), run=run, command=[EXE], out=lambda s: None) == 0
+    assert len(run.calls) == 2
+
+
+def test_setup_reports_a_failed_add(tmp_path):
+    out = []
+    run = Run(0, 3)
+    assert cli.setup(home=tmp_path, which=_which(claude=CLAUDE), run=run, command=[EXE], out=out.append) == 1
+    assert any("claude mcp add" in line for line in out)
+
+
+def test_setup_without_claude_prints_the_json_snippet(tmp_path):
+    out = []
+    run = Run()
+    assert cli.setup(home=tmp_path, which=_which(), run=run, command=[EXE], out=out.append) == 0
+    assert run.calls == []
+    blob = next(line for line in out if line.lstrip().startswith("{"))
+    assert json.loads(blob) == {"mcpServers": {"winhands": {"command": EXE}}}
+    assert (tmp_path / ".claude" / "skills" / "winhands" / "SKILL.md").is_file()
+
+
+def test_snippet_carries_args_for_the_python_dash_m_fallback(tmp_path):
+    out = []
+    cli.setup(home=tmp_path, which=_which(), run=Run(), command=[r"C:\py\python.exe", "-m", "winhands"], out=out.append)
+    blob = next(line for line in out if line.lstrip().startswith("{"))
+    assert json.loads(blob)["mcpServers"]["winhands"] == {"command": r"C:\py\python.exe", "args": ["-m", "winhands"]}
+
+
+def test_setup_dry_run_changes_nothing(tmp_path):
+    out = []
+    assert cli.setup(dry_run=True, home=tmp_path, which=_which(claude=CLAUDE),
+                     run=lambda *a, **k: pytest.fail("ran a command"), command=[EXE], out=out.append) == 0
+    assert list(tmp_path.iterdir()) == []
+    assert any("dry run" in line.lower() for line in out)
+
+
+def test_remove_unregisters_and_deletes_the_skill(tmp_path):
+    d = tmp_path / ".claude" / "skills" / "winhands"
+    d.mkdir(parents=True)
+    (d / "SKILL.md").write_text("x", encoding="utf-8")
+    run = Run()
+    assert cli.setup(remove=True, home=tmp_path, which=_which(claude=CLAUDE), run=run, command=[EXE],
+                     out=lambda s: None) == 0
+    assert run.calls == [[CLAUDE, "mcp", "remove", "winhands", "--scope", "user"]]
+    assert not d.exists()
+
+
+def test_remove_is_fine_with_nothing_installed_and_no_claude(tmp_path):
+    assert cli.setup(remove=True, home=tmp_path, which=_which(), run=Run(), command=[EXE], out=lambda s: None) == 0
+
+
+def test_main_passes_setup_flags_through(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(cli, "setup", lambda **kw: seen.update(kw) or 7)
+    assert cli.main(["setup", "--remove", "--dry-run"]) == 7
+    assert seen == {"remove": True, "dry_run": True}
+    assert cli.main(["setup"]) == 7
+    assert seen == {"remove": False, "dry_run": False}
+
+
+def test_unknown_command_is_an_argparse_error():
+    with pytest.raises(SystemExit) as e:
+        cli.main(["bogus"])
+    assert e.value.code == 2
+
+
+def test_command_is_the_running_executable_when_it_is_winhands():
+    got = cli.command_for(argv0=EXE, which=_which(winhands=r"C:\other\winhands.exe"),
+                          executable=r"C:\py\python.exe", isfile=lambda p: True)
+    assert got == [EXE]
+
+
+def test_command_falls_back_to_path_then_scripts_dir_then_python_dash_m():
+    py = r"C:\py\python.exe"
+    other = r"C:\other\winhands.exe"
+    # `python -m winhands`: argv0 is the package's __main__.py, not the executable
+    assert cli.command_for(argv0=r"C:\p\winhands\__main__.py", which=_which(winhands=other),
+                           executable=py, isfile=lambda p: True) == [other]
+    scripts = str(pathlib.Path(py).parent / "winhands.exe")
+    assert cli.command_for(argv0="x", which=_which(), executable=py, isfile=lambda p: p == scripts) == [scripts]
+    assert cli.command_for(argv0="x", which=_which(), executable=py, isfile=lambda p: False) == [py, "-m", "winhands"]