What makes Cua Driver notable?

1K downloads. Trust evidence available

How should Cua Driver be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

Cua Driver

Drive a native GUI app (macOS, Windows, Linux) via the cua-driver CLI (default) or MCP server; snapshot its accessibility tree, click/type/scroll by element_...

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.0k

Updated

Oct 11, 2026

Version

0.11.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 11, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 11, 2026
Adoption signal: 1K downloadsadoption · observed Oct 11, 2026
Latest release: 0.11.0release · observed Jul 22, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s171gssydc5ytdy8eyx7gtamy58an1mk:driver

Install using `clawhub skill install s171gssydc5ytdy8eyx7gtamy58an1mk:driver` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/cua/driver before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-cua-driver/snapshot"

Run-check

$0.02 USD

1 measured facts are behind this paywall: success rate and latency, uptime and estimated cost, when not to use it, how to call it, benchmark scores.

Agents pay $0.02 in USDC. A card payment is $0.50, the smallest a card allows.

Documentation

CLAWHUB

141,066 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: cua-driver
description: Drive a native GUI app (macOS, Windows, Linux) via the cua-driver CLI (default) or MCP server; snapshot its accessibility tree, click/type/scroll by element_index or pixel coordinates, and verify via re-snapshot without bringing the target to the foreground. Use when the user asks you to operate, drive, automate, or perform a GUI task in a real application on the host.
version: 0.11.0 # x-release-please-version
metadata:
  openclaw:
    requires:
      bins:
        - cua-driver
    envVars:
      - name: CUA_DRIVER_EMBEDDED
        required: false
        description: Set to 1 when a macOS host app launches the driver in embedded mode.
      - name: CUA_DRIVER_HOST_BUNDLE_ID
        required: false
        description: Bundle identifier of the macOS host app in embedded mode.
      - name: CUA_DRIVER_PATH
        required: false
        description: Optional path to a cua-driver binary used by an embedding host.
      - name: CUA_DRIVER_RS_ENABLE_WAYLAND
        required: false
        description: Set to 1 to enable the native Wayland backend.
      - name: CUA_DRIVER_RS_MCP_HTTP_PORT
        required: false
        description: Optional port for the local MCP HTTP endpoint.
    homepage: https://cua.ai/docs/cua-driver
---

# cua-driver

Orchestrates cross-platform app automation via `cua-driver`. Whenever
a user asks to drive a native app, follow the loop in this skill
rather than calling tools ad-hoc — the snapshot-before-action
invariant is not optional and silently breaks if you skip it.

## Platform-specific reading — read this first

This file is the **cross-platform core**: snapshot invariant, CLI vs
MCP choice, tool surface naming, behavior matrix, canonical loop,
pixel-click contract, common failure modes. The platform-specific
material (forbidden-list, accessibility tree implementation, launch
semantics, click dispatch) lives in companion files in this same
directory:

- **macOS** — read `MACOS.md` (no-foreground contract, forbidden
  `open`/`osascript`/`cliclick` invocations, AXMenuBar navigation,
  SkyLight pixel-click dispatch).
- **Windows** — read `WINDOWS.md` (UIA tree vs AX, UWP /
  ApplicationFrameHost hosting, layered UIA+PostMessage click chain,
  Session 0 isolation, Windows-specific focus-steal vectors).
- **Linux** — read `LINUX.md` (X11 background input via AT-SPI +
  XSendEvent and compositor-specific Wayland capabilities).

Cross-cutting topics also have their own files:

- `BROWSER.md` — exact native-window binding, explicit browser preparation,
  typed Chromium/Electron page tools, input trust classes, and native
  fallbacks for browser chrome and unsupported engines.
- `RECORDING.md` — session recording + `replay_trajectory`.

Use whichever combination matches the host. When in doubt, run
`cua-driver doctor` — it reports the platform and the right entry
point.

## The no-foreground principle (window phase)

