Documentation Index
Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt
Use this file to discover all available pages before exploring further.
Cua Driver supports Windows, macOS, and Linux. Support is defined by observed behavior in a real application against canonical Rust harness tests — not by whether a tool call returned a success code. The exact delivery route depends on the operating system, window system, application toolkit, action requested, and whether the target window may be brought to the foreground.
Support Levels
| Level | Meaning |
|---|
| Supported | A canonical Rust harness test proves the result against application-owned or desktop-owned state. |
| Supported with limits | Common paths are proven, but the platform or window system cannot safely provide every delivery shape. Unsupported paths return a structured refusal. |
| Experimental | The backend exists, but representative coverage is incomplete. Do not assume unlisted actions work. |
| Platform | Window system and automation APIs | Current state |
|---|
| Windows | Win32, UI Automation (UIA), native input, and targeted window messages | Supported. Canonical coverage includes Electron, Tauri, WPF, WinUI 3, and WebView2. Some background Chromium gestures and elevated-integrity boundaries remain unavailable or unproven. |
| macOS | AppKit, Accessibility (AX), Quartz/HID, and ScreenCaptureKit | Supported. Canonical coverage includes Electron, Tauri, AppKit, SwiftUI, and WKWebView. Accessibility and Screen Recording permissions are required. Some background scroll and drag shapes return structured refusals. |
| Linux X11 | X11/EWMH, XTest, AT-SPI, and toolkit accessibility bridges | Supported with toolkit-specific limits. Foreground input and semantic background actions are broadly covered. Toolkits that reject synthetic background events receive an explicit refusal instead of a silent success. |
| Linux Wayland | AT-SPI plus compositor-specific discovery, capture, activation, and portal input | Supported with compositor-specific limits. Semantic background actions work where the application exposes them. Raw input cannot generally be sent to an arbitrary occluded surface. |
Wayland portal grants belong to the compositor/runtime scope that issued them. Do not treat a successful portal grant as a durable credential that migrates to a later process generation.
macOS Requirements
macOS attributes Accessibility and Screen Recording grants to a responsible app identity. Use one of these supported launch modes:
- Standalone (recommended): Install
CuaDriver.app, grant permissions to it, start its daemon with open -n -g -a CuaDriver --args serve.
- Explicit direct MCP:
cua-driver mcp --direct makes the MCP process own its runtime, using the spawning host’s TCC attribution.
# Check permission status
cua-driver permissions status
# Request both Accessibility and Screen Recording
cua-driver permissions grant
Windows Capabilities
Cua Driver on Windows runs as a user-space process with no elevated privileges required for most automation.
| Capability | State |
|---|
| Window discovery and enumeration | Supported |
| UIA semantic actions | Supported |
| Keyboard injection | Supported |
| Mouse injection | Supported |
| Screenshot (per-window and desktop) | Supported |
| Background keyboard/mouse | Supported |
| Background Chromium gestures | Supported with limits |
| Elevated-integrity process targets | Not supported |
Linux Window Systems
| Environment | State | What is proven | Main limits |
|---|
| X11/Xorg | Supported | Window discovery, AT-SPI trees, foreground pointer/keyboard input, semantic background delivery, desktop scope | Raw background delivery depends on target toolkit |
| Sway (wlroots) | Supported with limits | Complete typed Electron, Tauri, GTK, capture, and desktop-scope catalog | Focus-bound raw background shapes return structured refusals |
| GNOME/Mutter | Supported with limits | AT-SPI actions, GTK controls, compositor-backed capture, portal/libei foreground input | WinRects Shell helper is a prerequisite; portal video recording incomplete |
| KDE/KWin | Experimental | Plasma 6 startup, GTK AT-SPI discovery, portal interface availability | No target-addressable KWin activation adapter yet |
cua-compositor nested session | Experimental | Native GTK behavior, capture and scope, private route metadata, independent observation, and per-cell video | The complete shared renderer matrix is not accepted. Unicode text and a canonical parallel-drag row remain unproven; this route does not establish a stock-Wayland capability. |
| XWayland | Supported with limits | X11 routes where the app exposes a real X11 window | Depends on whether the app uses X11 or native Wayland |
A structured background_unavailable or background_occluded result is part of the contract. It means Cua Driver refused an unsafe or unsupported route before disturbing the user’s active desktop. It is not a silent success — handle it in your agent loop.
(pid, window_id) binding.
| Surface | Proven routes | Explicit limit |
|---|
| Standalone Chrome and Edge on Windows | Snapshot, navigation, ref-bound typing, trusted background click, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Elevated-integrity and unsupported native-host relationships still refuse |
| Standalone Chrome on macOS | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns browser_input_trust_unavailable before dispatch |
| Standalone Chrome and Edge on Linux X11 | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, foreground JavaScript-dialog resolution, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input and background JavaScript-dialog resolution return browser_input_trust_unavailable before dispatch |
| Electron on Windows, macOS, X11, and validated Sway | Typed mutation while one proven native window maps to one CDP page | A second page or native window invalidates the bounded exact route |
| Tauri, WKWebView, WebKitGTK, and common split-process WebView2 | Browser identity plus a side-effect-free structured refusal | No exact native-host-to-engine relationship is currently proven |
| Safari and Firefox | Native discovery and native AX/PX fallbacks | No typed browser mutation engine is currently advertised |
Version Notes
This reference is documented against Cua Driver 0.19.3. Run cua-driver --version to confirm your installed version.
See Permission Modes for how to configure standard, bounded, or unrestricted access tiers. See MCP Tools for the full list of 54 automation tools. 