AI Hands

AI-Hands — Multi-Layer Desktop Automation for AI Agents

[](https://github.com/AIWander/AI-Hands/actions/workflows/ci.yml)

AI-Hands is a Rust MCP (Model Context Protocol) server that gives AI agents full desktop control through three automation tiers — not just pixel-guessing from screenshots.

> Renamed from AIWander/hands on 2026-05-15. Same Rust codebase, fresh versioning. The hands.exe binary name and hands:* MCP tool prefix are unchanged — existing MCP configs in Claude Desktop, Claude Code, Cowork, Codex CLI, Gemini CLI, and LM Studio keep working without edits.

See the [examples/](examples/) directory for sample configurations and walkthroughs.

Part of CPC (Copy Paste Compute) and the free core trio with Voice-Command and Programmer-Wander. Related repo: manager-universal (manager/dashboard Beta and coming soon)

Safe Use / Permission Model

AIWander tools are local, user-authorized MCP capability surfaces. They do not grant an AI new permissions by themselves. They expose tools the user explicitly installs and enables. Sensitive actions should be confirmed by the user, credentials should stay in the OS keyring or local vault, and demos should use mock data.

What's New in v1.1.0-unified.2 (preview)

• Ability-first union: the public and locally proven Hands surfaces are merged by capability, not by keeping every historical name. The safe default profile exposes 104 operational tools plus hands_capability_catalog; safe full and strict profiles and an explicitly unsafe compatibility/debug profile are selected through HANDS_TOOL_PROFILE.
• Central monitor boundary: hands_monitor_scope lists displays and applies one fail-closed scope across coordinate, UIA, browser-binding, screenshot, OCR, QR, and plugin paths. A locked physical stable ID is the recommended unattended setting.
• Collision-resistant screenshots: automatic filenames include sub-second time, process ID, and a per-process sequence so same-second and concurrent captures do not overwrite one another.
• Optional plugin package: Codex and Claude-compatible manifests, ability-routed skills, per-host instructions, and inert opt-in hook templates live under [plugins/ai-hands/](plugins/ai-hands/). They do not silently edit host configuration.
• Windows installer source: the Inno package stages the matching Rust binary, plugin, skills, and guide. PATH is selectable; AI and hook configuration remains user-controlled.

The machine-readable capability inventory and replacement map are in [manifest/unified_hands_manifest.json](manifest/unifiedhandsmanifest.json).

v1.0.1 — security dependency update

• openssl 0.10.78 to 0.10.79 resolved GHSA-xp3w-r5p5-63rr and GHSA-xv59-967r-8726. rqrr 0.7 to 0.10 brought lru 0.16.4 and resolved GHSA-rhfx-m35p-ff5j.

v1.0.0 — AI-Hands launch

• New tool: vision_screenshot_hidden_window — always-PrintWindow API captures a window's pixels without bringing it to the foreground. Replaces the behind=true mode of window_screenshot.
• window_title parameter on hands_capture — focus a named window via UIA before routing the capture.
• offset_x/offset_y on hands_click — when non-zero, every rung of the 7-rung click ladder resolves the element by its native method then coord-clicks at bbox.center + offset. When both zero, ref/selector click is preserved on rungs 1-4 for reliability.
• Deprecation markers on find_and_click, retry_click, read_screen_text, type_into_window (handlers preserved for backward compat), and window_screenshot (default mode).

The entries below are pre-rename AIWander/hands lineage notes kept for context; AI-Hands restarted public release numbering at v1.0.0 on 2026-05-15.

v1.3.4

• ci: bump GitHub Actions versions to latest (Node.js 20 deprecation)

v1.3.3

• Phase D: compile-time ZST AtomicTool dispatch — Replaced all runtime string-based UIA tool dispatch in meta-tools with zero-sized-type (ZST) AtomicTool handles resolved at compile time. 11 UIA tools wrapped. 7 meta-tool files refactored. 27 call sites replaced.
• src/atomic.rs — New module defining the AtomicTool trait and ZST wrappers for all UIA tools.
• Browser compatibility module — Optional browser compatibility adjustments for authorized automation testing.

v1.3.2

• Clippy + dead_code + unused cleanup — 3 crate-level allows removed, 60+ targeted allows added with justification, 22 supplemental mechanical fixes in src/meta/*

v1.3.1

• HTTP dashboard endpoint migrated to tiny_http (smaller binary, simpler stack)
• Duration tracking for tool calls in dashboard status
• Best-effort credential-pattern redaction in dashboard output
• Field name alignment across dashboard JSON responses
• Metadata cleanup and documentation fixes

Previous releases

v1.3.0 (2026-04-16) — Path deps to git tags, Cargo.lock committed, README license metadata aligned to Apache-2.0, version sync. First version that builds as standalone public clone.

v1.2.2 — Phase C Fix3: meta-tool dispatch, async Send bound, notify parity.

v1.2.1 — Phase C fixes, meta-tool dispatch improvements.

v1.1.1 — Initial public release with 71 MCP tools across 3 automation tiers.

Install

> winget submission pending. The microsoft/winget-pkgs PR is in flight — once it merges, winget install AIWander.AI-Hands works against the published index. Until then, [installers/winget/manifests/](installers/winget/manifests/) in this repo is the source of truth (use the --manifest form below). The manual download path is unaffected.

Option A — optional plugin installer (v1.1 preview)

Use the installer asset that matches your architecture, or compile it from source after building hands.exe:

installers\inno\build-installer.bat C:\path\to\hands.exe arm64
rem For x64, use x64compatible as the second argument.

The interactive installer stages hands.exe, the plugin, skills, opt-in hook templates, prerequisites, and a per-AI application guide. It offers current-user PATH setup but does not edit Codex, Claude, Grok, ChatGPT, MCP, or hook configuration. It attempts to copy the guide to the clipboard and reports success or directs you to the installed file if Windows denies clipboard access. Chrome or Chromium remains a separate prerequisite for the browser layer. See [installers/inno/PREREQUISITES.txt](installers/inno/PREREQUISITES.txt).

Option B — winget (recommended once the PR lands)

winget install AIWander.AI-Hands
# Until the upstream PR lands, install from this repo's manifest directly:
# winget install --manifest https://raw.githubusercontent.com/AIWander/AI-Hands/main/installers/winget/manifests/a/AIWander/AI-Hands/1.0.1/AIWander.AI-Hands.installer.yaml

# Then wire it into Claude Desktop (writes a timestamped .bak first):
.\installers\scripts\register-hands.ps1

Open a new shell after the install so winget's portable-shim directory (%LOCALAPPDATA%\Microsoft\WinGet\Links) is on PATH, then run the registration script. See [installers/README.md](installers/README.md) for -Force / -DryRun flags and rollback.

Option C — Scoop

# Direct URL (no bucket required):
scoop install https://raw.githubusercontent.com/AIWander/AI-Hands/main/installers/scoop/ai-hands.json

# Then register with Claude Desktop:
.\installers\scripts\register-hands.ps1

Option D — Manual download (always works)

1. Download from the latest release:

• Windows x64 → hands-vX.Y.Z-x64.exe
• Windows ARM64 (Snapdragon X / X Elite / X Plus) → hands-vX.Y.Z-aarch64.exe

1. Rename to hands.exe and place in %LOCALAPPDATA%\CPC\servers\.
2. Add to claude_desktop_config.json:

``json { "mcpServers": { "hands": { "command": "%LOCALAPPDATA%\\CPC\\servers\\hands.exe" } } } ``

1. Restart Claude Desktop.

ARM64 note: the binary uses native ARM64 UIA bindings — no x64 emulation. If you previously ran the x64 build under emulation, swap to aarch64 for ~3-4x faster screenshot/OCR throughput.

---

Prerequisites

• Windows 10/11 (x64 or ARM64)
• Chrome installed normally (any recent version). AI-Hands does not download or manage browser binaries — it talks to your existing Chrome over CDP.
• Claude Desktop or any MCP-compatible client
• Optional compatibility/debug-only browser_js_extract parser: Node.js plus linkedom or jsdom; safe-profile CDP browser tools do not require Node.js.

For full per-machine setup (paths, skills, credentials), see [docs/per_machine_setup.md](./docs/permachinesetup.md).

---

Why AI-Hands?

Renamed from AIWander/hands on 2026-05-15. Codebase, binary name, and MCP tool prefix are unchanged.

Anthropic's Claude Computer Use takes screenshots and clicks pixel coordinates. It works, but it's slow (screenshot after every action), imprecise (guessing where to click), and blind (no DOM, no accessibility tree, no structured data).

AI-Hands takes a different approach: use the right automation layer for each task.

| Layer | What it does | When to use it | |-------|-------------|---------------| | Browser (chromiumoxide CDP) | Structured visible DOM, minimized and pattern-redacted network observation, form interaction, multi-tab | Web apps, current-state reading, testing | | UIA (Win UI Automation) | Accessibility tree, named elements, window management, app launch | Native Windows apps | | Vision (OCR + template match) | Screenshot, OCR, image diff, visual analysis | Anything else, verification |

Comparison

AI-Hands is a capability surface — a local MCP server that lets your chosen AI model (Claude, GPT, Gemini, local LLM) drive your browser, Windows apps, and screen. It does not bundle an AI; you bring the model. The tables below set that apart from (1) other BYOM capability surfaces and (2) AI-bundled computer-use products. This comparison is a May 2026 snapshot; verify third-party pricing, availability, and benchmarks before relying on them.

vs. other BYOM capability surfaces

| | AI-Hands | Playwright MCP | |---|---|---| | Runtime | Single Rust binary (hands.exe) | Node.js + Playwright runner | | Procs per session | 1 | 18+ (Node procs + workers) | | RAM per session (measured) | ~184 MB | ~320 MB (5.83× heavier full-stack) | | Browser control | CDP attach to your existing Chrome | Spawns its own Chromium | | Persistent auth | YOUR logins, YOUR cookies | Fresh browser each session | | DOM access | Yes, via CDP | Yes, via Playwright API | | Native Windows UIA | Yes | No | | Vision/OCR (local) | Yes, local OCR | No, DOM only | | file:// protocol | Yes | No, blocked by default | | Screenshot save path | any | restricted to .playwright-mcp and C:\ | | Smart cross-tier routers | Yes; hands_click runs a 7-rung ladder (a11y → fuzzy → CSS → snapshot refresh → clickables → UIA → OCR) under one tool entrypoint | No; pick the primitive yourself | | Chain depth | Claude → hands.exe → Chrome (2 hops) | Claude → Node MCP → Playwright API → Chrome (3 hops) |

Per-session memory measured side-by-side loading example.com with the same Chrome attached.

vs. AI-bundled computer-use products

These bundle a specific AI model with their own UI surface. AI-Hands does neither — it gives your model a surface.

| | AI-Hands + your model | Claude Computer Use | OpenAI Operator (CUA) | Google Mariner / Gemini Agent | Perplexity Comet | |---|---|---|---|---|---| | Surface | Your Chrome + your Windows apps | Anthropic-hosted VM or your container | OpenAI-hosted browser sandbox | Chrome extension in your browser | Standalone Chromium-based browser | | Cost (May 2026) | ~$0 marginal (BYOM) | API or Claude subscription | ChatGPT Pro $200/mo, or API $3/$12 per 1M tokens (research preview, tiers 3-5) | Free w/ Google account (Mariner-standalone shut down May 4, 2026; capabilities folded into Gemini Agent) | Free since Mar 18, 2026; Comet Plus +$5/mo | | Privacy | All local; your model provider sees what you send it | Anthropic sees screen pixels | OpenAI sees screen pixels | Google sees browser actions; you stay logged in | Perplexity sees pages; you stay logged in | | DOM access | Yes | No (pixel only) | No (pixel only) | Yes (extension API) | Yes (native) | | Native app / UIA | Yes, Windows | Yes (full OS sandbox) | No (browser only) | No (browser only) | No (browser only) | | Vision/OCR | Yes, local OCR | implicit (vision model) | implicit (vision model) | implicit | implicit | | Element identification | CSS, XPath, UIA names, a11y tree, OCR text, template match | Screenshot → guess coordinates | Screenshot → guess coordinates | DOM + screenshot | DOM + screenshot | | Persistent auth | YOUR Chrome cookies (via debug-port attach) | sandbox VM cookies | sandbox VM cookies | YOUR Chrome | OWN browser, OWN profile | | Local memory | ~184 MB | 0 (remote) | 0 (remote) | ~50-100 MB ext + browser | 500+ MB (full browser app) | | Bring your own model | Yes, any | No, Claude only | No, OpenAI only | No, Gemini only | No, Perplexity model stack | | OSWorld benchmark | n/a (capability layer) | varies by Claude model | 38.1% (CUA in research preview) | n/a post-shutdown | n/a (browser-only) | | Public availability | v1.0.1 (this repo) | GA | Research preview API; ChatGPT Pro UI | Standalone shut down May 4 2026; lives inside Gemini Agent / Chrome Auto-Browse | Public, free, Windows + macOS |

TL;DR

• AI-Hands wins on capability surface (DOM + UIA + Vision in one binary) and local resource cost (~5.8× lighter than Playwright MCP).
• Bundled-AI products win on plug-and-play onboarding (no model selection, no setup) but lock you into one provider and surrender screen contents to them.
• If you already pay for a Claude / GPT / Gemini API subscription, AI-Hands lets you reuse that model with full DOM + native-app reach for ~$0 marginal cost.

Ability profiles and collections

The safe-advertised profiles are default with 104 operational tools plus hands_capability_catalog (105 tools/list entries), full with 106 plus the catalog (107 entries), and strict with 108 plus the catalog (109 entries). compatibility exposes all 143 canonical union tools plus the catalog (144 entries), including unsafe raw/debug and native-plugin capabilities. Exact duplicate registrations and three Workflow-owned recording front doors are not retained.

| Ability collection | Default operational tools | |---|---:| | Browser sessions, navigation, and contexts | 21 | | DOM and page-state discovery | 5 | | Browser interaction and forms | 11 | | Web retrieval, crawling, and page artifacts | 3 | | API and network intelligence | 12 | | Browser evaluation, waits, and evidence | 7 | | Browser batching, planning, and agentic execution | 3 | | Desktop apps, windows, input, and UIA | 17 | | Vision, OCR, and visual perception | 13 | | Unified cross-surface actions and verification | 8 | | Run telemetry | 1 | | Monitor scope and topology | 1 | | Extensions, runtime, and health | 2 | | Operational total | 104 |

Keep HANDS_TOOL_PROFILE=default unless a specific safe capability requires full or strict. All three are safe-advertised. The compatibility profile is an unsafe debug escape hatch, not a faster operating mode. Its raw/direct-fetch/value/trace/QR/event/native-plugin tools require three explicit gates: HANDS_TOOL_PROFILE=compatibility, the matching process gate (HANDS_ALLOW_UNSAFE_RAW_TOOLS=1, HANDS_ALLOW_UNSAFE_DIRECT_FETCH=1, or HANDS_ALLOW_UNSAFE_PLUGINS=1

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AIWander
• Source: AIWander/AI-Hands
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.