In a strict `window` session, and during the initial window phase of an
`aut

README.md

# Cua Driver agent skill

This cross-agent skill teaches an AI agent to operate native applications on
macOS, Windows, and Linux with the
[`cua-driver`](https://github.com/trycua/cua/tree/main/libs/cua-driver/rust)
CLI or MCP server.

It covers the canonical snapshot-action-verify loop, exact window addressing,
accessibility and pixel actions, background/foreground delivery, typed browser
automation, session recording, and platform-specific limitations. The skill
defaults to background delivery and requires structured refusal or observed
failure before a caller escalates to foreground input.

## Install Cua Driver

macOS or Linux:

```bash
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
```

Windows PowerShell:

```powershell
irm https://cua.ai/driver/install.ps1 | iex
```

Then verify the current host:

```bash
cua-driver doctor
```

On macOS, the installed `CuaDriver.app` needs Accessibility and Screen
Recording permission. On Windows, the daemon must run in an interactive user
desktop rather than Session 0. On Linux, the daemon must share the graphical
session and AT-SPI session bus.

## Install the skill

From ClawHub:

```bash
clawhub install @cua/driver
```

Or let the installed driver add the version-matched skill to detected agent
directories:

```bash
cua-driver skills install
```

The direct installer keeps only the current host's platform guide by default.
Use `--all-platforms` when the agent assists users across operating systems.
`cua-driver skills update` refreshes the pack to match a later driver release.

## Reading order

- `SKILL.md`: shared contract, tool selection, session identity,
  snapshot-action-verify loop, action ladder, and failure handling.
- `MACOS.md`, `WINDOWS.md`, or `LINUX.md`: host-specific launch, capture,
  accessibility, input delivery, permissions, and refusal boundaries.
- `BROWSER.md`: exact browser-window binding, explicit profile preparation,
  page refs, trust-classified click/type/navigation, and native fallbacks.
- `RECORDING.md`: trajectory evidence, MP4 capture, and replay.
- `EMBEDDING.md`: embedding the driver into another host application.

The agent should load `SKILL.md`, the current platform guide, and only the
cross-cutting guide needed for the task.

## Browser model

Browser work starts from the same native `(pid, window_id)` selection as every
other app. `get_browser_state` binds that exact window to a session-scoped
target and tab, then returns short-lived page refs for `browser_click`,
`browser_type`, and `browser_navigate`.

Setup is never a hidden read side effect. `browser_prepare` requires explicit
approval before launching a driver-managed profile or attaching to an existing
authenticated profile. Trusted pointer input and synthetic DOM clicks are
reported as different routes; the driver refuses instead of silently changing
trust class or foregrounding a standalone browser.

See `BROWSER.md` for the supported surface and exact recovery rules.

## Recording

Session rec

_meta.json

{
  "ownerId": "kn76076s7aaqc397ewg4xf682h8amc2s",
  "slug": "driver",
  "version": "0.11.0",
  "publishedAt": 1784758318708
}

BROWSER.md

# Browser automation

Use this guide for page content in Chromium-family browsers and Electron.
Browser chrome, permission prompts, downloads, file pickers, and unsupported
engines remain native windows: inspect and operate them with
`get_window_state` and the normal AX/PX action ladder in `SKILL.md`.

## Choose the page-aware route first

For supported page content, prefer the typed browser tools over the legacy
`page` tool, accessibility guesses, omnibox shortcuts, or raw pixels. The
typed route binds an exact native `(pid, window_id)` to a browser target and
mints session-scoped tab and element capabilities.

The canonical loop is:

```text
start_session
list_windows or launch_app
get_browser_state(pid, window_id, session)       # bind
get_browser_state(target_id, tab_id, session,
                  snapshot_format=semantic_v2)  # snapshot
browser_navigate / browser_click / browser_type / browser_pointer
browser_dialog / browser_set_input_files / browser_download
get_browser_state(target_id, tab_id, session,
                  snapshot_format=semantic_v2)  # verify and refresh refs
end_session
```

Use one explicit `session` value throughout. Never substitute a raw CDP
target id, tab ordinal, URL match, or remembered ref for a capability returned
by `get_browser_state`.

## 1. Select an exact native window

Start or discover the app with the native tools and select one returned
`window_id`:

```bash
cua-driver start_session '{"session":"browser-run-1"}'
cua-driver list_windows '{"pid":4242}'
cua-driver get_browser_state \
  '{"pid":4242,"window_id":991,"session":"browser-run-1"}'
```

Continue to mutation only when the bind result reports:

- `status: "ok"`;
- `binding_quality: "exact"`; and
- `mutation_allowed: true`.

A heuristic title match is read-only. Same-bounds windows, stale native
geometry, a moved tab, process restart, endpoint-owner mismatch, or any other
ambiguity must be re-bound or refused. Do not pick another window because its
title looks close.

## 2. Prepare only when the bind requests setup

`get_browser_state` is strictly read-only. It never launches a browser,
changes a profile, enables remote debugging, or accepts a consent prompt. If
it returns `browser_requires_setup`, choose one explicit preparation flow.

### Driver-owned isolated profile

Prefer an isolated profile when the task does not need the user's existing
cookies or login state:

```bash
# Direct CLI/raw clients mint this token interactively. MCP hosts can use their
# destructive-tool approval flow instead.
cua-driver browser-approve --pid 4242 --profile-mode isolated_new

cua-driver browser_prepare \
  '{"pid":4242,"session":"browser-run-1","allow_launch":true,
    "profile":{"mode":"isolated_new"},"approval_token":"<token>"}'
```

Use `isolated_named` with a path-safe `name` for a reusable driver-managed
profile. Preparation launches a separate browser and never copies, modifies,
or terminates the requested personal profile. The result returns a
`prepared_pid

EMBEDDING.md

# Embedding cua-driver in your application without introducing new permissions

This guide is for teams shipping a macOS app (an "agent harness") that wants
cua-driver's background computer-use and agent-cursor overlay **inside their
own app**, without shipping a second app bundle and without their users ever
seeing a second macOS permission prompt. Your app requests Accessibility and
Screen Recording once; the embedded driver inherits those grants.

A working daemon-host reference lives in the cua repo at
`libs/cua-driver/rust/examples/embedded-host-macos/`
(https://github.com/trycua/cua). This doc ships standalone in the skill
pack, so the path is given rather than a relative link.

## How macOS attributes these permissions (what you must know)

macOS TCC (the privacy system behind System Settings → Privacy & Security)
does not attribute Accessibility or Screen Recording to an executable path.
It attributes them to the **responsible process**: the app at the top of the
process's launch chain, as tracked by the kernel/LaunchServices. When your
signed app spawns a child with `posix_spawn`, `NSTask`/`Process`, or plain
`fork`/`exec`, that child stays inside *your* responsibility chain — TCC
checks made by the child are answered with **your app's** grants, and any
prompt it triggered would name **your app**. This is exactly the behavior
embedding relies on: grant once to the host, and every well-behaved child
inherits. (Apple documents the attribution chain; you can watch it live with
`log stream --debug --predicate 'subsystem == "com.apple.TCC" AND eventMessage BEGINSWITH "AttributionChain"'`.)

Two things break the chain, and both are things the embedded driver must
*not* do (and, in embedded mode, does not do). First, launching via
LaunchServices (`open -a …`, `NSWorkspace.open`) makes the launched app its
own responsible process. Second, a process can explicitly *disclaim*
responsibility for a child (`responsibility_spawnattrs_setdisclaim`), making
the child its own responsible process — standalone cua-driver does this on
purpose so its permissions attach to a stable `com.trycua.driver` identity
instead of whatever terminal launched it. Embedded mode turns that off.

Note this is TCC **responsibility** inheritance — it is unrelated to App
Sandbox inheritance (`com.apple.security.inherit`). This guide assumes a
non-sandboxed host, which is typical for agent harnesses; a sandboxed host
spawning a non-sandboxed helper raises separate App Sandbox questions that
embedded mode does not address.

## Preferred application SDK: same-process runtime

Python and TypeScript applications should normally import the packaged SDK and
create `CuaDriver` directly. This path does not start an executable or open a
socket, and TCC checks execute as the importing application:

```ts
import { CuaDriver } from '@trycua/cua-driver';

const driver = CuaDriver.create(undefined);
try {
  const metadata = await driver.metadata();
  // Invoke typed driver operations here.
}

Github ReposUpdated 2d agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.